Visualization with BESA Plot in FieldTrip - Revision history

Jaehyun at 10:56, 27 August 2021

2021-08-27T10:56:01Z

Abinash at 12:10, 6 May 2021

2021-05-06T12:10:31Z

Jaehyun: /* Predefined plotting functions for data from FieldTrip */

2021-05-06T11:35:05Z

‎Predefined plotting functions for data from FieldTrip

Jaehyun at 12:17, 5 May 2021

2021-05-05T12:17:24Z

Jaehyun at 13:12, 4 May 2021

2021-05-04T13:12:10Z

Jaehyun at 10:11, 19 June 2017

2017-06-19T10:11:46Z

Abinash at 15:44, 15 February 2017

2017-02-15T15:44:39Z

Todor at 12:27, 7 July 2016

2016-07-07T12:27:09Z

Todor: /* Predefined plotting functions for data from FieldTrip */

2016-07-07T12:23:11Z

‎Predefined plotting functions for data from FieldTrip

Todor: /* Predefined plotting functions for data from FieldTrip */

2016-07-07T12:22:46Z

‎Predefined plotting functions for data from FieldTrip

@@ Line 31: / Line 31: @@
 </tt>
-In order to create a data file from that structure, one needs the function <tt>besa_save2Avr</tt> which can be found in the FieldTrip installation in the folder <tt>external\besa</tt> or can be downloaded directly from [https://www.besa.de/wp-content/uploads/2020/10/MATLAB2BESA.zip BESA Homepage]. Just unpack the archive and add the path to the MATLAB path (e.g. <code>addpath('D:\Path\to\MATLAB2BESA')</code>).
+In order to create a data file from that structure, one needs the function <tt>besa_save2Avr</tt> which can be found in the FieldTrip installation in the folder <tt>external\besa</tt> or can be downloaded directly from [https://github.com/BESA-GmbH/BESA-MATLAB-Scripts/releases/latest/download/MATLAB2BESA.zip here]. Just unpack the archive and add the path to the MATLAB path (e.g. <code>addpath('D:\Path\to\MATLAB2BESA')</code>).
 Use the function like this:
@@ Line 99: / Line 99: @@
 == Predefined plotting functions for data from FieldTrip ==
-There are two functions available in [https://my.hidrive.com/share/9rw3-to96j#$/ here (MATLAB2BESA_BESAPlot.zip)] or the external toolbox folder of <tt>FieldTrip</tt> (<tt>external\besa</tt>, this folder can be added to the MATLAB path using the following fieldtrip command: <code>ft_hastoolbox('besa', 1)</code>) which can be used to plot directly data from FieldTrip with BESA Plot.
+There are two functions available in MATLAB2BESA ([https://github.com/BESA-GmbH/BESA-MATLAB-Scripts/blob/main/MATLAB2BESA/besa_plotFtSensorLevelMaps.m <code>besa_plotFtSensorLevelMaps.m</code>] and [https://github.com/BESA-GmbH/BESA-MATLAB-Scripts/blob/main/MATLAB2BESA/besa_plotFtDipoleResults.m <code>besa_plotFtDipoleResults.m</code>]) or the external toolbox folder of <tt>FieldTrip</tt> (<tt>external\besa</tt>, this folder can be added to the MATLAB path using the following fieldtrip command: <code>ft_hastoolbox('besa', 1)</code>) which can be used to plot directly data from FieldTrip with BESA Plot.
 * <tt>besa_plotFtSensorLevelMaps</tt>: for sensor level MEEG data generated by <tt>ft_timelockanalysis</tt>
 * <tt>besa_plotFtDipoleResults</tt>: for dipole fit data resulted from <tt>ft_dipolefitting</tt>

@@ Line 5: / Line 5: @@
 }}
-[http://www.besa.de/downloads/besa-plot/ BESA Plot] is a free tool created by Dr. Patrick Berg ([http://www.besa.de/ BESA GmbH]) for visualization of MEEG data. Initially it was meant to be complementary visualization tool to [http://www.besa.de/products/besa-research/besa-research-overview/ BESA Research], however, it could be used in more general context. In this document we demonstrate the possibility of using BESA Plot as a visualization tool in the [https://www.mathworks.com/ MATLAB] based open source package for MEEG data analysis [http://www.fieldtriptoolbox.org/ FieldTrip].
+[http://www.besa.de/downloads/besa-plot/ BESA Plot] is a free tool created by Dr Patrick Berg ([http://www.besa.de/ BESA GmbH]) for visualization of MEEG data. Initially, it was meant to be a complementary visualization tool to [http://www.besa.de/products/besa-research/besa-research-overview/ BESA Research], however, it could be used in a more general context. In this document, we demonstrate the possibility of using BESA Plot as a visualization tool in the [https://www.mathworks.com/ MATLAB] based open-source package for MEEG data analysis [http://www.fieldtriptoolbox.org/ FieldTrip].
-Since BESA Plot can be started with command line arguments, it can be called directly from MATLAB and the required input parameters (e.g. data file, settings and plotting modalities) can be committed as such arguments. There are four files necessary for starting BESA Plot from MATLAB and visualizing the corresponding data:
+Since BESA Plot can be started with command-line arguments, it can be called directly from MATLAB and the required input parameters (e.g. data file, settings and plotting modalities) can be committed as such arguments. There are four files necessary for starting BESA Plot from MATLAB and visualizing the corresponding data:
 # a data file (e.g. test1.avr)
 # a file containing the channel labels and coordinates (e.g. test1.elp)

@@ Line 99: / Line 99: @@
 == Predefined plotting functions for data from FieldTrip ==
-There are two functions available in the the external toolbox folder of <tt>FieldTrip</tt> (<tt>external\besa</tt>, this folder can be added to the MATLAB path using the following fieldtrip command: <code>ft_hastoolbox('besa', 1)</code>) which can be used to plot directly data from FieldTrip with BESA Plot.
+There are two functions available in [https://my.hidrive.com/share/9rw3-to96j#$/ here (MATLAB2BESA_BESAPlot.zip)] or the external toolbox folder of <tt>FieldTrip</tt> (<tt>external\besa</tt>, this folder can be added to the MATLAB path using the following fieldtrip command: <code>ft_hastoolbox('besa', 1)</code>) which can be used to plot directly data from FieldTrip with BESA Plot.
 * <tt>besa_plotFtSensorLevelMaps</tt>: for sensor level MEEG data generated by <tt>ft_timelockanalysis</tt>
 * <tt>besa_plotFtDipoleResults</tt>: for dipole fit data resulted from <tt>ft_dipolefitting</tt>

@@ Line 2: / Line 2: @@
 |title = Module information
 |module = BESA Plot
-|version = 1.1 or higher
+|version = BESA Plot 1.1 or higher
 }}
-[http://www.besa.de/downloads/besa-plot/ BESA Plot] is a free tool created by Dr. Patrick Berg ([http://www.besa.de/ BESA GmbH]) for visualization of MEEG data. Initially it was meant to be complementary visualization tool to [http://www.besa.de/products/besa-research/besa-research-overview/ BESA Research], however, it could be used in more general context. In this document we demonstrate the possibility of using BESA Plot as a visualization tool in the [https://www.mathworks.com/ Matlab] based open source package for MEEG data analysis [http://www.fieldtriptoolbox.org/ FieldTrip].
+[http://www.besa.de/downloads/besa-plot/ BESA Plot] is a free tool created by Dr. Patrick Berg ([http://www.besa.de/ BESA GmbH]) for visualization of MEEG data. Initially it was meant to be complementary visualization tool to [http://www.besa.de/products/besa-research/besa-research-overview/ BESA Research], however, it could be used in more general context. In this document we demonstrate the possibility of using BESA Plot as a visualization tool in the [https://www.mathworks.com/ MATLAB] based open source package for MEEG data analysis [http://www.fieldtriptoolbox.org/ FieldTrip].
-Since BESA Plot can be started with command line arguments, it can be called directly from Matlab and the required input parameters (e.g. data file, settings and plotting modalities) can be committed as such arguments. There are four files necessary for starting BESA Plot from Matlab and visualizing the corresponding data:
+Since BESA Plot can be started with command line arguments, it can be called directly from MATLAB and the required input parameters (e.g. data file, settings and plotting modalities) can be committed as such arguments. There are four files necessary for starting BESA Plot from MATLAB and visualizing the corresponding data:
 # a data file (e.g. test1.avr)
 # a file containing the channel labels and coordinates (e.g. test1.elp)
 # a control file containing the plotting commands for BESA Plot (e.g. test1.bpctrl)
 # a dataset file containing general information about the data file (e.g. test1.avr.dataset)
-These files should be generated dynamically in Matlab in order to be able to plot the Matlab data in BESA Plot.
+These files should be generated dynamically in MATLAB in order to be able to plot the MATLAB data in BESA Plot.
-== Generating the data file ==
+== Procedure ==
-First of all we need the data which are going to be saved as an avr-file. This is usually a Matlab structure generated  in FieldTrip with the function <tt>ft_timelockanalysis</tt>. Its general form is something like this:
+=== Generating the data file (.avr) ===
 <tt>
         avg: [147x271 double]
@@ Line 29: / Line 31: @@
 </tt>
-In order to create a data file from that structure, one needs the function <tt>besa_save2Avr</tt> which can be found in the FieldTrip installation in the folder <tt>external\besa</tt> or can be downloaded directly from [https://www.besa.de/wp-content/uploads/2020/10/MATLAB2BESA.zip BESA Homepage]. Just unpack the archive and add the path to the Matlab path (e.g. <tt>addpath(‘D:\Path\to\MATLAB2BESA’)</tt>).
+In order to create a data file from that structure, one needs the function <tt>besa_save2Avr</tt> which can be found in the FieldTrip installation in the folder <tt>external\besa</tt> or can be downloaded directly from [https://www.besa.de/wp-content/uploads/2020/10/MATLAB2BESA.zip BESA Homepage]. Just unpack the archive and add the path to the MATLAB path (e.g. <code>addpath('D:\Path\to\MATLAB2BESA')</code>).
 Use the function like this:
@@ Line 37: / Line 39: @@
 </source>
-== Generating the channel file (*.elp) ==
+=== Generating the channel file (*.elp) ===
 This file contains the channel type, the channel labels and the spherical coordinates of the channels. It can be created using the function <tt>besa_save2Elp</tt> again from the package <tt>MATLAB2BESA</tt>. Use the function like this:
 <source lang="matlab">
 status = besa_save2Elp(cfg.datapath, ElpFile, ...
@@ Line 45: / Line 48: @@
 </source>
-== Creating the BESA Plot control file ==
+=== Creating the BESA Plot control file (*.bpctrl) ===
 This is the actual plotting script. It follows the syntax of a scripting language defined in BESA Plot. For more details about the scripting language please refer to the program help. For this file format there is no writer function, since it can contain different scripts for different visualization scenarios. One possible script for plotting two dipoles in a schematic head could look like this:
@@ Line 68: / Line 71: @@
 </source>
-The result after running the script is shown in Figure 1.
+Figure 1 shows the result after running the script in BESA Plot with the data (.avr) and channel (.elp) files.
 [[File:DipoleFitResults.png|thumb|500px|c|none|Figure 1. Dipole fitting results visualized with BESA Plot]]
-== Creating the dataset file ==
+=== Creating the dataset file (*.dataset) ===
 The dataset file contains basic information about the data in the data file. It is not essential for the visualization process, however, if it is missing, the program asks the user additional questions about the settings before generating the image. The dataset file can be created with the function <tt>besa_save2Dataset</tt> which also in the package <tt>MATLAB2BESA</tt>. Use the function like this:
@@ Line 81: / Line 85: @@
 </source>
-== Starting BESA Plot with command line arguments ==
+=== Starting BESA Plot with command line arguments ===
-After the generation of the input files one can start BESA Plot with these files as input in order to visualize data. The syntax of the call is:
-<tt>BesaPlot <data_file_name> <control_file_name></tt>
+After the generation of the input files, one can start BESA Plot with these files as input to visualize data in '''command line'''. The syntax of the call is: <code>BesaPlot <data_file_name> <control_file_name></code>
 '''Example:'''
-<source lang="dos">
+<source lang="text">
-start /b cmd /c "C:\Program Files (x86)\BESA\Plot\BesaPlot.exe"
+start /b cmd /c ""C:\Program Files (x86)\BESA\Plot\BesaPlot.exe" "D:\Path\to\erf1.avr" "D:\Path\to\erf1.bpctrl""
-    M:\QM\BesaPlot\erf1.avr M:\QM\BesaPlot\erf1.bpctrl
 </source>
-Please note that <tt>start /b cmd /c</tt> is used to start the program in background.
 == Predefined plotting functions for data from FieldTrip ==
-There are two functions available in the package <tt>MATLAB2BESA</tt> (and also in FieldTrip in the folder <tt>external\besa</tt>) which can be used to plot directly data from FieldTrip with BESA Plot. These functions are <tt>besa_plotFtSensorLevelMaps</tt> and <tt>besa_plotFtDipoleResults</tt>. The first one can be used to plot sensor level MEEG data generated by <tt>ft_timelockanalysis</tt> and the second one for dipole fit data resulted from <tt>ft_dipolefitting</tt>. The image gained with the function <tt>besa_plotFtSensorLevelMaps</tt> is shown in Figure 2 and the one generated with the function <tt>ft_dipolefitting</tt> is shown in Figure 1.
+There are two functions available in the the external toolbox folder of <tt>FieldTrip</tt> (<tt>external\besa</tt>, this folder can be added to the MATLAB path using the following fieldtrip command: <code>ft_hastoolbox('besa', 1)</code>) which can be used to plot directly data from FieldTrip with BESA Plot.
 The functions can be called like this:
@@ Line 109: / Line 117: @@
 status = besa_plotFtSensorLevelMaps(cfg, data_avg);
 </source>
 [[File:AverageResults.png|thumb|500px|c|none|Figure 2 Visualization of sensor level data with BESA Plot]]
@@ Line 124: / Line 132: @@
 status = besa_plotFtDipoleResults(cfg, data_avg, dipole_source);
 </source>
 Please note that there are two possible ways to customize the plots:
-# Change the section '''Write the control file''' in the plotting functions <tt>besa_plotFtSensorLevelMaps</tt> and <tt>besa_plotFtDipoleResults</tt>.
+# Change the section "'''Write the control file'''" in the plotting functions <tt>besa_plotFtSensorLevelMaps</tt> and <tt>besa_plotFtDipoleResults</tt>.
-# After the plots were created use BESA Plot to change the images.
+# After the plots were created, use BESA Plot to change the images.
-For more information about which visualization possibilities are available in BESA Plot please read the program help or check the [http://www.besa.de/downloads/besa-plot/ feature list].
+For more information about which visualization possibilities are available in BESA Plot, please read the program help or check the [http://www.besa.de/downloads/besa-plot/ feature list].
 [[Category:ERP/ERF]] [[Category:BESA Plot]]

@@ Line 5: / Line 5: @@
 }}
-[http://www.besa.de/downloads/besa-plot/ BESA Plot] is a free tool created by [https://www.psychologie.uni-konstanz.de/forschung/clinicalpsychology/mitarbeiter/mitarbeiter-detailseite/berg-patrick-22/7347/7149/ Patrick Berg] ([http://www.besa.de/ BESA GmbH]) for visualization of MEEG data. Initially it was meant to be complementary visualization tool to [http://www.besa.de/products/besa-research/besa-research-overview/ BESA Research], however, it could be used in more general context. In this document we demonstrate the possibility of using BESA Plot as a visualization tool in the [https://www.mathworks.com/ Matlab] based open source package for MEEG data analysis [http://www.fieldtriptoolbox.org/ FieldTrip].
+[http://www.besa.de/downloads/besa-plot/ BESA Plot] is a free tool created by Dr. Patrick Berg ([http://www.besa.de/ BESA GmbH]) for visualization of MEEG data. Initially it was meant to be complementary visualization tool to [http://www.besa.de/products/besa-research/besa-research-overview/ BESA Research], however, it could be used in more general context. In this document we demonstrate the possibility of using BESA Plot as a visualization tool in the [https://www.mathworks.com/ Matlab] based open source package for MEEG data analysis [http://www.fieldtriptoolbox.org/ FieldTrip].
 Since BESA Plot can be started with command line arguments, it can be called directly from Matlab and the required input parameters (e.g. data file, settings and plotting modalities) can be committed as such arguments. There are four files necessary for starting BESA Plot from Matlab and visualizing the corresponding data:
@@ Line 15: / Line 15: @@
 == Generating the data file ==
 First of all we need the data which are going to be saved as an avr-file. This is usually a Matlab structure generated  in FieldTrip with the function <tt>ft_timelockanalysis</tt>. Its general form is something like this:
 <tt>
@@ Line 28: / Line 29: @@
 </tt>
-In order to create a data file from that structure one needs the function <tt>besa_save2Avr</tt> which can be found in the FieldTrip installation in the folder <tt>external\besa</tt> or can be downloaded directly from [ftp://h1772544.stratoserver.net/public/Matlab/MATLAB2BESA.zip BESA’s ftp-server]. Just unpack the archive and add the path to the Matlab path (e.g. <tt>addpath(‘D:\Path\to\MATLAB2BESA’)</tt>).
+In order to create a data file from that structure, one needs the function <tt>besa_save2Avr</tt> which can be found in the FieldTrip installation in the folder <tt>external\besa</tt> or can be downloaded directly from [https://www.besa.de/wp-content/uploads/2020/10/MATLAB2BESA.zip BESA Homepage]. Just unpack the archive and add the path to the Matlab path (e.g. <tt>addpath(‘D:\Path\to\MATLAB2BESA’)</tt>).
 Use the function like this:
@@ Line 37: / Line 38: @@
 == Generating the channel file (*.elp) ==
 This file contains the channel type, the channel labels and the spherical coordinates of the channels. It can be created using the function <tt>besa_save2Elp</tt> again from the package <tt>MATLAB2BESA</tt>. Use the function like this:
 <source lang="matlab">
@@ Line 44: / Line 46: @@
 == Creating the BESA Plot control file ==
 This is the actual plotting script. It follows the syntax of a scripting language defined in BESA Plot. For more details about the scripting language please refer to the program help. For this file format there is no writer function, since it can contain different scripts for different visualization scenarios. One possible script for plotting two dipoles in a schematic head could look like this:
@@ Line 66: / Line 69: @@
 The result after running the script is shown in Figure 1.
-[[File:DipoleFitResults.png|thumb|500px|c|none|Figure 1 Dipole fitting results visualized with BESA Plot]]
+[[File:DipoleFitResults.png|thumb|500px|c|none|Figure 1. Dipole fitting results visualized with BESA Plot]]
 == Creating the dataset file ==
 The dataset file contains basic information about the data in the data file. It is not essential for the visualization process, however, if it is missing, the program asks the user additional questions about the settings before generating the image. The dataset file can be created with the function <tt>besa_save2Dataset</tt> which also in the package <tt>MATLAB2BESA</tt>. Use the function like this:
@@ Line 91: / Line 95: @@
 == Predefined plotting functions for data from FieldTrip ==
 There are two functions available in the package <tt>MATLAB2BESA</tt> (and also in FieldTrip in the folder <tt>external\besa</tt>) which can be used to plot directly data from FieldTrip with BESA Plot. These functions are <tt>besa_plotFtSensorLevelMaps</tt> and <tt>besa_plotFtDipoleResults</tt>. The first one can be used to plot sensor level MEEG data generated by <tt>ft_timelockanalysis</tt> and the second one for dipole fit data resulted from <tt>ft_dipolefitting</tt>. The image gained with the function <tt>besa_plotFtSensorLevelMaps</tt> is shown in Figure 2 and the one generated with the function <tt>ft_dipolefitting</tt> is shown in Figure 1.
 The functions can be called like this:

← Older revision		Revision as of 15:44, 15 February 2017
Line 108:		Line 108:
	For more information about which visualization possibilities are available in BESA Plot please read the program help or check the [http://www.besa.de/downloads/besa-plot/ feature list].		For more information about which visualization possibilities are available in BESA Plot please read the program help or check the [http://www.besa.de/downloads/besa-plot/ feature list].

−	[[Category:BESA Plot~~, Matlab~~]]	+	[[Category:ERP/ERF]] [[Category:BESA Plot]]

@@ Line 79: / Line 79: @@
 cfg.latency = [0.000 0.250]; % interval of interest in seconds
 cfg.timestep = 0.020; % time interval between two plots
-cfg.besaplot = '"C:\Program Files (x86)\BESA\Plot\BesaPlot.exe"'; % path to BESA Plot
+% path to BESA Plot
 cfg.filebasename = 'erf1'; % basename for the generated files
-cfg.datapath = 'D:\Data\BesaPlot'; % folder where to save the generated files
+% folder where to save the generated files
 status = besa_plotFtSensorLevelMaps(cfg, data_avg);
@@ Line 95: / Line 97: @@
 status = besa_plotFtDipoleResults(cfg, data_avg, dipole_source);
 </source>