Difference between revisions of "MATLAB Interface"

From BESA® Wiki
Jump to: navigation, search
 
(17 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
{{BESAInfobox
 +
|title = Module information
 +
|module = BESA Research Basic or higher
 +
|version = BESA Research 6.1 or higher
 +
}}
  
 +
= Introduction =
  
= MATLAB Interface =
+
BESA Research has menu items ''"Send to MATLAB..."'' at various locations that allow to send data as structures to MATLAB. After sending the data, BESA Research starts a MATLAB script that can be used to start further data analysis on the data structure. These scripts, located in the ''Scripts\Matlab'' folder in the BESA Research installation, can be edited by the user to perform further data analysis in MATLAB. For example, if "''Send to MATLAB''" is selected in the ''[[Export#Export Dialog|File Export Dialog]]'', a data structure <code>besa_channels</code> will be created. After filling the structure, the script <code>besa_action_channels.m</code> will be started.
  
== Introduction ==
+
All the MATLAB export functions are batchable. Thus, a complete data analysis can be performed, in which BESA Research does the preprocessing, and passes the data on to MATLAB i.e. for a statistical analysis of the results.
  
BESA Research has menu items ''"Send to MATLAB..."'' at various locations that allow to send data as structures to Matlab. After sending the data, BESA Research starts a Matlab script that can be used to start further data analysis on the data structure. These scripts, located in the ''Scripts\Matlab'' folder in the BESA Research installation, can be edited by the user to perform further data analysis in Matlab. For example, if "''Send to MATLAB''" is selected in the ''File Export Dialog'', a data structure "''besa_channels''"
+
An example for the application of the MATLAB interface is demonstrated in the BESA Research Tutorial. You can download this tutorial from [https://www.besa.de/wp-content/uploads/2021/04/BESA-Research-7.1-Tutorial.pdf our website].
  
will be created. After filling the structure, the script "''besa_action_channels.m''" will be started.
+
Some MATLAB scripts that can be used in conjunction with the BESA Research MATLAB interface are also available on our website at https://www.besa.de/downloads/matlab/. You are invited to send your own scripts for data analysis or to submit any questions or feedback here: https://www.besa.de/support/support-page/.
  
All the Matlab export functions are batchable. Thus, a complete data analysis can be performed, in which BESA Research does the preprocessing, and passes the data on to Matlab for a statistical analysis of the results.
+
'''Important: Please follow the instructions in the [[#Configuration | Configuration]] section! Then read the [[#How the interface works | How the interface works]] section to get started.'''
  
An example for the application of the MATLAB interface is demonstrated in the BESA Research Tutorial on Batch Scripts, Multiple Subjects & Conditions, MATLAB-Interface. You can download this tutorial from our website at www.besa.de/tutorials/hands_on.
 
  
Some MATLAB scripts that can be used in conjunction with the BESA Research MATLAB interface are also available on our website at www.besa.de/updates/matlab. You are invited to send your own scripts for data analysis or to submit any questions or feedback here: http://besa.de/contact/support/form.php.
+
= Configuration =
  
'''Important! Please follow the instructions in the ''Installation” ''chapter! Then read the “''How the interface'' ''works” ''section to get started.'''
+
In order for the BESA-MATLAB interface to work, please follow the instructions below. If you start BESA Research, and the file menu does not display the "''Send to MATLAB''" item, the interface is not installed correctly!
  
== Configuration ==
+
== MATLAB must be installed ==
  
In order for the BESA-Matlab interface to work, please follow the instructions below. If you start BESA Research, and the file menu does not display the "''Send to MATLAB''" item, the interface is not installed correctly!
+
For the next step (required for MATLAB versions 2009b and over):
 
+
* We need to know whether the '''32-bit''' or '''64-bit''' version of MATLAB is installed.
 
+
* We also need to know the path to the MATLAB installation (e.g. '''C:\Program Files\MATLAB\2009b\''').
'''1'''. '''Matlab must be installed.'''
+
 
+
 
+
For step 2 (required for MATLAB versions 2009b and over), we need to know whether the 32-bit or 64-bit version of Matlab is installed. We also need to know the path to the Matlab installation (e.g. ''c:\Program'' ''Files\MATLAB\2009b\)''.
+
 
+
 
+
'''2'''. '''PATH environment variable:'''
+
 
+
 
+
For versions 2009b and over, make sure that the path to the Win32 or Win64 folder in the Matlab installation to the PATH environment variable is defined:
+
 
+
 
+
* The path for the 64-bit version for Matlab 2009b is typically ''c:\Program'' ''Files\MATLAB\2009b\bin\win64''. For the 32-bit version, the path is typically ''c:\Program Files\MATLAB\2009b\bin\win32''.
+
* Open the "System Properties" Dialog by holding down the <span style="color:#3366ff;">'''Windows'''</span> key and pressing the <span style="color:#3366ff;">'''Pause '''</span>button. In XP, the dialog is opened directly. In Vista and Window 7, the key combination opens the System Display. Click on the link "Change Settings".
+
  
 +
== Setting PATH environment variable ==
  
 +
For versions 2009b and over, make sure that the path to the Win32 or Win64 folder in the MATLAB installation to the PATH environment variable is defined:
  
 +
* The path for MATLAB 2009b:
 +
** The path for the 64-bit version: '''C:\Program Files\MATLAB\R2009b\bin\win64'''
 +
** The path for the 32-bit version: '''C:\Program Files\MATLAB\R2009b\bin\win32'''
  
 +
* Open the "'''System Properties'''" dialog by holding down the ''"Windows"'' key and pressing the ''"Pause"'' key at the same time (Windows logo key + Pause).
 +
** In Windows 7, the key combination opens the ''"System Display"''. Click on the link ''"Change Settings"''.
 +
** In Windows 8 and Windows 10, the key combination also opens the ''"System Display"''. Click on the link "'''Advanced system settings'''".
 +
*** Skip the step in this description, as you have already chosen the advanced settings.
  
 
[[Image:Matlab (1) .gif]]
 
[[Image:Matlab (1) .gif]]
  
 
+
* Select the "'''Advanced'''" tab in the ''"System Properties"'' dialog.
 
+
* Press the "'''Environment Variables...'''" button.
 
+
 
+
 
+
* Select the "Advanced" tab.
+
 
+
 
+
 
+
 
+
  
 
[[Image:Matlab (2) .gif]]
 
[[Image:Matlab (2) .gif]]
  
 
+
* Under "'''System variables'''" click on the "'''Path'''" variable, and then click the ''"Edit..."'' button.
 
+
** In the resulting dialog, enter a semicolon (;) at the end of the path string, and add the path after the semicolon.
 
+
** In Windows 10, click the ''"New"'' button in the resulting dialog and then add the path.
 
+
** Note that if you have multiple versions of MATLAB installed, the added path has to be prior to other MATLAB versions present in the system path.
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
 
+
* Press the "<span style="color:#3366ff;">'''Environment Variables'''</span>" button.
+
 
+
 
+
 
+
 
+
  
 
[[Image:Matlab (3) .gif]]
 
[[Image:Matlab (3) .gif]]
  
 +
[[Image:EditSystemVariable.png]]
 +
<!-- [[Image:Matlab (4) .gif]] -->
  
* Under "System variables" click on the "Path" variable and press "<span style="color:#3366ff;">'''Edit'''</span>". In the resulting dialog, enter a semicolon (;) at the end of the path string, and add the path after the semicolon.
+
* Click ''"OK"'' to close and save the path variable. Click ''"OK"'' to close the ''"System Properties"'' dialog. When using Windows Vista/7/8/10, you will also need to close the ''"Control Panel"'' window afterwards.
  
 +
== Additional configuration ==
  
 +
=== ConfigureBesaMatlabInterface.exe ===
  
 +
[[File:ConfigureBesaMatlabInterface_01.png|250px]]
  
 +
(Only required after a change of your MATLAB configuration after installation of BESA Research)
  
[[Image:Matlab (4) .gif]]
+
During the installation process of BESA Research, the program <span style="color:#ff9c00;">ConfigureBesaMatlabInterface.exe</span> (or SetupBesaMatlabInterface.exe) in the BESA Research root folder (e.g.: '''C:\Program Files (x86)\BESA\Research_7_1''') was executed.
  
 +
Run this program '''as administrator''' again when your MATLAB configuration has changed, e.g. after updating your MATLAB version. In the dropdown list, select the MATLAB version that you are using.
  
Press "<span style="color:#3366ff;">'''OK'''</span>" to close and save the path variable. Press "<span style="color:#3366ff;">'''OK'''</span>" to close the "System Properties" Dialog.
+
In the dropdown list, select the MATLAB version that you are using.
  
 +
This program performs two operations:
 +
* It copies the appropriate interface dll file to the BESA Research root folder and renames it to "<span style="color:#ff9c00;">BesaMatlab.dll</span>" (32-bit version) or "<span style="color:#ff9c00;">BesaMatlab64.dll</span>" (64-bit version), and
 +
* If you are using a 64-bit version, it creates an entry in [[The Initialization File: BESA.ini|BESA.ini]] (e.g.: '''C:\Users\Public\Documents\BESA\Research_7_1''') as follows:
  
'''3. Additional configuration''' (only required after a change of your MATLAB configuration after installation of BESA Research):
+
<source lang="dos">
 +
[Matlab]
 +
Platform=64
 +
</source>
  
 +
=== BesaMatlab64Interface.exe ===
  
During the installation process of BESA Research, the program "<span style="color:#ff9c00;"><span style="color:#00000a;">''SetupBesaMatlabInterface.exe''</span></span>" in the BESA Research root folder was executed. Run this program again when your MATLAB configuration has changed, e.g. after updating your MATLAB version.
+
[[File:BesaMatlab64Interfaces_01.png|200px]]
  
In the dropdown list, select the Matlab version that you are using.  
+
'''Note: This step is not needed from BESA Research 7.1 March 2021.'''
  
This program does two operations:  
+
If the installed MATLAB is 64-bit version, please run the program <span style="color:#ff9c00;">BesaMatlab64Interface.exe</span> in the BESA Research root folder (e.g.: '''C:\Program Files (x86)\BESA\Research_7_1'''). If the MATLAB path is set properly, a program window as the screenshot below is shown up without an error message. After that please just close the window.
  
 +
[[File:BesaMatlab64Interfaces_02.png|400px]]
  
a) it copies the appropriate interface Dll to the BESA Research root folder and renames it to "<span style="color:#ff9c00;">'''BesaMatlab.dll'''</span>" (32-bit version) or "<span style="color:#ff9c00;">'''BesaMatlab64.dll'''</span>" (64-bit version), and
+
== Updating the MATLAB Interface after MATLAB Upgrade ==
  
b) if you are using a 64-bit version it creates an entry in <span style="color:#ff9c00;">'''BESA.ini'''</span> as follows:
+
Sometimes, the BESA to MATLAB interface stops working after installation of new/additional MATLAB version on one computer. The reason is the registry change/corruption caused by the newly installed version. In order to correct this, one has to perform the following steps:
  
[Matlab]
+
# Make sure that in the "'''Path'''" environment variable the path to the current MATLAB version exist and, in case of other MATLAB version are present, is first on a list.
 +
# Make sure that the correct MATLAB interface dll (<span style="color:#ff9c00;">BesaMatlab.dll</span> (32-bit version) or <span style="color:#ff9c00;">BesaMatlab64.dll</span> (64-bit version)) is installed by starting the tool <span style="color:#ff9c00;">ConfigureBesaMatlabInterface.exe</span> (or SetupBesaMatlabInterface.exe) and selecting the corresponding MATLAB version and architecture.
 +
# Run '''CMD (Command Prompt) as administrator''', and then execute the following command <source lang="dos">matlab -regserver</source> ([https://www.mathworks.com/help/matlab/matlab_external/register-matlab-as-automation-server.html registers MATLAB as a Component Object Model (COM) server]).
 +
#* Close the CMD window (there should be no error message).
 +
#* Sometimes if the MATLAB license is connected to a specific user account and the user account does not have administrator rights, it could be problematic to execute that command. In that case, change the corresponding account to an administrator account and then perform the actions again. After that the account could be made to regular user account again.
 +
#* Alternatively, you can also run the <code>UserRegMATLAB.p</code> (which can be downloaded [https://www.mathworks.com/matlabcentral/answers/uploaded_files/139006/UserRegMATLAB.p here]) function to manually register your MATLAB version as a COM Automation Server. To switch the version of MATLAB that is registered, simply run the <code>UserRegMATLAB</code> command on the new version so that it becomes the new COM Automation Server.
 +
#* Finally, since MATLAB 2020a to register COM server a following command can be executed directly form MATLAB: <code>comserver('register')</code>. This does not require administrator account
 +
# Run '''CMD (Command Prompt) as NOT administrator''', and then execute the following command <source lang="dos">matlab -automation</source> ([https://www.mathworks.com/help/matlab/matlab_external/creating-the-server-manually.html Manually create automation server]: start MATLAB as a Component Object Model (COM) Automation server. MATLAB does not display the splash screen).
 +
#* Close the CMD and MATLAB Command Window (there should be no error message).
  
Platform=64
+
== Testing ==
  
 +
Start BESA Research and check if '''Send to MATLAB...''' is displayed in the '''File''' menu. If it is, the interface is set up correctly. Note that the item will be grayed if no file is open in BESA Research.
  
'''4. Testing:'''
+
Test the MATLAB interface
 +
* Open a data file, mark a short (e.g. 1 s) time range, and select '''File / Send to MATLAB...''' to open  the ''[[Export#Export Dialog|Export Dialog]]''.
  
 +
[[Image:Matlab1.png]]
  
Start BESA Research and check if ''Send to MATLAB ''is displayed in the<span style="color:#3366ff;">''' File '''</span>menu. If it is, the interface is set up correctly. (Note that the item will be grayed if no file is open in BESA Research.)
+
* The MATLAB window should open, and BESA Research will display a progress bar.
 
+
Test the interface: open a data file, mark a short (e.g. 1 s) time range, and select ''File / Send to Matlab'' to open the ''Export Dialog'':
+
 
+
 
+
[[Image:Matlab (5) .gif]]
+
 
+
 
+
The Matlab window should open, and BESA Research will display a progress bar:
+
 
+
  
 
[[Image:Matlab (6) .gif]]
 
[[Image:Matlab (6) .gif]]
  
 
+
* After the window closes, open the MATLAB window, and type '''<code>workspace</code>''' to open the workspace window, or '''<code>desktop</code>''' to open the standard MATLAB desktop.
After the window closes, open the Matlab window, and type "''Workspace''" to open the workspace window, or "''Desktop''" to open the standard Matlab desktop.
+
* Examine the <code>besa_channels</code> variable, which contains the data for the marked data segment.
 
+
Examine the "besa_channels" variable, which contains the data for the marked data segment.
+
 
+
  
 
[[Image:Matlab (7) .gif]]
 
[[Image:Matlab (7) .gif]]
  
 +
<!--
 +
<div><ul>
 +
<li style="display: inline-block;"> [[File:SendToMatlab.png|thumb|400px|Figure 4. Send marked segment to MATLAB]] </li>
 +
<li style="display: inline-block;"> [[File:SendToMatlabProgressbar.png|thumb|200px|Figure 5. Send to MATLAB progress bar]] </li>
 +
<li style="display: inline-block;"> [[File:ExportedMatlabStructure.png|thumb|300px|Figure 6. Data exported from BESA Research to MATLAB]] </li>
 +
</ul></div>
 +
-->
  
'''Troubleshooting if the interface is not working after the above steps'''
+
== Troubleshooting if the interface is not working after the above steps ==
  
 +
If the '''File / Send to MATLAB...''' menu item is not shown, this means that either the path (the above step for Setting PATH environment variable) is not defined properly, or that the interface Dll (<span style="color:#ff9c00;">'''BesaMatlab.dll'''</span> or <span style="color:#ff9c00;">'''BesaMatlab64.dll'''</span>) is not compatible with the currently installed version of MATLAB.
  
If the ''File / Send to MATLAB''... menu item is not shown, this means that either the path (step 2 above) is not defined properly, or that the interface Dll <span style="color:#ff9c00;">'''BesaMatlab.dll'''</span> or <span style="color:#ff9c00;">'''BesaMatlab64.dll'''</span> is not compatible with the currently installed version of Matlab.
+
If the path is correct, then please contact our support team here: https://www.besa.de/support/support-page/, including the following information:
 
+
* Which MATLAB version are you using?
If the path is correct, then please contact our support team here: [http://besa.de/contact/support/form.php http://besa.de/contact/support/form.php], including the following information:* Which Matlab version are you using?
+
 
* Specify also if you are using the 32-bit or 64-bit version.
 
* Specify also if you are using the 32-bit or 64-bit version.
  
  
 +
= How the interface works =
  
== How the interface works ==
+
== The interface ==
 
+
'''The interface'''
+
 
+
  
 
The interface uses libraries supplied by Matlab. Their descriptions can be found in Matlab Help under the keywords "Engine Library". The Matlab libraries are incorporated into the interface Dll (<span style="color:#ff9c00;">'''BesaMatlab.dll'''</span> or <span style="color:#ff9c00;">'''BesaMatlab64.dll'''</span>) that provides the interface between BESA Research and Matlab. As newer versions of Matlab are released, it may be necessary to generate new versions of the dll to match the new library versions.
 
The interface uses libraries supplied by Matlab. Their descriptions can be found in Matlab Help under the keywords "Engine Library". The Matlab libraries are incorporated into the interface Dll (<span style="color:#ff9c00;">'''BesaMatlab.dll'''</span> or <span style="color:#ff9c00;">'''BesaMatlab64.dll'''</span>) that provides the interface between BESA Research and Matlab. As newer versions of Matlab are released, it may be necessary to generate new versions of the dll to match the new library versions.
  
 +
== Matlab automation window ==
  
'''Matlab automation window'''
+
On the first call to one of the Matlab routines, the Matlab Automation Window is opened. This is not the same as the window that is normally opened when Matlab is started directly in Windows (the window can also be opened by typing "Matlab /automation" from the command line). From the Automation Window one can run normal Matlab scripts. It is also possible to type "'''<code>desktop</code>'''" in the Automation Window to open the standard Matlab desktop. All variables that have been sent from BESA Research are then visible there.
  
 +
== BESA Research "Send to MATLAB" commands and scripts ==
  
On the first call to one of the Matlab routines, the Matlab Automation Window is opened. This is not the same as the window that is normally opened when Matlab is started directly in Windows (the window can also be opened by typing "Matlab /automation" from the command line). From the Automation Window one can run normal Matlab scripts. It is also possible to type "desktop" in the Automation Window to open the standard Matlab desktop. All variables that have been sent from BESA Research are then visible there.
+
Send to MATLAB commands generate data structures that differ depending on the type of data that are sent. After each export the corresponding script is executed. They are available at the following locations in BESA Research:
 
+
* From the Main program window (<span style="color:#3366ff;">'''File'''</span> Menu), as part of the ''Export Dialog''. Structure name ''besa_channels''. Script name ''besa_action_channels.m''.
 
+
'''BESA Research "Send to MATLAB" commands and scripts'''
+
 
+
 
+
Send to MATLAB commands generate data structures that differ depending on the type of data that are sent. After each export the corresponding script is executed. They are available at the following locations in BESA Research:* From the Main program window (<span style="color:#3366ff;">'''File'''</span> Menu), as part of the ''Export Dialog''. Structure name ''besa_channels''. Script name ''besa_action_channels.m''.
+
 
* From the FFT analysis (<span style="color:#3366ff;">'''File'''</span> Menu). Structure name ''besa_fft''. Script name ''besa_action_fft.m''.
 
* From the FFT analysis (<span style="color:#3366ff;">'''File'''</span> Menu). Structure name ''besa_fft''. Script name ''besa_action_fft.m''.
 
* From Combine Conditions (''Run Scripts Tab''), in the export of peaks and mean amplitudes. Structure name ''besa_peak''. Script name ''besa_action_peak.m''.
 
* From Combine Conditions (''Run Scripts Tab''), in the export of peaks and mean amplitudes. Structure name ''besa_peak''. Script name ''besa_action_peak.m''.
Line 205: Line 161:
 
* From Time-Frequency/Coherence Analysis (<span style="color:#3366ff;">'''File'''</span> Menu). Structure names ''besa_tfc'', and ''besa_tfc_trials'' (for single-trial time-frequency data). Script names ''besa_action_tfc.m'' and ''besa_action_tfc_trials.m''.
 
* From Time-Frequency/Coherence Analysis (<span style="color:#3366ff;">'''File'''</span> Menu). Structure names ''besa_tfc'', and ''besa_tfc_trials'' (for single-trial time-frequency data). Script names ''besa_action_tfc.m'' and ''besa_action_tfc_trials.m''.
  
 +
Some additional scripts are used for specific data types. For example, when exporting raw data, two scripts, ''besa_helper_channels_event.m'' (or ''besa_helper_channels_event_continousdata.m'' for 64bit) and ''besa_helper_channels_continuousdata.m'' are used to collect events from each data block and to combine the exported data blocks into a single matrix.
  
 +
== Command script path ==
  
 +
When the commands are executed, BESA Research automatically executes an "addpath" command in Matlab to add the ''Scripts\MATLAB'' folder (in Windows 10 typically ''C:\Users\Public\Documents\BESA\Research_7_1\Scripts\MATLAB'') and its first-level subfolders to the Matlab search path.
  
 +
== Units ==
  
Some additional scripts are used for specific data types. For example, when exporting raw data, two scripts, ''besa_helper_channels_event.m'' and ''besa_helper_channels_continuousdata.m'' are used to collect events from each data block and to combine the exported data blocks into a single matrix.
+
Unless otherwise stated, distances are in meters, times are in seconds, and the head-frame (fiducial-based) coordinate system is used.
  
  
'''Command script path'''
+
[[Category:Research Manual]]
  
 
+
{{BESAManualNav}}
When the commands are executed, BESA Research automatically executes an "addpath" command in Matlab to add the ''Scripts\MATLAB'' folder (in Windows 7 typically ''C:\Users\Public\Public'' ''Documents\BESA\Research_6_0\Scripts\MATLAB'') and its first-level subfolders to the Matlab search path.
+
 
+
 
+
'''Units'''
+
 
+
 
+
Unless otherwise stated, distances are in meters, times are in seconds, and the head-frame (fiducial-based) coordinate system is used.
+

Latest revision as of 13:27, 6 May 2021

Module information
Modules BESA Research Basic or higher
Version BESA Research 6.1 or higher

Introduction

BESA Research has menu items "Send to MATLAB..." at various locations that allow to send data as structures to MATLAB. After sending the data, BESA Research starts a MATLAB script that can be used to start further data analysis on the data structure. These scripts, located in the Scripts\Matlab folder in the BESA Research installation, can be edited by the user to perform further data analysis in MATLAB. For example, if "Send to MATLAB" is selected in the File Export Dialog, a data structure besa_channels will be created. After filling the structure, the script besa_action_channels.m will be started.

All the MATLAB export functions are batchable. Thus, a complete data analysis can be performed, in which BESA Research does the preprocessing, and passes the data on to MATLAB i.e. for a statistical analysis of the results.

An example for the application of the MATLAB interface is demonstrated in the BESA Research Tutorial. You can download this tutorial from our website.

Some MATLAB scripts that can be used in conjunction with the BESA Research MATLAB interface are also available on our website at https://www.besa.de/downloads/matlab/. You are invited to send your own scripts for data analysis or to submit any questions or feedback here: https://www.besa.de/support/support-page/.

Important: Please follow the instructions in the Configuration section! Then read the How the interface works section to get started.


Configuration

In order for the BESA-MATLAB interface to work, please follow the instructions below. If you start BESA Research, and the file menu does not display the "Send to MATLAB" item, the interface is not installed correctly!

MATLAB must be installed

For the next step (required for MATLAB versions 2009b and over):

  • We need to know whether the 32-bit or 64-bit version of MATLAB is installed.
  • We also need to know the path to the MATLAB installation (e.g. C:\Program Files\MATLAB\2009b\).

Setting PATH environment variable

For versions 2009b and over, make sure that the path to the Win32 or Win64 folder in the MATLAB installation to the PATH environment variable is defined:

  • The path for MATLAB 2009b:
    • The path for the 64-bit version: C:\Program Files\MATLAB\R2009b\bin\win64
    • The path for the 32-bit version: C:\Program Files\MATLAB\R2009b\bin\win32
  • Open the "System Properties" dialog by holding down the "Windows" key and pressing the "Pause" key at the same time (Windows logo key + Pause).
    • In Windows 7, the key combination opens the "System Display". Click on the link "Change Settings".
    • In Windows 8 and Windows 10, the key combination also opens the "System Display". Click on the link "Advanced system settings".
      • Skip the step in this description, as you have already chosen the advanced settings.

Matlab (1) .gif

  • Select the "Advanced" tab in the "System Properties" dialog.
  • Press the "Environment Variables..." button.

Matlab (2) .gif

  • Under "System variables" click on the "Path" variable, and then click the "Edit..." button.
    • In the resulting dialog, enter a semicolon (;) at the end of the path string, and add the path after the semicolon.
    • In Windows 10, click the "New" button in the resulting dialog and then add the path.
    • Note that if you have multiple versions of MATLAB installed, the added path has to be prior to other MATLAB versions present in the system path.

Matlab (3) .gif

EditSystemVariable.png

  • Click "OK" to close and save the path variable. Click "OK" to close the "System Properties" dialog. When using Windows Vista/7/8/10, you will also need to close the "Control Panel" window afterwards.

Additional configuration

ConfigureBesaMatlabInterface.exe

ConfigureBesaMatlabInterface 01.png

(Only required after a change of your MATLAB configuration after installation of BESA Research)

During the installation process of BESA Research, the program ConfigureBesaMatlabInterface.exe (or SetupBesaMatlabInterface.exe) in the BESA Research root folder (e.g.: C:\Program Files (x86)\BESA\Research_7_1) was executed.

Run this program as administrator again when your MATLAB configuration has changed, e.g. after updating your MATLAB version. In the dropdown list, select the MATLAB version that you are using.

In the dropdown list, select the MATLAB version that you are using.

This program performs two operations:

  • It copies the appropriate interface dll file to the BESA Research root folder and renames it to "BesaMatlab.dll" (32-bit version) or "BesaMatlab64.dll" (64-bit version), and
  • If you are using a 64-bit version, it creates an entry in BESA.ini (e.g.: C:\Users\Public\Documents\BESA\Research_7_1) as follows:
[Matlab] 
Platform=64

BesaMatlab64Interface.exe

BesaMatlab64Interfaces 01.png

Note: This step is not needed from BESA Research 7.1 March 2021.

If the installed MATLAB is 64-bit version, please run the program BesaMatlab64Interface.exe in the BESA Research root folder (e.g.: C:\Program Files (x86)\BESA\Research_7_1). If the MATLAB path is set properly, a program window as the screenshot below is shown up without an error message. After that please just close the window.

BesaMatlab64Interfaces 02.png

Updating the MATLAB Interface after MATLAB Upgrade

Sometimes, the BESA to MATLAB interface stops working after installation of new/additional MATLAB version on one computer. The reason is the registry change/corruption caused by the newly installed version. In order to correct this, one has to perform the following steps:

  1. Make sure that in the "Path" environment variable the path to the current MATLAB version exist and, in case of other MATLAB version are present, is first on a list.
  2. Make sure that the correct MATLAB interface dll (BesaMatlab.dll (32-bit version) or BesaMatlab64.dll (64-bit version)) is installed by starting the tool ConfigureBesaMatlabInterface.exe (or SetupBesaMatlabInterface.exe) and selecting the corresponding MATLAB version and architecture.
  3. Run CMD (Command Prompt) as administrator, and then execute the following command
    matlab -regserver
    (registers MATLAB as a Component Object Model (COM) server).
    • Close the CMD window (there should be no error message).
    • Sometimes if the MATLAB license is connected to a specific user account and the user account does not have administrator rights, it could be problematic to execute that command. In that case, change the corresponding account to an administrator account and then perform the actions again. After that the account could be made to regular user account again.
    • Alternatively, you can also run the UserRegMATLAB.p (which can be downloaded here) function to manually register your MATLAB version as a COM Automation Server. To switch the version of MATLAB that is registered, simply run the UserRegMATLAB command on the new version so that it becomes the new COM Automation Server.
    • Finally, since MATLAB 2020a to register COM server a following command can be executed directly form MATLAB: comserver('register'). This does not require administrator account
  4. Run CMD (Command Prompt) as NOT administrator, and then execute the following command
    matlab -automation
    (Manually create automation server: start MATLAB as a Component Object Model (COM) Automation server. MATLAB does not display the splash screen).
    • Close the CMD and MATLAB Command Window (there should be no error message).

Testing

Start BESA Research and check if Send to MATLAB... is displayed in the File menu. If it is, the interface is set up correctly. Note that the item will be grayed if no file is open in BESA Research.

Test the MATLAB interface

  • Open a data file, mark a short (e.g. 1 s) time range, and select File / Send to MATLAB... to open the Export Dialog.

Matlab1.png

  • The MATLAB window should open, and BESA Research will display a progress bar.

Matlab (6) .gif

  • After the window closes, open the MATLAB window, and type workspace to open the workspace window, or desktop to open the standard MATLAB desktop.
  • Examine the besa_channels variable, which contains the data for the marked data segment.

Matlab (7) .gif


Troubleshooting if the interface is not working after the above steps

If the File / Send to MATLAB... menu item is not shown, this means that either the path (the above step for Setting PATH environment variable) is not defined properly, or that the interface Dll (BesaMatlab.dll or BesaMatlab64.dll) is not compatible with the currently installed version of MATLAB.

If the path is correct, then please contact our support team here: https://www.besa.de/support/support-page/, including the following information:

  • Which MATLAB version are you using?
  • Specify also if you are using the 32-bit or 64-bit version.


How the interface works

The interface

The interface uses libraries supplied by Matlab. Their descriptions can be found in Matlab Help under the keywords "Engine Library". The Matlab libraries are incorporated into the interface Dll (BesaMatlab.dll or BesaMatlab64.dll) that provides the interface between BESA Research and Matlab. As newer versions of Matlab are released, it may be necessary to generate new versions of the dll to match the new library versions.

Matlab automation window

On the first call to one of the Matlab routines, the Matlab Automation Window is opened. This is not the same as the window that is normally opened when Matlab is started directly in Windows (the window can also be opened by typing "Matlab /automation" from the command line). From the Automation Window one can run normal Matlab scripts. It is also possible to type "desktop" in the Automation Window to open the standard Matlab desktop. All variables that have been sent from BESA Research are then visible there.

BESA Research "Send to MATLAB" commands and scripts

Send to MATLAB commands generate data structures that differ depending on the type of data that are sent. After each export the corresponding script is executed. They are available at the following locations in BESA Research:

  • From the Main program window (File Menu), as part of the Export Dialog. Structure name besa_channels. Script name besa_action_channels.m.
  • From the FFT analysis (File Menu). Structure name besa_fft. Script name besa_action_fft.m.
  • From Combine Conditions (Run Scripts Tab), in the export of peaks and mean amplitudes. Structure name besa_peak. Script name besa_action_peak.m.
  • From Source Analysis (File Menu), for exporting source waveforms (besa_sourcewaveforms), source models (besa_sourcemodel), data, residual and model waveforms (besa_sa_channels), and 3D images (besa_image). Script names besa_action_sourcewaveforms.m, besa_action_sourcemodel.m, besa_action_sa_channels.m, and besa_action_image.m.
  • From Time-Frequency/Coherence Analysis (File Menu). Structure names besa_tfc, and besa_tfc_trials (for single-trial time-frequency data). Script names besa_action_tfc.m and besa_action_tfc_trials.m.

Some additional scripts are used for specific data types. For example, when exporting raw data, two scripts, besa_helper_channels_event.m (or besa_helper_channels_event_continousdata.m for 64bit) and besa_helper_channels_continuousdata.m are used to collect events from each data block and to combine the exported data blocks into a single matrix.

Command script path

When the commands are executed, BESA Research automatically executes an "addpath" command in Matlab to add the Scripts\MATLAB folder (in Windows 10 typically C:\Users\Public\Documents\BESA\Research_7_1\Scripts\MATLAB) and its first-level subfolders to the Matlab search path.

Units

Unless otherwise stated, distances are in meters, times are in seconds, and the head-frame (fiducial-based) coordinate system is used.