Difference between revisions of "Visualization with BESA Plot in FieldTrip"
(→Predefined plotting functions for data from FieldTrip) |
|||
Line 99: | Line 99: | ||
== Predefined plotting functions for data from FieldTrip == | == Predefined plotting functions for data from FieldTrip == | ||
− | There are two functions available in | + | 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_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> | * <tt>besa_plotFtDipoleResults</tt>: for dipole fit data resulted from <tt>ft_dipolefitting</tt> |
Revision as of 12:35, 6 May 2021
Module information | |
Modules | BESA Plot |
Version | BESA Plot 1.1 or higher |
BESA Plot is a free tool created by Dr. Patrick Berg (BESA GmbH) for visualization of MEEG data. Initially it was meant to be complementary visualization tool to 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 MATLAB based open source package for MEEG data analysis 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:
- 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.
Contents
Procedure
Generating the data file (.avr)
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 ft_timelockanalysis. Its general form is something like this:
avg: [147x271 double] var: [147x271 double] time: [1x271 double] dof: [147x271 double] label: {147x1 cell} dimord: 'chan_time' grad: [1x1 struct] cfg: [1x1 struct]
In order to create a data file from that structure, one needs the function besa_save2Avr which can be found in the FieldTrip installation in the folder external\besa or can be downloaded directly from BESA Homepage. Just unpack the archive and add the path to the MATLAB path (e.g. addpath('D:\Path\to\MATLAB2BESA')
).
Use the function like this:
status = besa_save2Avr(cfg.datapath, DataFile, data_matrix, ... time_samples, channel_labels, data_scale_factor, time_scale_factor);
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 besa_save2Elp again from the package MATLAB2BESA. Use the function like this:
status = besa_save2Elp(cfg.datapath, ElpFile, ... SphericalCoords, channel_labels, channel_type);
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:
set color=black set size=16 set dipole number=1 xloc=0.65 yloc=0.16 zloc=0.29 xori=0.15 yori=-0.73 zori=-0.67 color=blue length=0.1 diameter=0.05 set dipole number=2 xloc=-0.65 yloc=0.16 zloc=0.29 xori=-0.17 yori=-0.57 zori=-0.81 color=blue length=0.1 diameter=0.05 head width=35 height=40 viewpoint=top brain=on x=20.0 y=75.0 head width=35 height=40 viewpoint=back brain=on x=20.0 y=30.0 head width=35 height=40 viewpoint=left brain=on x=77.0 y=77.0 set dataset=1 set mapuV=18 set mapcolor negative=blue positive=red electrode=none set mapsize=35 set maptype=amplitude set maplambda=1E-5 set mapviewpoint=top set maprange maximumuV=461 minimumuV=-419 zerouV=0.0 contours=on map latency=110.6 end=150.4 step=20 mean=on label=on x=77.0 y=30.0
Figure 1 shows the result after running the script in BESA Plot with the data (.avr) and channel (.elp) files.
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 besa_save2Dataset which also in the package MATLAB2BESA. Use the function like this:
status = besa_save2Dataset(DatasetPath, DataFile, ... ElpFile, ControlFile, NumChannels, NumTimeSamples, ... SamplingInterval, FirstTimeSample);
Starting BESA Plot with command line arguments
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: BesaPlot <data_file_name> <control_file_name>
Example:
start /b cmd /c ""C:\Program Files (x86)\BESA\Plot\BesaPlot.exe" "D:\Path\to\erf1.avr" "D:\Path\to\erf1.bpctrl""
Please note that start /b cmd /c
is used to start the program in background.
Predefined plotting functions for data from FieldTrip
There are two functions available in here (MATLAB2BESA_BESAPlot.zip) or the external toolbox folder of FieldTrip (external\besa, this folder can be added to the MATLAB path using the following fieldtrip command: ft_hastoolbox('besa', 1)
) which can be used to plot directly data from FieldTrip with BESA Plot.
- besa_plotFtSensorLevelMaps: for sensor level MEEG data generated by ft_timelockanalysis
- besa_plotFtDipoleResults: for dipole fit data resulted from ft_dipolefitting
The image gained with the function besa_plotFtSensorLevelMaps is shown in Figure 2 and the one generated with the function ft_dipolefitting is shown in Figure 1.
The functions can be called like this:
cfg = []; cfg.badchannels = 1; % number of bad channels 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 cfg.filebasename = 'erf1'; % basename for the generated files cfg.datapath = 'D:\Data\BesaPlot'; % folder where to save the generated files status = besa_plotFtSensorLevelMaps(cfg, data_avg); % data_avg: A structure resulting from the function ft_timelockanalysis.
and
cfg = []; cfg.badchannels = 1; % number of bad channels cfg.besaplot = '"C:\Program Files (x86)\BESA\Plot\BesaPlot.exe"'; % path to BESA Plot cfg.filebasename = 'megdatafile'; % basename for the generated files cfg.datapath = 'D:\Data\BesaPlot'; % folder where to save the generated files status = besa_plotFtDipoleResults(cfg, data_avg, dipole_source); % data_avg: A structure resulting from the function ft_timelockanalysis. % dipole_source: A structure resulting from the function ft_dipolefitting.
Please note that there are two possible ways to customize the plots:
- Change the section "Write the control file" in the plotting functions besa_plotFtSensorLevelMaps and besa_plotFtDipoleResults.
- 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 feature list.