BESA® Wiki - User contributions [en]

BESA Research Batch Processing

2021-11-02T12:44:40Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 6.1 or higher
}}



== Combine Conditions and Batch Module: Introduction ==

Functions of this module are started by selecting the menu operations "'''ERP / Combine Conditions...'''" and "'''Process / Batch Scripts...'''".

* '''Combine Condition Scripts''' provides various operations on BESA averages.
* '''Batch Scripts''' provides batch operations on all data files.
* Note that a batch script can also be performed on the current file by selecting "'''Process / Run Batch...'''" or by typing the shortcut key "'''R'''".

== File List Tab ==

Define a list of files on which the operations will be performed. The tab is the same for Combine Conditions Scripts and for Batch Scripts. Combine Conditions Scripts only allows you to open BESA average files (e.g. '''<nowiki>*.fsg</nowiki>''' and '''<nowiki>*.avr</nowiki>''', but also '''.mul''', '''.raw''', '''.swf''', and '''.foc''' if the files have a defined pre-stimulus interval), whereas Batch Scripts allows you to open any data file whose format is known to BESA Research.

When the Combine-Conditions or the Batch module is started, all currently opened (Combine-Conditions: averages only) files are displayed in the list.

To the right of each file name, the number of electrodes, total number of channels, and the sampling rate used in the file are displayed. In the Combine-Conditions module, the number of Epochs (segments) and the number of differently-named conditions are also shown.

'''Add files to the list'''

* Press the '''Add File ''' button.
* Drag one or more files from Windows Explorer onto the window.

'''Remove files from the list'''

* Right click on the file name and confirm the delete operation in the resulting dialog.
* Mark one or more file names in the list (e.g. hold down the''' Ctrl''' key to mark multiple files). Right click to obtain the context menu and select "'''Delete'''", or just press the '''Del '''key.

'''Reorder files within the current file list'''

* Right click on the file name and select "'''''Move Up'''''" or "'''''Move Down'''''".
* Mark one or more file names in the list (e.g. hold down the '''Ctr'''l key to mark multiple files). Right click to obtain the context menu and select "'''''Move Up'''''" or "'''''Move Down'''''", or hold down the''' Ctrl''' key '''and '''press the '''Up''' and '''Down arrows'''.

'''Sort the current file list alphabetically'''

* Click on the File bar above the list

'''Save the current file list'''

* Press the '''Save File List''' button.

'''Load a file list'''

* Press the '''Load File List''' button, or the '''Load Previous''' button to load the most recently used file list.

'''Which conditions are read from a source file? (Combine-Conditions module only)'''

* Normally, all conditions are read from a source file. To exclude one or more segments from operations in the Combine Conditions module, mark the segments as artifacts in the main program display. It is sufficient for the beginning or the end of an artifact interval to be within the segment for the segment to be excluded.

'''File list from Combine Conditions:'''

[[Image:Batch processing (1).png]]

'''Don't try to open here... (Batch only)'''

By default, this checkbox is unchecked.

In the checked state, BESA Research doesn't check if it can open the file. Use this function '''only''' if the file is ASCII and you want to use the '''ImportASCII '''batch command.

'''File List from Batch Scripts''':

[[Image:Batch processing (2).png]]

== Batch Processing ==

=== Batch Processing Scripts ===

With Batch Scripts, you can define a set of operations (e.g. Artifact Scan, Average, etc.) and apply these to several data files.

These operations include

* Load Paradigm
* Artifact Scan
* Average
* Export (and Merge)
* File Open (switch to another data file)
* Set filters
* Specify a montage (used, for example, for export to current montage)
* Run automatic eye and EKG artifact correction
* Define artifact topographies
* Turn artifact correction and view on and off
* Read and write events
* Edit default block epoch (for export around triggers)
* Edit triggers (for export around triggers)
* Mark a block for export, or send the block to Source Analysis or Top View
* Convert patterns to triggers
* Attach auxiliary files (e.g. elp, sfp) to the data file
* Send to MATLAB
* Specify display configurations for the BESA Research Main, SA, and Top View windows
* and more - see the full list of [[#Batch Commands|Batch Commands]]

An additional set of commands are available for operations in the '''Source Analysis Module''', allowing to load, create and fit dipole models, and save the results.

A further set of commands apply to '''Time-Frequency Analysis''', allowing to start TFC, change the display, save results, and run the beamformer or DICS analyses on a selected time-frequency range.

[[Image:Batch commands1.png]]

These operations will be extended in future program releases.

The module includes two tabbed windows:

* '''File List''': Define a list of files on which the operations will be performed.
* '''Batch''': Define or load '''batch commands'''. Run the batch.

=== Batch Tab ===

Load or define batch commands, and then apply them to the files in the File List.

[[Image:Batch processing (4).png]]

'''Add Command'''

* Press '''Add Command''' to add a new command to the batch. The following dialog is opened, showing the available commands:

[[Image:Batch commands1.png]]

* Select the desired command and press '''OK''' or double-click on the command. A dialog box is opened, allowing to specify individual command parameters.
* If you click on "Apply at beginning of batch" or "Apply at end of batch", the command will only be run at the beginning or the end of a batch. You can use this, for example, at the end of a batch to start a MATLAB script to perform statistics on the results of the batch.

'''Load and Save Batch'''

* Press '''Load Batch''' to load a previously defined batch or '''Save Batch''' to save the current batch to a file ('''<nowiki>*.bbat</nowiki>''').

'''Load Previous'''

* Press '''Load Previous''' to load the most recently used batch file. Whenever a batch is run, the current set of commands is written to the file '''Previous.bbat in''' the '''Scripts/Batch''' subdirectory. This file is loaded when you press '''Load Previous'''.

'''Clear All'''

* Clears all commands from the window.

'''View Log File'''

* Each time a batch is run, BESA Research adds information about the batch to a log file, with headings showing the date and time the batch was started. The file is opened automatically in Internet Explorer if errors occurred during processing. Otherwise you may open the file by pressing the '''View Log File''' button here or in the dialog that is displayed at the end of batch processing. 
* The log file is saved in xml format, and a JavaScript is used to format the display in web browsers. JavaScript should be enabled in the browser to obtain an optimal display of the results. If JavaScript is enabled, the log file is displayed as a list of headings for each batch. Click on a heading to display the results of the corresponding batch.
* To open the log file in the Notepad, hold the''' Shift '''key down when pressing the '''View Log File''' button.

'''Batch Command List'''

* Double-click on a command to edit it. See [[#Batch Commands|Batch Commands]] for descriptions of the dialogs that are opened to edit each command.
* Right click on a command to open a context menu allowing more options.

[[Image:Batch processing (5).png]]

* '''Delete''', '''Move Up''', '''and Move Down''' can also be applied to multiple selections.
* If you have made a multiple selection, the '''Del '''button will delete all the marked commands. '''Ctrl '''plus '''Up''' or '''Down''' '''cursor keys''' will move the marked commands up or down.
* '''Toggle Comment''' will add or remove a semicolon (;) in front of the command, to deactivate or reactivate the command.
* '''Toggle Command Only at Start/End''' will add or remove the text "Start_" or "End_" in front of the command. With these prefixes, the command will only be performed when the first file ("Start_") or the last file ("End_") in the file list is being processed.

'''Single Step Mode'''

* Check this item to step through the batch, one command at a time. A dialog is opened after each command, allowing to run the next command, continue the batch without single steps, or stop running the batch. See the'' “Pause''” command for further details.
* During a batch, press and hold down the '''Pause''' or '''Delete''' key to interrupt the batch and enter Single Step Mode. Press and hold down the '''Esc''' key to cancel the batch.

'''Changes in batch written to database'''

* Checked by default. If this item is unchecked, file display settings, such as Montage setting and Artifact correction display, are not written to the database. When the file is next opened in BESA Research, the settings made in the batch are not retained.

'''Leave files in the file list open after running the batch'''

* If this item is checked, files in the file list will remain open after the batch. This is useful, for instance, if you want to open a set of files, specifying the same montage and/or filter settings for each file.

Press '''OK''' to start running the batch. Each command is then applied in succession to each file in the File List.

Note that, while a batch is running press and hold down the''' Pause''' or '''Delete''' key to interrupt the batch and enter Single Step Mode. Press and hold down the '''Esc''' key to cancel the batch.

=== The log file ===

A protocol of each batch is written to the log file '''Batch.txt.''' (e.g. C:\Users\Public\Documents\BESA\Research_7_1\Scripts\Log\Batch.txt)

When you press the '''View Log File''' button, the file is opened in the Batch Log dialog. The Batch Log dialog will be opened automatically if there was an error during batch processing, unless you have used the ''BatchError'' batch command to suppress this behaviour.

'''Backup of the log file'''

When the log file is written, a backup of the previous version is written to '''Batch.txt.bak'''.

If the size of the log file exceeds 200 KB, it is renamed to '''Batch.txt_date_time''' (e.g. '''Batch.txt_2004-10-08_10-53-32'''), and a new version of '''Batch.txt''' is created.

=== Placeholders ===

A powerful feature of the batch commands is the ability to define file names and specify standard paths using placeholders. These are text strings enclosed by percentage (%) signs. They can be used in all batch commands where file names are specified.

'''Basename'''

{| class="wikitable"
! Placeholder !! Description !! Example
|-
|style="text-align:center;" width="10%"|'''%basename%'''
|width="40%"|replaced by the basename of the currently opened file.
|width="40%"|If the data file is named "f-spike.fsg", "%basename%-export.fsg" will be interpreted as "f-spike-export.fsg".
|-
|style="text-align:center;"|'''%basename-n%'''
|replaced by the basename of the currently opened file, but removing the last "n" characters from the name.
|If the data file is named "dongle-BB.fsg", "%basename-3%" will be replaced by "dongle", because the last 3 characters of the basename have been removed.
|-
|style="text-align:center;"|'''%-nbasename%'''
|replaced by the basename of the currently opened file, but removing the first "n" characters from the name.
|If the data file is named "BB-dongle.fsg", "%-3basename%" will be replaced by "dongle", because the first 3 characters of the basename have been removed.
|-
|style="text-align:center;"|'''%orgbasename%'''
|replace by basename of the current file in the file list (it has the same meaning as %basename% if no MAINFileOpen batch command was used in command list)
|
|-
|style="text-align:center;"|'''%base%'''
|replace by basename of the current file without the path
|
|-
|style="text-align:center;"|'''%orgbase%'''
|replace by basename of the current file in the file list without the path
|-
|style="text-align:center;"|'''%ext%'''
|replace by extension of the current file
|
|-
|style="text-align:center;"|'''%orgext%'''
|replace by extension of the current file in the file list
|
|-
|style="text-align:center;"|'''%basefolder%'''
|replace by folder of the current file
|
|-
|style="text-align:center;"|'''%orgbasefolder%'''
|replace by folder of the current file in the file list
|
|-
|style="text-align:center;"|'''%t%'''
|Log batch command only: time since start of batch on current file
|
|-
|style="text-align:center;"|'''%T%'''
|Log batch command only: current date and time
|
|-
|style="text-align:center;"|'''%label%'''
|Replace label of the most recent marked block by the block label, not including no. of averages
|
|-
|style="text-align:center;"|'''%LABEL%'''
| Replace label of the most recent marked block by the block label, including no. of averages

|
|-
|style="text-align:center;"|'''%scripts%'''
|replaced by the path to the Scripts folder.
|"%scripts%Batch" is where batches are saved by default; "%scripts%MATLAB" is the location of the standard MATLAB scripts used by BESA Research.
|-
|style="text-align:center;"|'''%montages%'''
|replaced by the path to the Montages folder.
|
|-
|style="text-align:center;"|'''%examples%'''
|replaced by the path to the Examples folder.
|
|}



'''Placeholders for folders'''

The following placeholders are the same as those used in the [Folders] section of '''Besa.ini''':

The strings enclosed by percent signs (%) are placeholders for the following folders in English-language versions of Windows. Folder names are different for the system and for other language settings. BESA Research will substitute the placeholders by the appropriate folder name for the Windows system and the system language:

* '''Windows 10 (English)'''

<div style="margin-left:1.27cm;margin-right:0cm;"> '''%localapp%''' = ""C:\Users[user]\AppData\Local\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Desktop as ""Desktop[user]\AppData\Local\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;"> '''%publicprog%''' = "Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = ""C:\Users\[user]\Documents\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as "Desktop\[User]\Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as''' %progdir%'''</div>

* '''Windows 7 (English):'''

<div style="margin-left:1.27cm;margin-right:0cm;">'''%localapp%''' = "C:\Users\[user]\AppData\Local\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Desktop as "Desktop\[user]\AppData\Local\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%publicprog%''' = "C:\Users\Public\Public Documents\BESA\Research_7_1". This folder is directly accessible from the Windows Explorer under "Libraries\Documents\Public Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = "C:\Users\[user]\Documents\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as ""Libraries\Documents\My Documents\Research_7_1" or "Desktop\[User]\My Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as''' %progdir%  '''</div>

=== Batch Commands ===

Batch commands are selected when the "'''Add Command'''" button is pressed in the "Batch" Tab. The commands are subdivided into five categories: General commands, commands for the Main module, for the Source Analysis module, imaging commands in the Source Analysis module, and commands for Time-Frequency Analysis. The commands have prefixes,''' GEN''', '''MAIN''',''' SA''', '''SAIMAGE''', and''' TFC'''), which identify the category. For compatibility with older program versions, old batches without the prefixes are accepted.

Detailed descriptions of each batch command are available in the electronic help chapter “''Batch Processing and Combining Conditions / Batch Processing / Batch Commands”.''

'''General commands''' - prefixed with "'''GEN'''" (can be used anywhere):

{| cellspacing="8" style
| style="width: 180pt"| GENBatchError || used to change program behavior when errors occur
|-
| GENBatchWindowPosition || set the position of the batch window relative to the main window
|-
| GENComment || comment in the batch script: no batch functionality
|-
| GENMATLABcommand || send a command string to MATLAB
|-
| GENMATLABwaitForVariable || tells BESA to wait until Matlab has created a variable with the specified name.
|-
| GENPause || pause batch operations, allowing step-by-step operations
|-
| GENFor/GENEndFor|| a programming language-like FOR loop
|-
| GENRunProcess || runs a command-line process, e.g. an external program to perform part of the data analysis in the batch
|-
| GENsaveBitmap || save a screenshot of the Source Analysis or the 3D window
|-
| SetVariable || the value of the variable is inserted into subsequent batch commands where the text contains the name flanked by % signs
|-
| GENWindowPosition || set window size and positions to a selection of standard settings, e.g. for bitmap export
|}

'''Commands for the Main Module''' - prefixed with "'''MAIN'''":

{| cellspacing="8"
| style="width: 180pt"| MAINArtifactCorrect || run automatic artifact correction
|-
| MAINArtifactMethod || specify the method for artifact correction
|-
| MAINArtifactOn || turn artifact correction an artifact view on or off
|-
| MAINArtifact Scan || run an artifact scan as from the Paradigm Dialog
|-
| MAINAuxiliaryFiles || associate auxiliary files (e.g. *.''ela'', *.''sfp'') with the data file
|-
| MAINAverage || average the data
|-
| MAINBaseline || specify the parameters for baseline correction
|-
| MAINDefineArtifactTopography || define an artifact topography
|-
| MAINEditDefaultEpoch || edit the default block epoch
|-
| MAINEventRead || read events from an ASCII event file
|-
| MAINEventWrite || write events to an ASCII event file
|-
| MAINExport || export or append data in the selected target format
|-
| MAINExportToBESAConnectivity || export data segments to BESA Connectivity
|-
| MAINFFT || calculates the FFT spectrum of the marked data interval
|-
| MAINFFTmean || starts an averaging procedure that calculates the mean spectral properties in pre-defined regions
|-
| MAINFFTsave || saves FFT data (generated using the ''FFT Average option'' in the ''Average ''command) to disk (*.''fma)''
|-
| MAINFileOpen || close the current file and open a new file to which the remaining batch commands will be applied
|-
| MAINFileClose || close the currently open file in a batch, provided it is not the current file in the File List
|-
| MAINFilter || set filters
|-
| MAINfMRIArtifact || turns on the fMRI artifact removal
|-
| MAINGoTo || jumps with the cursor to the specified time point
|-
| MAINICA || starts ICA decomposition of data on the current screen
|-
| MAINICAsave || saves selected ICA components as topographies in a file
|-
| MAINICAselect || opens component selection dialog for managing ICA components
|-
| MAINImportASCII || import an ASCII file into a ''<nowiki>*.fsg</nowiki>'' file.
|-
| MAINMarkBlock || mark a data block (optionally send to Source Analysis)
|-
| MAINMarkChannels || mark one or more channels, as given by the list
|-
| MAINMaxInInterval || within the current marked block, search for the largest absolute value on the specified channel
|-
| MAINMontage || change the montage (used by the Export command when saving to current montage)
|-
| MAINParadigm || load a paradigm file
|-
| MAINPatternToTrigger || convert a tag into a trigger
|-
| MAINPolygraphicFilters || sets filters for polygraphic or added channels
|-
| MAINScale || set amplitude and time scales
|-
| MAINSearchAverageView || start search average view
|-
| MAINSendToMATLAB || send data to MATLAB
|-
| MAINSplineConstant || set the spline constant used in spherical spline maps and channel interpolation
|-
| MAINTriggerRecode || the command recodes a specified trigger number to a new number
|-
| MAINTriggerSelect || edit the trigger list (cf. ''Edit / Trigger Values''...)
|-
| MAINTriggerTagDelete || delete one or more triggers or tags
|-
| MAINViewAverageBuffer || turn on the Average Buffer View and place the specified buffer number to the left in the display
|-
| MAINViewChannelType || select the channel type to display, and select channel types for mapping, export, etc
|-
| MAINViewSelected || turns selected view on or off
|}

'''General commands for Source Analysis''' - prefixed with "'''SA'''" (but see also ''MarkBlock'', which is used to send a block of data to SA and open the SA window):

{| cellspacing="8"
| style="width: 180pt"| SAAddSource || add a dipole or regional source to a model
|-
| SAChannelTypeForFit || switch between EEG, magnetometers or axial gradiometers, and planar gradiometers
|-
| SAConvertSource || convert a source from dipole to regional source, or from regional source to dipole
|-
| SAcorticalClara || run Cortical CLARA
|-
| SAcorticalLoreta || run Cortical LORETA
|-
| SADelete || delete current solution or all solutions or remove current fit interval or cursor
|-
| SADICS || start DICS computation (if DICS has been precomputed in the time-frequency image command)
|-
| SADisplayMRI || switch MRI display on/off and select small or large window
|-
| SAElectrodeConfiguration || equivalent to pressing the Org or Std button in the Channel box of the Source analysis window
|-
| SAExit || close Source Module
|-
| SAFit || start fit
|-
| SAFitConstraint || set fit constraints, e.g. Residual Variance, Energy, Maximum Distance, Image Weighting, and their weights.
|-
| SAFitInterval || set fit or baseline interval
|-
| SAHeadModel || set the head model
|-
| SALabelSource || set the label of the specified source number
|-
| SAMinimumNorm || run a minimum norm analysis
|-
| SANewSolution || open a new solution
|-
| SAOpenSolution || open a solution from a file
|-
| SAPCA || toggle PCA display of data or residual, and transfer a selected number of components to the source model
|-
| SARegularization || set the regularization values both for discrete and distributed source images
|-
| SASaveBitmap || save a screenshot of the Source Analysis or the 3D window
|-
| SASaveLeadfields || save the leadfields of the current source model
|-
| SASaveModelWaveforms || save model waveforms
|-
| SASaveResidualWaveforms || save residual waveforms
|-
| SASaveRVandGFPWaveforms || save residual variance and global field power waveforms
|-
| SASaveSolution || save the current solution
|-
| SASaveSourceMontage || save a source montage
|-
| SASaveSourceWaveforms || save source waveforms
|-
| SASendToMATLAB || send data, model, source waveforms, images, etc. to Matlab
|-
| SASetCursor || set the cursor
|-
| SASetDefaultSourceType || set the default source type (dipole or regional source)
|-
| SASetOrActivateSource || Turn specified source on or off, or enable/disable source for fitting
|-
| SASetOrientation || set orientation (of regional source)
|-
| SASwitchCondition || switch to a specified condition
|}

'''Commands for Distributed 3D Volume Images'''

{| cellspacing="8"
| style="width: 180pt"| SAIMAGEBeamformer || switch between Single Source and Bilateral Beamformer image
|-
| SAIMAGEBeamformerTimeDomain || start beamformer computation in the time domain
|-
| SAimageBrainAtlas || turns on the Brain Atlas overlay on volumetric image
|-
| SAIMAGECLARA || generate CLARA image
|-
| SAIMAGEClip || clip image values under a threshold
|-
| SAIMAGEExport || save the results of minimum norm or 3D imaging method
|-
| SAIMAGEGotoMax || set the crosshair cursor at the nth maximum in the image
|-
| SAIMAGEImport || load a 3D volume image from file
|-
| SAimageImportFMRI || import fMRI image to Source Analysis Module
|-
| SAIMAGELAURA || create LAURA image
|-
| SAIMAGELORETA || create LORETA image
|-
| SAIMAGESLoreta || create sLORETA image
|-
| SAimageSESAME || start SESAME computation
|-
| SAIMAGESSLOFO || create SSLOFO image
|-
| SAIMAGEUser-Defined || create user-defined image
|-
| SAIMAGESaveLeadfields || save the leadfields of all the voxel sources in a 3D image
|-
| SAIMAGEClip || clip current 3D image
|-
| SAIMAGESmooth || smooth current 3D image
|-
| SAIMAGESetCrosshair || set the position of the crosshair in the 3D image
|}

'''Commands for Time-Frequency Analysis''' ('''TFC''')

{| cellspacing="8"
| style="width: 180pt"| TFCStartTFAnalysis ||(previously TFCgo) start TFC analysis using the current paradigm settings
|-
| TFCdisplay || change the TFC display (e.g. power/amplitude, coherence)
|-
| TFCsave || save numerical results to an ASCII file, or save a screenshot of the TFC window
|-
| TFCimage || start beamformer analysis on a selected time-frequency range
|-
| TFCSendToMATLAB || send TF results or single-trial data to MATLAB
|}

=== How to Average Your Data in a Batch ===

Using batch processing, several files from an experiment can be averaged at a time.

Here we summarize the steps required:

'''Before running the batch'''

* Create the paradigm, and save the paradigm file.
* Open each individual data file to check the data:
** Make sure auxiliary files are defined and loaded properly, and the data are displayed correctly.
** Eyeball the data.
** Define bad (and interpolated) channels.
** Mark artifact time ranges.
** If required, set up artifact correction for the file.
** The data file can be closed again after this step.

'''Preparing the batch'''

* Open at least one file and select ''Process / Batch Scripts''.... The file(s) should be displayed in the file list. Alternatively, just select ''Process / Batch Scripts...,'' and add the files by
** pressing the '''Add File''' button
** dragging the files from Windows Explorer
** Opening a previously saved list with ''Load File List''

* You can delete files from the list (press '''Del''') or edit the file sequence using the right click context menu.
* Select the ''Batch Tab''.
* Add commands to your script. For averaging, these would normally be
** '''Paradigm''' -- to load the paradigm file
** '''Artifact Scan''' -- to run the artifact scan
** '''Average''' -- to perform the average

* Save these commands (press '''Save Batch''').
* Test the commands on the files in the current file list: press '''OK'''
* Look at the log file (press '''View Log File''') to check the results of averaging.
* Look at the data averages to make sure they have been done correctly.
* Repeat these steps until averaging is working properly.

'''Running the batch'''

* Select ''Process / Batch Scripts''....
* Open the files you want to average in the batch in the file list:
** Any files that were open in BESA are included in the list
** Files can be added using the '''Add File''' button
** You may drag one or more files from Windows Explorer to the file list
** Alternatively, load a previously saved file list.

* Edit the file list, e.g. delete unwanted files (use the '''Del''' key or the right click context menu), or reorder the files (use '''Ctrl + cursor keys''' or context menu).
* Note that the order of files in the list specifies the order in which they will be processed in the batch script. This order will be important if all results are saved to the same target file. Otherwise the file sequence is not important.
* Optionally, save the file list (press '''Save Batch'''
* Select the ''Batch Tab'', and load the previously defined batch script with ''Load Batch''.
* Press '''OK''' to run the batch.

=== How to Merge and Compress raw data ===

Using the Export command in a batch, several data files can be merged into a single data file in BESA's data format ('''<nowiki>*.foc</nowiki>''').

This can be useful if data from one subject have been collected in several data blocks, and you want to analyze all data blocks together.

Optionally, to save space, data can be saved in compressed format.

'''Files can be merged:'''

* if they have identical channel configurations, or
* there are at least 16 EEG channels, and the export format is Standard 81 (i.e. EEG channels are interpolated to 81 standard locations).

'''How to merge files:'''

* Select '''Process / Batch Scripts...'''
* Add all the files that are to be merged to the file list:
** Any files that were open in BESA Research are included in the list
** Files can be added using the '''Add File''' button
** You may drag one or more files from Windows Explorer to the file list
** Alternatively, load a previously saved file list (''Load File List'').
* Rearrange the files in the file list to the sequence in which they should be merged.
* Select the ''Batch Tab ''and insert an "''Export"'' command, as described below.

The following dialog shows a possible configuration of the ''Export'' command:

[[Image:Batch processing (4).gif]]

* The parameters shown in the Information box are the settings chosen in the ''Export Dialog'' when the '''Select Options''' button has been pressed.
* '''Append if file already exists''' must be checked in order to merge the files.
* The '''target file name''' must be fixed, i.e. don't use the '''%basename%''' variable, because that will result in a different target file name for each source file.
* There are two variables that can be used for the segment label:
** '''%filename%''' will insert the basename of the source file into the segment label.
** '''%c%''' will insert the file number into the segment label. The number gives the position of the file in the file list. For instance, "File %c%" will generate the label "File 2" for the second file in the list.

=== Example: Data averaging in the auditory intensity experiment ===

In this example, two raw data files, '''s1.cnt''' and '''s2.cnt''', from the auditory intensity experiment will be batch averaged.

Please note that there are further tutorials covering this experiment. The first file is contaminated by many eyeblinks, and more epochs would be averaged if eye correction were used (see Viewlet demonstration on artifact correction on the BESA website). However, in this tutorial, we will just use artifact rejection.

'''A. Various ways of creating a File List'''

1. '''Files that were open in BESA Research are automatically added to the File List.''' Start BESA Research and open the files '''s1.cnt '''and '''s2.cnt '''in the directory ''Examples\ERP-Auditory-Intensity''.

2. Select ''Process / Batch Scripts''.... You should see the file names in the '''''File List Tab''''' something like this:

[[Image:Batch processing (5).gif]]

3. You can resort the files in the file list alphabetically by clicking onto the '''''File List column header''''':

[[Image:Batch processing (6).gif]]

Alternatively, you can mark any file, hold down the '''Ctrl '''key and press the '''Up''' or '''Down arrow '''to move the file name up or down the list. This is the sequence in which files will be processed in the batch.

[[Image:Batch processing (7).gif]]

4. Press '''Save File List''' and save the list you have created to '''ERP-Aud-Ex1.flist'''.

5. Highlight both names and press the''' Del '''button to remove them from the list.

6. '''Files can be dragged from Windows Explorer'''. Start Windows Explorer and navigate to the ''ERP-Auditory-Intensity'' subdirectory of your BESA Research examples folder (located in the ''Public Documents'' folder of your computer). Click on '''s1.cnt''' and drag it with the mouse onto the '''''File List Tab'''''. Let go of the mouse. BESA Research opens the file, and displays the name in the File List. Repeat for '''s2.cnt.'''

7. Highlight both names and press the '''Del '''button to remove them from the list.

8. '''Files can be added using the ''Add File'' button'''. Press '''Add File''' and navigate to the ''Examples\ERP-Auditory-Intensity'' subdirectory. Select '''s1.cnt'''. Press '''Ctrl''' and select '''s2.cnt'''. Both names should then be displayed in the ''File Open'' dialog. Press '''OK''' to add the files to the file list.

9. Highlight both names and press the '''Del''' button to remove them from the list.

10. '''Files can be loaded from a previously saved file list'''. Press '''Load File List '''and select '''ERP-Aud-Ex1.flist''', the list you saved in step 6 above.

'''B. Setting up the batch'''

1. We will add three commands, '''Paradigm''', '''Artifact Scan''', and '''Average''', to create a batch that will be applied to the two files in the file list.

2. Click on the '''Batch Tab'''.

[[Image:Batch processing (8).gif]]

3. Press the '''Add Command''' button to obtain the ''Select Command'' window:

[[Image:Batch processing (9).gif]]

4. Click on '''Paradigm''' and then on '''OK''' (alternatively, double-click on '''Paradigm'''). Hit '''Browse''', navigate to the ''Auditory'' folder, and select '''AEP_Intensity.pdg''', the paradigm for the auditory intensity experiment.

[[Image:Batch processing (10).gif]]

5. Press '''OK''' to obtain the ''Load Paradigm Task'' window.

[[Image:Batch processing (11).gif]]

6. Press '''OK''', and the first task in the batch is ready, and listed in the Batch Command window. If you want to modify the command, double-click on it to open the above window, that allows to browse for a different paradigm file.

[[Image:Batch processing (12).gif]]

7. Next, we add the '''Artifact Scan''' command. Click on the '''Add Command''' button, and select ''Artifact Scan.''

[[Image:Batch processing (13).gif]]

8. Press '''OK''' to open the ''Artifact Scan Task'' window. We want to be able to view the results of the scan, and adjust thresholds and bad channels if necessary. Therefore, check the ''Wait after scan'' checkbox.

[[Image:Batch processing (14).gif]]

9. Press '''OK''' to close the ''Artifact Scan Task'' window. Our batch now contains two commands.

[[Image:Batch processing (15).gif]]

10. Finally, we will add an '''Average''' command. Press the '''Add Command''' button and select ''Average''. Press '''OK''' to open the ''Average Task ''window.

[[Image:Batch processing (16).gif]]

11. With the default settings, the average would be saved to the same directory as the data. The file name mask is set by default so that in this example the two averages would be saved to '''s1-av.fsg '''and '''s2-av.fsg'''. We will save the averaged files to subdirectory ''"Averages''" of the data directory. Uncheck the ''Use default target'' check box, change the File name mask to '''%basename%_av-test''' in order not to overwrite the predefined files.

[[Image:Batch processing (17).gif]]

12. Press '''OK '''to close the ''Average Task'' window. Our batch is now complete.

[[Image:Batch processing (18).gif]]

13. We will now save the batch so that it can be used again. Press the '''Save Batch''' button, and save to the file '''ERP-Aud-ex1.bbat'''. Note that an easy way to generate new averaging batches is to load a previously save batch and edit the commands -- it may only be necessary to edit the '''Paradigm''' command to select the relevant paradigm file, and maybe to adjust the target directory in the '''Average''' command.

14. Press '''OK''' in the ''Batch'' Window to start the batch running. As requested, the batch pauses after the artifact scan:.

[[Image:Batch processing (19).gif]]

You may now adjust the number of rejected trials, e.g. by moving the vertical red bar to the left or exclude bad channels.

15. Press '''OK''' to continue with averaging.

[[Image:Batch processing (20).gif]]

16. Note that, in the background, the ''Batch Running'' window is providing feedback about the current file and current task.

[[Image:Batch processing (6).jpg|400px]]

17. The batch will stop again after the next artifact scan. Press '''OK''' to allow the batch to run to the end.

[[Image:Batch processing (21).gif|400px]]

18. Press '''View Log''' to view the batch log.

19. The batch log gives feedback about the number of epochs that were averaged for each file.

20. Finally, press '''OK''' to return to the main BESA Research display. Open the averages in the ''Averages'' subdirectory to confirm that they were generated properly.

=== Example: Merging files using the Export Command ===

Here we will demonstrate the use of the '''Export '''command to merge two files. We will combine the two averages from the previous example (Data averaging in the auditory intensity experiment) into one target file.

'''A. Generate the file list'''

# Start BESA Research and load the two data files '''S1_av-test.fsg''' and '''S2_av-test.fsg''' that were saved in the previous example.
# Select ''Process / Batch Scripts....''The two file names should be displayed in the file list.
# In the file list, make sure that '''s1_av-test.fsg '''is the first file in the list. If it is not, highlight the file, and move it up using '''Ctrl+up''', or right click and select ''Move Up'' in the context menu.

'''B. Generate the batch'''

1. Press the '''Add Command''' button, and select the '''Export''' command.

2. Press '''OK''' to open the ''Export Task'' window.

[[Image:Batch processing (24).gif]]

3. Press the '''Select Options'''... button to open the ''Export Dialog''.

[[Image:Batch processing (25).gif]]

4. Since we are combining averages, select ''Hires (no compression)'' in the '''Target data format''' drop-down list (If we were merging raw data files, it is better to select compression. Press '''OK '''to close the dialog. Check'' Append if file already exists'', so that the files will be merged. Enter '''s1+s2''' in the target file name mask edit box. This ensures that both files will be saved to the same target: '''S1+S2.fsg'''.

[[Image:Batch processing (26).gif]]

5. Press '''OK '''to close the ''Export Task'' window. The '''Export '''command is displayed.  

[[Image:Batch processing (27).gif]]

6. Optionally, you may save the batch file by pressing '''Save Batch'''.

7. Press '''OK''' to run the batch, and '''OK''' in the ''Batch Completed'' window to return to the BESA main window.

8. Finally, open the file '''S1+S2.fsg''' to confirm that it contains the two merged files.

'''C. Merge raw data'''

# Repeat the above task to merge the two raw data files '''S1.cnt''' and '''S2.cnt''' into a single target file '''S1+S2.foc'''. In this case, select one of the compression options as the target data format. Note that you would not normally want to merge two files from different subjects. However, several data blocks from the same subject can conveniently be merged using this method.

Note that ''<nowiki>*.fsg</nowiki>'' files can also be merged using the ''Combine Conditions'' dialog. 

== Combine Conditions, Channels ==

=== Combine Condition Scripts ===

With the Combine-Conditions module you can do a variety of operations on BESA averages (files with the extension '''<nowiki>*.fsg</nowiki>''', and other segment files, such as '''<nowiki>*.mul</nowiki>''', '''<nowiki>*.avr</nowiki>''', '''<nowiki>*.swf</nowiki>'''):

* Create grand averages
* Combine averages (add, subtract, weighted/unweighted)
* Merge files
* Exclude unwanted averages
* Rename conditions
* Rename or resort channels
* Generate averages or differences over selected channels
* Transform the data: standard interpolated 81 electrodes, change sampling rate, change interval
* Determine peaks, mean amplitudes, or integrals on data averages
* These operations can be performed on one or more files simultaneously. Results of an operation are stored in a single target file.

The module includes four tabbed windows:

* File List: Define a list of files on which the operations will be performed.
* Condition List: List the condition names, define target condition names, and how input conditions are combined into target conditions.
* Channel List: List the channel names, define target channel names, and how input channels are combined into target channels.
* Run Scripts: Define global options for the output (e.g. spatial interpolation, resampling, copy/merge or average, peak analysis). Start the operation.
* Note that in all four tabs, configurations can be saved for future use, and the '''Load Previous''' button restores the most recently used configuration.

=== Condition List Tab ===

List the condition names, define target condition names, and how input conditions are combined into target conditions.

The first column of the list box shows a list of all the condition names found in the source files.

Rows of the list box define the source conditions. Columns define the target conditions.

'''Initial setting'''

When first selecting the tab, each column shows each condition name found in the source files (as in the example below). In the list box, there is a "+1" along the diagonal. The result of this selection is that target conditions will have the same name as source conditions. Right click on source condition labels to view properties (e.g. no. of samples, time range, sampling rate).

[[Image:Batch processing (28).gif]]

'''Editing the condition list'''

* Target condition names can be edited, inserted or deleted by clicking on the label at the top of each column.
* Click on a box within the list to toggle between "+1", "-1" and blank. These correspond to the operations:
** "+1" = add
** "-1" = subtract
** blank = do nothing
* Right click on a box for further operations: conditions can be weighted by a given factor other than 1.

'''Divide result by sum of PLUS factors'''

* Normally, when creating an average over conditions, the sum is divided by the number of conditions or a weighted average is generated (see below).  If "''Divide the result by the sum of PLUS factors''" is unchecked, the conditions will be summed rather than averaged.
* Note that, when making differences between conditions, no such division is required. BESA Research will uncheck the checkbox automatically if subtraction ("-1") is specified somewhere in the condition list.

'''Weighting of averages'''

* Below the list, click on the ''Weighted Average'' row to toggle "YES" and "NO". "YES" means that averages will be weighted by the number of epochs contributing to the average. For instance, if average A contained 100 epochs and average B contained 200 epochs, the weighted average will be computed as

<div style="margin-left:1cm;margin-right:0cm;">(100 * A +  200 * B) / (100 + 200)</div>

<div style="margin-left:1cm;margin-right:0cm;">Select "NO" for an unweighted average. For the above example, the average is computed as</div>

<div style="margin-left:1cm;margin-right:0cm;">(A + B) / 2</div>

<div style="margin-left:1cm;margin-right:0cm;">Weighted averages are not permitted if one of the boxes contains a negative value.</div>

* Values other than +1 or -1 in the boxes apply a different kind of weighting. For instance, we want to compute the difference between the means of conditions A, B, C and D, E. Use a right-click to specify the fraction 1/3 for each of A, B, and C, and -1/2 for each of D and E (see example below).

[[Image:Batch processing (29).gif]]

'''Save the current condition list'''

* Press the '''Save Condition List''' button.

'''Load a condition list'''

* Press the '''Load Condition List''' button.

'''Load previous settings'''

* Press the '''Load Previous''' button

'''Feedback'''

* Conditions that have different numbers of electrodes (averaging across different files) can only be combined if channels are interpolated to a standard set of electrodes.
* Conditions that have different durations or sampling rates can only be combined if the sampling rate and durations are made the same.
* Feedback about the above situations is displayed by the presence of tick marks above the list box.

=== Channel List Tab ===

List the channel names, define target channel names, and how input channels are combined into target channels.

Note that this tab is very similar in usage to the '''Condition List Tab'''. Note also that some of the functions performed in this tab could also be done in the Montage Editor. It may be a matter of convenience whether you choose to perform these operations here or in the Montage Editor.

The first column of the list box shows a list of all the channel names found in the source files.

Rows of the list box define the ''source'' channel. Columns define the'' target'' channel.

'''Initial setting'''

When first selecting the tab, each column shows each channel name found in the source files (as in the example below). In the list box, there is a "+1" along the diagonal. The result of this selection is that target channel will have the same name as source channel.

'''Combining files'''

If files with different channel configurations are included in the File List, the rows and columns of the Channel List Tab will only contain the labels for the channels that are in common among the files.

If the files in the File List have a different sequence of channels, the sequence of the first file in the list will be adopted in the Channel List.

Thus, for the initial setting, unless the "''Ignore Settings in this Tab''" checkbox is checked, the target grand average or peak/amplitude analysis, etc. will be applied using only channels that are in common among the input files, and using the channel sequence of the first file in the File List. By changing the target channels or by changing the entries in the Channel List, new channels consisting of averages or differences can be generated.

'''What can the Channel List be used for?'''

Some examples:

* Reorder or relabel channels
* Create channel differences
* Create averages over channel groups, e.g. for peak analysis
* Extract a selection of channels for peak analysis or mean amplitudes
* Create grand averages across files with different channel configurations, just using channels in common among the files

[[Image:Batch processing (30).gif]]

'''Editing the channel list'''

* Target channel names can be edited, inserted or deleted by clicking on the label at the top of each column.
* Click on a box within the list to toggle between "+1", "-1" and blank. These correspond to the operations:
** "+1" = add
** "-1" = subtract
** blank = do nothing
* Right click on a box for further operations: channels can be weighted by a given factor other than 1.

'''Divide result by sum of PLUS factors'''

* Normally, when creating an average over channels, the sum is divided by the number of channels or a weighted average is generated (see below).  If "Divide result by the sum of PLUS factors" is unchecked, the channels will be summed rather than averaged.
* Note that, when making differences between channels, no such division is required. BESA Research will uncheck the checkbox automatically if subtraction ("-1") is specified somewhere in the channel list.

'''Save the current channel list'''

* Press the '''Save Channel List''' button.

'''Load a channel list'''

* Press the '''Load Channel List '''button.

'''Load previous settings'''

* Press the '''Load Previous''' button

=== Run Scripts Tab ===

Define global options for the output (e.g. spatial interpolation, resampling, copy/merge or average, peak detection. Start the operation.

[[Image:Batch processing (7).jpg]]

'''Load or Save Settings'''

* You can save the current settings of this tab to a file (*.run) which can be loaded later.
* When you run the script, the current settings are saved automatically to a file "'''PreviousSettings.run'''".

'''Load Previous'''

* Press this button to load the previous settings (from "'''PreviousSettings.run'''").

'''Averages to Generate'''

* '''Generate separate averages for each source file'''. Averages are performed over conditions within the source file, and are then appended to the target file.
* '''Combine data from source files'''. Conditions are combined over all source files into a single target average.
* '''No averages, just copy'''. Files are copied and merged to the target file. Use this option for renaming conditions, merging files, removing unwanted averages (see below), changing the sampling rate and interval.
* '''Peaks and mean amplitudes'''. Specify time ranges for peaks, mean amplitudes, or integrals (areas).
* Note: When generating or copying averages (first three options), filters and baseline settings are turned off. For Peaks and mean amplitudes, filters and baseline settings are specified in the dialog.

'''Spatial Interpolation'''

* '''Interpolate to Standard 81 electrodes'''. The target file will contain only electrodes (other channels are omitted), using the Standard 81 configuration (as in other export functions within BESA Research). This cannot be selected if the source data contain less than 16 EEG channels.
* '''Interpolate Bad Channels'''. Bad electrode channels in the source file will be interpolated. If the above option is deselected and bad channels exist in one or more of the source files, this option is always on.

BESA Research can interpolate EEG, and MEG if the sensors are axial gradiometers or magnetometers. If other channels are marked as bad in one or more of the source files, these will be defined as bad in the target file. This applies to MEG planar gradiometers, to polygraphic data, and to ICR channels.

'''Temporal Interpolation'''

* '''Spline to New Sampling Rate and Interval'''. Data can be converted to a new sampling rate, and the interval can be changed.
** If the sampling rate is reduced, the data will be low-pass filtered at 1/3 sampling frequency before reduction.
** If the sampling interval is changed, the prestimulus and poststimulus intervals are limited by the smallest intervals in the conditions contributing to the averages. These limits are shown below the edit boxes.

'''Peaks and Mean Amplitudes'''

[[Image:Batch processing (31).gif]]

'''Peaks:'''

* Select the time range between which peaks are to be determined.
* Select the montage on which the peaks are to be determined.
* Define the filter settings.
* Define the baseline settings.
* Specify whether peaks are to be defined at one latency: if so, select the channel on which peaks are to be detected.
* Specify whether you want to find positive or negative peaks.

'''Mean amplitudes and areas:'''

* Select the time range over which the mean amplitudes or areas are to be determined.
* Select the montage on which the mean amplitudes or areas are to be determined.
* Define the filter settings.
* Note that when computing areas, data are first rectified (made positive) and then summed over the time range.

'''Output options of the analysis:'''

* A single ASCII file that contains the result of the analysis for all data sets, conditions, and channels including header and information lines.
* A sparse output suitable for import in SPSS. Each variable (e.g. a latency, a channel amplitude) constitutes one column of the output file.
* Direct transfer to MATLAB into a struct besa_peak. For more information on the data transfer from BESA Research to MATLAB, please refer to help chapter ''“The MATLAB interface”.''

'''Starting the Operation'''

* Press '''OK''' to start the operation. After the operation is completed, and the "Open target file in BESA" box is checked, BESA Research will open the target file.  "Open target file in BESA" cannot be checked if "Peaks and mean amplitudes" was selected - then the result of the operation will be an ASCII file or a MATLAB transfer.
* You will be asked for the name of the target file (unless a MATLAB transfer of peak data has been performed).

'''Restrictions'''

* Depending on source file configurations, not all options above are selectable. For instance, if two files contain different numbers of electrodes, and the "''Ignore Settings in this Tab''" checkbox is checked in the '''''Channel List''''' Tab, spatial interpolation to Standard 81 is enforced in the target. Similarly, if different sampling rates are used in different files, temporal interpolation is enforced.
* You are not allowed to add files to the file list if the channel configuration is different, and the data cannot be combined with Standard 81 interpolation. Since Standard 81 interpolation is only possible for EEG, multiple files without EEG can only be loaded if they have the same number of channels.

=== How to Create Grand Averages ===

* Open the files you want to average in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. To average across different conditions, click in the list boxes to obtain "+1" for each source condition to combine, and rename the target condition to define a meaningful name for the average.
* Click on the '''Run Scripts Tab'''.
* If you have more than one file, specify whether averages should be generated across files ('''Combine data from source files''') or within files ('''Generate separate averages for each source file''').
* Select other options if required (spatial or temporal resampling).
* Press '''OK'''.

=== How to Generate Differences Between Conditions ===

* Open the files you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. To create differences, click in the list boxes to obtain "+1" for one of the source conditions, and "-1" for the source condition to subtract, and rename the target condition to define a meaningful name for the difference.
* Click on the '''Run Scripts Tab'''.
* If you have more than one file, specify whether averages should be generated across files ('''Combine data from source files''') or within files ('''Generate separate averages for each source file''').
* Select other options if required (spatial or temporal resampling).
* Press '''OK'''. An average of the differences is generated. If only one example of each condition exists, e.g. in a grand average file, the result is the difference between conditions.

=== How to Merge Files ===

* Open the files you want to merge in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions''...).
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press '''OK'''.

'''Notes'''

* If the source files have different electrode configurations, use the Standard 81 configuration for the target.
* If the source files have different sampling rates or intervals, use Temporal Interpolation.

=== How to Remove Unwanted Averages ===

'''Removing one or more unwanted segments'''

* Normally, all conditions are read from a source file. To exclude one or more segments from operations in the Combine Conditions module, mark the segments as artifacts in the main program display. It is sufficient for the beginning or the end of an artifact interval to be within the segment for the segment to be excluded.
* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press''' OK'''.
* The target file contains the copied data without the conditions that were marked as averages.

'''Removing one or more unwanted conditions (by label)'''

* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Deselect the target conditions you want to omit (replace the "+1" by a blank).
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press''' OK'''.
* The target file contains the copied data without the conditions that were marked as artifacts.

=== How to Rename Conditions ===

* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions''...).
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. Click on column headings to rename the target conditions.
* Click on the''' Run Scripts Tab'''. Select "''No averages, just copy''".
* Press '''OK'''.
* The target file contains the copied data with the renamed conditions.

=== How to Change the Sampling Rate ===

* Open the file(s) you want to change in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...'').
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Select "''Spline to New Sampling Rate and Interval''" and type the new sampling rate into the edit box.
* Press '''OK'''.

=== Example: Create grand average and combinations of conditions ===

In this example, we will generate a grand average of the results of the Auditory Intensity Experiment. The experiment includes averages from five different stimulus intensities. We will create a grand average over each intensity, but also include means over the two lowest and the two highest intensities, and the difference between these two combinations.

'''A. File selection'''

# Start BESA Research and open files '''S1_av.fsg - S10_av.fsg''' in the ''Examples\ERP-Auditory-Intensity'' folder. The files contain the individual averaged data of the 10 subjects who participated in this study.
# Select ''ERP / Combine Conditions...'' The file list should display the two files, with feedback about the number of averages and conditions. 8 epochs are found. See the ''“Data averaging in the auditory intensity'' ''experiment”'' example for examples how to manipulate the file list.

[[Image:Batch processing (32).gif]]

'''B. Define conditions'''

1. Click on the '''Condition List Tab'''. The initial window defines target conditions with the same name as the source conditions. To generate the grand average over these conditions we could proceed without further changes to the '''Run Scripts Tab'''. However, we want to modify the condition list and create a condition that contains the grand averaged difference between the''' High''' and '''Low''' conditions.

[[Image:Batch processing (8).jpg]]

2. Click on the '''All '''column label. In the resulting window, rename condition '''All''' to''' Difference'''. Then press '''OK'''.

[[Image:Batch processing (33).gif]]

3. The last column is now labeled '''Difference.''' Left-click twice onto the ‘'''+1’''' entry that links this condition to the '''All '''input condition. This will remove the link and leave the field blank. To define the ‘Difference’ condition as the average of ‘High’ minus ‘Low’ over subjects, left-click once into the field linking input '''High''' with target '''Difference''' to generate an entry ‘'''+1’''' in this field. Left-click twice into the field linking input '''Low '''with target '''Difference''' to generate an entry '-'''1'''’.

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;">[[Image:Batch processing (35).gif]]</div>

4. Press '''Save Condition List''' and save the list to '''ERP-aud-ex1.clist'''. This condition combination can thus be loaded later using the '''Load Condition List''' button.

'''C. Run the script'''

# Click on the '''Run Script Tab'''.
# The default tab settings are ready for generating the grand average ('''Combine data from source file''' and '''Open target file in BESA''' should be checked). Just press '''OK'''. Enter '''All_Subjects_cc-test.fsg''' as file name and press''' Save'''.

The resulting file contains the 8 target conditions, 60db, 70dB, 80dB, 90dB, 100dB, Low, High, and Difference.

=== Example: Average files from different experiments ===

This example is intended to illustrate several features of the ''Combine Conditions'' Dialog, such as electrode interpolation and resampling. We will combine an average from the Auditory Intensity experiment with one from the P300 auditory experiment. In this particular case, it is not a very meaningful thing to do, but it shows what is possible. For instance, the same experiment may have been performed using different sampling rates or electrode combinations. This example shows how such data may be combined.

'''A. File selection'''

# Start BESA Research and open the file '''All_Subjects_GA.fsg''' in the ''Examples\ERP-Auditory-Intensity'' folder. The file contains the grand average data from the auditory intensity experiment.
# Open the file '''RareFrequentResponseLeft.fsg''' in the ''Examples\ERP-P300-Auditory'' folder. This file contains averages from the P300 auditory experiment.
# Select ''ERP / Combine Conditions... ''Note that the files have different sampling rates and different numbers of electrodes.

[[Image:Batch processing (36).gif]]

'''B. Define conditions'''

1. Click on the '''Condition List Tab'''. Note that the feedback text at the bottom of the window displays the text "Standard 81 interpolation required to generate average; Across files: resampling or change in time range required to generate average". The condition labels show all the names from both files.

[[Image:Batch processing (37).gif]]

2. We will exclude most conditions, and just combine the most similar conditions from the two experiments: the "Standard" and the "80dB" conditions. Click on the title of the first column,''' Blink'''. Select “''Delete all conditions to the right of this column”'', and press '''OK'''.

[[Image:Batch processing (38).gif]]

3. Click on the title again, and rename the target condition to "Standard".

[[Image:Batch processing (39).gif]]

4. Click twice in the first line to remove the "+1" entry there. Click once in the third row ("Frequent"), and in the 7th row ("80dB"), to display "+1" at each entry. Thus, just two of the conditions will be combined into one target condition.

[[Image:Batch processing (40).gif]]

'''C. Run the script'''

1. Click on the '''Run Script Tab'''.

[[Image:Batch processing (41).gif]]

2. Note that '''Interpolate to Standard 81 electrodes''' is checked and grayed: since two different electrode sets are to be combined, we can only do this by interpolating electrodes. Also, both '''Spline to new sampling rate''' and '''Clip interval '''are checked and grayed. Again, these settings are required in order to be able to average the two data files together. The sampling rate is set to the higher of the two selections. The time range is set to the largest possible range that can be clipped from the two data sets. For now, leave these settings as they are, and press '''OK'''. Save the target to '''TestCombineExpts_CC-std81.fsg'''.

{{BESAManualNav}}

BESA Research Spectral Analysis

2021-11-02T12:42:53Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 6.1 or higher
}}

== Spectral Analysis - Introduction ==

There are two different types of spectral analysis in BESA Research:

# A '''Fast Fourier Transform (FFT)''' computes the total spectral content of a certain data interval, usually a few seconds or minutes long. This interval can be
#* a short data block of interest, typically a few seconds
#* an extended time range, e.g. between two markers or the whole data file ('mean FFT')
# '''Density spectral arrays (DSA)''' provide an overview of the temporal evolution of spectral activity over longer epochs (here: 15, 20 or 30 minutes) or the whole data file. DSA is useful for reviewing long recordings, since epochs where changes of frequency distribution or amplitudes occur can be identified at a glance.

== FFT ==

The Fast Fourier Transformation (FFT) can be applied to a marked region, the data displayed on the screen, over a larger time range in the data between two markers, over marked epochs, or the whole EEG, in order to examine the frequency content of a signal. Results of the FFT can be viewed in a variety of ways, including amplitude and power spectra, amplitude and power in frequency bands, and these results may be printed or written to data files in ASCII format. The previously calculated FFT spectrum may be redisplayed. The current FFT can be saved to a binary file and reloaded. Topographic maps of amplitude, power, and phase can be plotted.

'''FFT Computation and Display'''

Two FFT computations are available in BESA Research:

* [[#FFT over a short data block of interest | The FFT over a short data block of interest]]
* [[#Mean FFT Spectrum over an extended time range | The Mean FFT over an extended time range]]

=== FFT over a short data block of interest ===

To start an FFT calculation, highlight a data block by left mouse click and drag. If no block is highlighted, the FFT will be performed over the time range shown on the display. Apply one of the following:

# Right-click into the marked block and select the item ''FFT''.
# Type the HotKey '''F'''.
# Select the item ''FFT-Spectrum'' in the '''Process''' menu ('''Alt+P, F''').

[[Image:Spectral (2).gif ]]      [[Image:Spectral (1).gif ]]

'''Note:''' It is not possible to select the FFT process if the region to be processed contains less than 128 samples. This can occur, for instance, if the time range of a highlighted region is too short.

'''Note''': When an FFT is selected, BESA Research displays the results for the current montage on the screen. In the background, the program also performs the FFT on 81 standard interpolated, average referenced channels in the case of EEG and on the average referenced data in the case of MEG. When FFT results are saved to a file, you have the choice of saving either the current montage or the 81 interpolated, average referenced channels (only for EEG). Maps of the FFT results are always based on the average referenced data. This is necessary to ensure that electrodes are given equal weights in the nonlinear transformation to power or amplitude (= root of power).

For an FFT over a marked block or the whole screen, no parameters have to be specified. Internally, BESA Research preprocesses the selected data segment for the FFT in two steps:

# A window function is multiplied with the data to attenuate the amplitudes at the ends to zero
# The number of samples is increased by interpolation (if necessary) to make it a power of 2.

This preprocessing of a highlighted data segment is illustrated in the figure below:

[[Image:Spectral (3).gif ]]

The highlighted block constitutes 80% of a window of width 100%. A cosine squared (cos²) window of width 20% of the total is applied at the edges, so that the signal amplitude is attenuated to 50% at the edges of the marked block, and zero at the edges of the window. Then we take the number of time samples in the window and select the next higher power of 2 (up to 2^15 = 32768). Using spline interpolation, the data in the window are converted to this larger number of points, and the FFT is applied. If the number of points is greater than 32768, spline interpolation is used to reduce the number to 32768. In this case, to avoid aliasing, the data are low-pass filtered at a frequency corresponding to ¼ of the new sampling rate.

If the FFT is applied to the data displayed on the screen, windowing is similar to that for the highlighted block, except that no data outside the block are included: the cosine squared window is applied so that the signal amplitude is attenuated to zero at the edges of the display.

=== Mean FFT Spectrum over an extended time range ===

To start a mean FFT over an extended time range, e.g. between markers or over the whole data file, select the item ''Mean FFT-Spectrum'' in the '''Process''' menu ('''Alt+P M''').

[[Image:MeanFFT_Dialog.png]]

In the upper section of the ''Mean FFT'' dialog box the range on which the FFT is performed can be set:

# on the whole EEG
# on all marked epochs within the EEG
# on all marked epochs with a specific label
# on a time range delimited by two markers
# on all epochs delimited by two markers
# over triggers generated by the ERP module; mean FFT over triggers is only available if the mean FFT is called from the ERP module

Ranges that are not currently available (e.g. if no epochs or no markers are defined) are greyed out.

The mean FFT consists of a set of FFTs from overlapping data segments spanning the selected time range. Each data segment has a fixed width, defined as a power of 2 sampling points, that can be selected under '''Block Size / Points per Block''': In the center of the options window, the number of points per FFT block is selected. Selection can be 128, 256, 512, or 1024 points. The block width influences in particular the contribution to the spectrum of low frequencies: the wider the block, the lower the frequencies that can be represented. The lowest frequency is given by 1/(block width in seconds). Thus, if you have recorded data with a high sampling rate, a wider window is necessary to compute low frequencies. Note: For each block size in samples, the corresponding width in seconds is specified in brackets.

The lower section of the options window determines amplitude and gradient thresholds for including a block in the mean FFT. If signal amplitudes exceed the amplitude threshold or the difference of two consecutive signal amplitudes exceeds the gradient threshold, the block will be omitted. Different thresholds may be set for each channel type (in the above example, scalp and polygraphic channels).

Press '''OK''' in the options window to start the computation of the mean FFT. Computation can be interrupted by pressing any key. The interrupt has to be confirmed and may be cancelled to resume the mean FFT calculation.
The section “FFT Covariance” allows to compute the FFT covariance over the data range selected.
If the check box “Covariance Spectrum” is checked, a text file (BESA vectorized ASCII format) will be written after the computation. The file can be loaded into BESA Research again or can be analysed externally.
The file has the naming convention: [basename]FFTCovSvdBack_[MtgName].avr
Internally, the mean FFT is performed over the current montage. The covariance matrix is computed in frequency space.
The steps are:
For each epoch to be added to the mean covariance matrix:
# Average reference for EEG, MAG, and GRA data (if the single montage channels box is not checked)
# Resample data to 256 Hz
# Compute FFT
# Add to FFT covariance matrix (either sum over all channels, or individually for each montage channel if that box is checked)
Then, a singular value decomposition is performed on the FFT covariance of each channel, to obtain the (complex) eigenvectors. The newly arranged matrix of eigenvectors is then inverse Fourier transformed to obtain waveforms for each of the components. These are written to file.

Note on computational steps: Each data segment overlaps 50% with the next segment and is multiplied by a cosine squared (cos² window, as shown at the bottom of the figure below). This combination of overlap and windowing ensures that each time point contributes equally to the mean spectrum (since cos²(x) + sin²(x) = 1). Because mean spectra are computed, phase information is not available.

[[Image:Spectral (5).gif ]]

'''Note''' that time ranges marked as artifacts are not included in the computation of the mean FFT. These time ranges are not excluded when computing the FFT of a marked block or of the displayed data.

The section “FFT Covariance” allows to compute the FFT covariance over the data range selected.

If the check box “Covariance Spectrum” is checked, a text file (BESA vectorized ASCII format) will be written after the computation. The file can be loaded into BESA Research again or can be analysed externally.

The file has the naming convention: [basename]FFTCovSvdBack_[MtgName].avr

Internally, the mean FFT is performed over the current montage. The covariance matrix is computed in frequency space.

The steps are:
For each epoch to be added to the mean covariance matrix:
1) Average reference for EEG, MAG, and GRA data (if the single montage channels box is
not checked)
2) Resample date to 256 Hz
3) Compute FFT
4) Add to FFT covariance matrix (either sum over all channels, or individually for
each montage channel if that box is checked)

Then, a singular value decomposition is performed on the FFT covariance of each channel, to obtain the (complex) eigenvectors. The newly arranged matrix of eigenvectors is then inverse Fourier transformed to obtain waveforms for each of the components. These are written to file.

=== Redisplaying the previous FFT ===

The results of the previously calculated FFT spectrum can be redisplayed by selecting the item ''Previous FFT-Spectrum'' in the '''Process '''menu or by typing the hotkey '''Ctrl+F'''. It is not possible to recall the previous FFT if there was a change in

* the montage for which the FFT was calculated
* additional or artifact channels
* bad or interpolated channels
* the channel configuration

after the last FFT was calculated.

=== Mapping the Results of the FFT ===

Amplitude, power, mean band amplitude or power, and phase delays can be mapped. How to map FFT results is described in the chapter ''"Mapping / FFT Mapping''".

=== FFT 'View' Menu: Adjusting the FFT Display ===

[[Image:Spectral (6).gif ]]

The FFT spectrum of each channel in the '''current montage''' is displayed in a window on the left of the screen. At the bottom is the frequency scale. To the right, the dominant frequency is shown for each channel, together with the amplitude or power at this frequency. The dominant frequency is determined between the lower boundary of the first frequency band and the maximum displayed frequency.

[[Image:Spectral (7).gif ]]

''FFT result window with a display of amplitude spectrum with the sum of amplitudes in bands, color coding, and frequency range 1-30 Hz. The montage is TR_Temporal Region.''

Using the '''View''' Menu, the following options can be selected:

* Results can be displayed as '''Amplitude''' ('''Alt+V A''') or '''Power''' ('''Alt+V P)''' spectra. At the top of the display (cf. example below) is the text ''"Amp. Spectrum"'' or'' "Power Spectrum". ''Click on the text to toggle between the two types of display.
* The graphical display of amplitude or power spectra can be '''Normalized''' ('''Alt+V N'''), such that all displayed values are scaled relative to the dominant frequency separately for each channel (i.e. amplitudes cannot be compared between channels). Without this option set, values in each channel group (scalp, source, MEG, Pgr, ICR) are scaled to the channel in this group that has the largest amplitude in its dominant frequency (i.e. amplitude relationships among channels within one channel group are upheld).
* Amplitude or power values can be displayed on a '''Logarithmic scale''' ('''Alt+V L'''). Amplitude values are displayed over two log units, power values over four log units. Thus, for amplitudes, values less than 1/100 (two log units) of the maximum are set to zero. For power, values less than 1/10000 (4 log units) of the maximum are set to zero.
* The sum of '''amplitudes''' or '''powers''' in each frequency band can be displayed ('''Alt+V M''', or '''Alt+V''' '''O''').
* Spectra are shown as a curve of amplitude/power vs. frequency. If '''Color coding''' is selected ('''Alt+V C'''), then the areas underneath the curve are colored differently for each frequency band. Colors can be changed in the FFT Options menu ('''FFT/FFT Options Menu''').
* The frequency scale can be set to one of the three predefined display frequencies '''1-30 Hz, 1-50''' '''Hz''', ('''Alt+V 3''', or '''Alt+V 5''') '''or 1-half of the sampling frequency''', e.g. 1-100 Hz in the above screenshot of the '''View''' menu. Alternatively, any user-defined '''Frequency Band '''('''Alt+V B''') can be displayed. The upper and lower boundary of the frequency band is set to the next whole-numbered multiple of the frequency resolution. The DC component is always set to zero.
* '''Info-box'''. Click with the right mouse button on a particular frequency in the spectrum of one of the channels to obtain a box with the following information: Channel name, frequency, and amplitude/power at that frequency.

'''Note:''' The number of channels shown in the FFT display is the same as the number shown in the EEG display. If you change the EEG display (e.g. by changing the number of scalp electrodes or switching off polygraphic channels), the FFT display is updated automatically. The update can be performed without recalculation. If additional channels or artifact channels reconstructed by BESA Research artifact correction are switched on/off, or the status of bad or interpolated channels changes, the FFT is recalculated. Recalculation is only possible if the FFT was calculated over a block or the whole screen. The mean FFT window has to be closed in this case. Recalculation is also not possible if the FFT was loaded from a file. If you change the montage in the EEG display, the FFT window will always be removed: different montages require recalculation of the FFT.

'''Note''': Bad channels in the original montage are displayed in an attenuated color. The spectrum of bad channels is zero for each frequency. As the dominant frequency, its amplitude and the sum of amplitudes or powers in each frequency band cannot be determined, a horizontal bar is shown for each missing value.

'''Notes about display resolution: frequencies and pixels'''

When plotting the results of the FFT on the screen, there is a subtle interaction with the screen resolution which can affect the frequency and amplitude/power values displayed when generating maps or looking in the Info-box. Note that two types of situations can arise, depending on whether the number of frequency steps (= half the no. of sampling points in the data window) is greater or less than the number of screen pixels.

If the number of frequency steps is less than or equal to the number of screen pixels, the amplitude at each frequency can be displayed correctly.

If the number of frequency steps is greater than the number of screen pixels, then there are not enough pixels to display each amplitude. In this case, the amplitude displayed at each pixel is the maximum amplitude in the range of frequencies covered by that pixel. For a given pixel, this '''maximum''' amplitude can differ among channels. Thus, depending on the channel to which the mouse is pointing, the frequency displayed in maps (left click) or in the Info-box (right-click) can vary, even if the horizontal position of the mouse is the same.

=== FFT 'File' Menu: Saving, Loading and Printing Results of the FFT ===

 
[[Image:Spectral (8).gif ]]

'''Loading and Saving FFT'''

Select '''Load...''' ('''Alt+F L''') to load an FFT file that has been saved to a binary file using '''Save...''' ('''Alt+F S'''). An FFT spectrum should be redisplayed with the file from which it was calculated. An FFT file cannot be loaded if electrode configuration and bad channels of the current file do not match with the electrode configuration and bad channels of the saved FFT spectrum. The montage of the current EEG is changed to the montage of the loaded FFT. Filter settings that were active at the time when the FFT was calculated are not reset but are indicated correctly in the FFT printout.

The heading of the printout shows the name of the loaded FFT file and the name of the EEG for which the FFT was calculated. If the loaded file contains a mean FFT spectrum, the mean FFT options are adjusted to the settings used to calculate the loaded mean FFT spectrum.

'''Averaging FFT spectra'''

Select '''Load and Average...''' ('''Alt+F V''') to compute averages of previously saved FFT spectra. In the appearing window, select an FFT spectrum ('''*.fft''') from the list on the left and press the arrow button (-->) to copy it to the list of FFTs to be averaged on the right. Press '''OK''' to calculate and display the averaged FFT spectrum.

[[Image:Spectral (2).png ]]

'''Note:''' Averaging of FFT spectra is only possible if the spectra were computed using the same epoch length (marked block or whole screen), montage, and sampling rate.

'''Exporting FFT spectral data'''

Select '''Export FFT Data''' in the '''File''' menu ('''Alt+F F'''). You can select two different output montages:

* Output '''81 Interpolated''' average referenced data (to a standard configuration of 81 electrodes, only available for EEG data) ('''Alt+F FI'''), or
* Output '''Current Montage''' data ('''Alt+F FM''')

Select one of two output formats:

* Write the data in''' Vectorized '''format:
** Line 1 of the output file contains the number of frequency steps (Npts), a starting value for BESA Research’s time scale (TSB), the frequency step (DI), scaling in bins per microvolt (SB), a scaling value for the BESA Research display (SC), and the number of channels (Nchan) as shown in the following example:
*** <tt>Npts= 1023 TSB= 0.10 DI= 0.100 SB= 1.000 SC= 100.0 Nchan= 23</tt>
** Line 2 lists the channel labels.
** Each successive line contains the amplitude/power values at each frequency for one channel.

* Write the data in '''Multiplexed''' format:
** Line 1 contains the frequency step size in Hz.
** Line 2 lists the channel labels.
** Each subsequent line contains amplitude/power values for all channels (in the sequence given in line 2) for one frequency.

Both vectorized and multiplexed files may be reread into BESA Research in the same way as time-domain averages. Vectorized files may be read directly using the '''File / Open''' menu. Multiplexed files may be read using the ASCII import menu item '''File / Import ASCII file'''.

For each of these output formats and montages, different data can be saved:

* '''Amplitude Spectrum''' ('''Alt+F FA'''),
* '''Power Spectrum''' '''(Alt+F FP'''), or
* '''Real + Imaginary Part''' ('''Alt+F FR'''). In this case, amplitudes of the real and imaginary components are written to two separate files.

File name extensions for each type of output file are given in the following table:


{| class="wikitable"
!
! current montage
! average reference
! mean in bands
|-
| amplitude spectrum
| style="text-align: center;" | *.fma
| style="text-align: center;" | *.faa
| style="text-align: center;" | *.fba
|-
| power spectrum
| style="text-align: center;" | *.fmp
| style="text-align: center;" | *.fap
| style="text-align: center;" | *.fbp
|-
| real components
| style="text-align: center;" | *.fmr
| style="text-align: center;" | *.far
| style="text-align: center;" | N/A
|-
| imaginary components
| style="text-align: center;" | *.fmi
| style="text-align: center;" | *.fai
| style="text-align: center;" | N/A
|}

'''Exporting band amplitudes and power'''

Select '''Export Power in Bands''' ('''Alt+F P''') or '''Export Amplitude in Bands''' ('''Alt+F A'''). An ASCII file is produced with one channel per line, and each line contains the value for each frequency band.

'''Sending FFT data to MATLAB'''

Select''' Send to MATLAB '''('''Alt+F M''') to transfer the current FFT data to MATLAB. This menu entry is available only when MATLAB is installed. Details on the MATLAB interface are provided in the chapter [[MATLAB_Interface | MATLAB Interface]].

[[Image:Spectral (12).gif]]

A dialog window opens that allows to specify:

* the type of data to be transferred (Amplitude, Power, or Complex FFT data)
* whether each frequency bin should be transferred or frequencies should be pooled in bands
* the montage for which the FFT should be sent

When hitting '''OK''', the sent data will be made available in MATLAB in struct variable '''besa_fft'''. For details on the data transfer from BESA Research to MATLAB, please refer to the chapter [[MATLAB_Interface | MATLAB Interface]].

'''Printing results of the FFT'''

Select '''File / Print''' to print the FFT display and FFT maps. BESA Research uses the standard WINDOWS printer output. You may change your printer settings temporarily for your current BESA Research session. In the printer setup, you can choose the orientation (landscape or portrait) and the resolution. If you have any problems with printing, try to set the resolution to 300*300. If you want to change the printer setup permanently, please select the Printer Control from the WINDOWS main control group.

A preview of the printout can be generated with '''File / Print Preview'''. Click on the ''''OK'''' button to return to the program.

'''Closing FFT'''

To remove the FFT window (without saving the results), select ''Close'' in the''' File''' menu ('''Alt+F C'''), or simply type the '''Esc''' key.

=== FFT ‘Options’ Menu ===

The '''Options''' menu allows to define FFT mapping options, to set colors for the display of each frequency band, and to define and name up to 7 bands. When working with BESA Research, the band colors, names, and frequency ranges of the last session are stored in the file '''BESA.set'''. These values are then used in the next BESA Research session.

[[Image:Spectral (13).gif]]

'''Mapping options'''

In the Mapping submenu two entries toggle different mapping modes:

[[Image:Spectral (14).gif]]

* The entry '''3D Whole Head Mapping''' toggles between 3D and 2D mapping.
* The entry '''Top Meridian Projection''' toggles between top meridian projection and whole head mapping.

'''Defining band colors'''

[[Image:Spectral (15).gif]]

Select '''Options / Band Color''' ('''Alt+O C'''), and then the name of the band to define (e.g. '''Theta''': '''Alt+O CT'''). A window is presented with a palette of colors, allowing the choice of a color for the display.

Select''' Default Colors''' ('''Alt+O CD''') to select the default colors for the bands (predefined in '''BESA.ini''').

'''Defining band names and widths'''

Select '''Options / Band Name and Width''' to define up to 7 band names and frequency ranges. A window showing names and frequency limits is displayed, allowing redefinition of the frequency bands. Overlapping frequency ranges can be defined. Upper/lower limits of FFT bands can be set up to the maximum frequency that can be displayed in the current FFT (which is usually half of the sampling rate). Press the '''Default''' button to select the default definitions as predefined in the file BESA.ini and shown in the following table:

[[Image:Spectral (16).gif]]

=== FFT Mouse Controls ===

'''Single left click'''

* on the '''displayed peak frequency''' or peak amplitude values of a channel or on the channel labels or head symbols at the left of the FFT window: Sets a cursor at the peak (dominant) frequency of the selected channel and displays a map of the topography at the marked frequency (only if the channel is not defined as bad).
* on the string indicating the '''spectrum type '''(Amp. Spectrum or Power Spectrum): Toggles between the display of amplitude and power spectrum.
* on the string indicating the map type (EEG or MEG): Toggles between EEG and MEG FFT maps (only for combined MEG and EEG measurements). 
* on the '''displayed spectrum''': Sets a cursor and draws a FFT map of the topography at the marked frequency. The availability of this function by single left mouse click depends on the settings in the main window’s '''Options / Mapping''' submenu ('''Options / Mapping / Enable Direct Mapping by Single Click''').

'''Note:''' The mouse pointer changes to a hand in areas of the FFT window where left mouse clicks initiate an action.

'''Double left click'''

* on the '''displayed spectrum''': Sets a cursor and draws a map of the topography at the marked frequency. The availability of this function by single left mouse click depends on the settings in the main window’s '''Options / Mapping''' submenu ('''Options / Mapping / Enable Direct Mapping by Double Click''').

'''Right click'''

* on the '''displayed spectrum''': Opens an info-box indicating channel name, frequency, and amplitude/power at that frequency.

== Density Spectral Arrays (DSA) ==

=== Introduction ===

The Density Spectral Arrays (DSA) module displays a compressed two-dimensional time-frequency display of the activity in the data file. It focuses on the frequency range of 1 Hz - 25 Hz which includes the commonly observed oscillatory rhythms in the human brain. This allows for a quick overview of the sections where events of interest occur, e.g. in the analysis of epileptic seizures or in sleep research. DSA values are computed for every second in the data file using a windowed FFT with a window length of 2s. By default, the DSA module uses a standardized brain source montage to separate the activities of both hemispheres and the different brain regions using 15 regional sources. This spatial filtering prior to the application of the time-frequency transformation helps to identify brain regions where oscillatory activity originates. The DSA can be invoked by hitting the [[Image:Spectral (17).gif]] button or from the '''Process''' menu.

[[Image:Spectral (18).gif]]

[[Image:Spectral (19).gif]]

''Standard DSA display of an EEG containing four seizures. For each brain hemisphere, the sum of activities is shown.''

'''Using DSA to navigate'''

With a '''left mouse click''' into the DSA display, you can navigate to the selected EEG event. The data review window display jumps to the selected time in the record.

'''DSA display modes'''

Three modes of DSA display are possible:

# Hemispheric Comparison, which sums up all the lateral activities of each hemisphere
# Regional Comparison, which gives account of the activity within five gross brain regions
# Current Montage, which shows the activity in each channel of the selected montage at the time the DSA window was opened. For MEG data, only the Current Montage option is available.

For the first two modes, the signals are first transformed to the standardized brain source montage ''[[BESA_Research_Montage_Editor#Standard_Source_Montage_-_BR_Brain_Regions|BR_Brain Regions]]'' (see chapter '''[[Review#Remontaging|Review / Remontaging]]''') before the summation of the spectral parameters is performed. This transformation of the data to a source montage optimally separates the activities from the different brain regions that generate overlapping signals at the scalp surface. DSA of scalp channels can be seen by selecting a recording (traditional) montage and selecting mode 3, current montage.

The way in which signals are sub-sampled to obtain the density display can be modified, from the fastest sub-sampling to an averaged or maximum signal display. The color-coded display of the spectral values in frequency bins can be normalized to the percentage value relative to the sum over all frequency bins of each channel.

The current position in the data file is indicated by the vertical dashed lines in the display.

[[Image:Spectral (20).gif]]

The time scale shows minutes as small grey ticks (in real-time - not time measured from file start). In the "''Hemispheric Comparison''" mode, the time scale appears in the middle, whereas it is displayed below the channels otherwise. Thicker gray ticks indicate five-minute marks, larger black ticks ten-minute-marks, and segment borders are displayed in red.

=== Setting the DSA Display Mode ===

The data can be remontaged for display in three different ways using the first three toolbar buttons.

[[Image:Spectral (21).gif]] '''Hemispheric Comparison (default option)'''

Hemispheric comparison is activated by clicking on the '''leftmost''' toolbar button. The integrated activity of each hemisphere is shown. In this mode, the DSA window aligns with the event bar at the bottom of the main window to relate activity to the events marked in the event bar. The integrated activity of each hemisphere is calculated by first transforming the data to the standardized source montage ''BR_Brain'' ''Regions'', which is also available from the "'''Src'''" button in the BESA Research main window (see chapter ''"Review / Remontaging").'' Then the signals of all source channels in the left ('''L''') and the right ('''R''') hemispheres are summed up separately. This transformation of the data to a source montage optimally separates the activities from the different brain regions that are overlapped and smeared at the scalp surface.

For MEG data, this option is not available.

[[Image:Spectral (22).gif]]''' Regional Comparison  '''

This option is activated by clicking on the''' second''' toolbar button. The integrated activity of five brain regions is shown. The regions are:

* '''FcpL, FcpR''', which sum all lateralized activity in the upper parts of the brain
* '''TmpL, TmpR''', which sum all activity in the temporal regions of the brain
* '''SagM''', which sum all activity in the sagittal midline regions of the brain (only shown if tick mark ''"Midline Channels"'' is on in '''Montage Options''').

In this mode, the DSA window is displayed in the right portion of the BESA Research main window. The integrated activity of each region is calculated by first transforming the data to the standardized source montage ''BR_Brain Regions'', which is also available from the '''"Src" '''button in the BESA Research main window (see chapter ''"Review / Remontaging''").

Then the signals of the source channels which belong to the corresponding region are summed up.

For MEG data, this option is not available.

[[Image:Spectral (23).gif]] '''Current Montage'''

With the '''third''' toolbar button, the Current Montage option is selected to display the spectra of the channels of the montage that was selected when the DSA window was opened. In this mode, the DSA window is displayed in the right portion of the BESA Research main window. If the current montage is changed in the BESA Research main window, the DSA display remains unchanged -''' Ändern'''.

[[Image:Spectral (24).gif]] '''Source Montage'''

The four following buttons, which appear only in the hemispheric comparison window, allow for the selection of the montage underlying the display, based on the source montage ''BR_Brain Regions''. One of the buttons is always down, with '''BR''' as default.

In the case of '''BR''' (''Brain Regions''), the averages of all left-hand and right-hand side channels of the montage ''BR_Brain Regions'' are shown in the upper and lower channel, respectively, as indicated by the labels''' L''' and '''R'''.

For '''TL''' (''Temporal Lobe''), the averages of the most important channels of the source montage ''TR_Temporal Regions'' are calculated and displayed in the upper and lower channels labelled '''L''' and '''R'''. The channels in question are TAL and TPL for the left-hand side and TAR and TPR for the right-hand side.

'''FP''' (''Frontoparietal'') is based on the source montage ''BR_Brain Regions'' and averages the source channels FL, CL, PL and FR, CR, PR, respectively, displaying them in channels '''L''' and '''R.'''

'''SG''' (''Sagittal'') also uses the source montage ''BR_Brain Regions''. The mean of the frontal sagittal channels FpM, FM and CM is displayed in the upper channel F, the mean of the posterior sagittal channels CM, OpM and CM is shown in the lower channel '''P'''.

[[Image:Spectral (25).gif]] '''Visualizing Differences'''

Many features of interest are lateralized in the brain and show up clearly when hemispheric regions are compared directly. This is achieved using the '''Delta''' toolbar button:

This button enables subtraction of hemispherically homologue regions and is available for the standardized montage options "''Hemispheric Comparison"'' and "''Regional Comparison".''

'''Hemispheric Difference'''

<div style="margin-left:1.27cm;margin-right:0cm;">The integrated activities of the hemispheres (calculated as in the ''Hemispheric Comparison'' option) are subtracted from one another. The differences between the activities are displayed. The channel '''L+''' shows signal at the frequencies and latencies where activity was higher in the left hemisphere. Frequencies and latencies where activity was higher in the right hemisphere show up in channel '''R+.'''</div>

'''Regional Difference'''

<div style="margin-left:1.27cm;margin-right:0cm;">The integrated activity of four brain regions is calculated as in the ''Regional Comparison'' option excluding the midline sagittal region. Then the activities of homologous regions are subtracted from one another and this difference is displayed on the side where the activity is larger: Thus, the channel '''FcpL+''' only shows signal at frequencies and latencies where activity was higher in ''FcpL'' than in ''FcpR''. The signals in the other channels are calculated accordingly.</div>

[[Image:Spectral (26).gif]] '''Epochs'''

The epoch buttons allow the choice of time interval for browsing through the data.''' '''Either the whole file ("''All")'' or intervals of 15, 20 or 30 minutes, with one additional''' '''minute of overlap with the following window, are shown. The default is 20 minutes,''' '''which corresponds best to the length of the standard EEG. For continuous data files,''' '''interval start times are chosen in relation to the full hour (e.g. 18:00, 18:20 and''' '''18:40 for the 20-minute window). Only the first and last windows are positioned such''' '''as to start and end with file start and end, respectively.

The default epoch is "All" for files shorter than 20 minutes and "20" for longer files. For files no longer than 15 minutes, all buttons are greyed (with "All" automatically selected). Otherwise, "All" and those buttons which allow paging are enabled.

In the case of "All" and files of long duration, a progress bar may appear. Hitting "'''Abort'''" will result in the display of those portions of the data that have already been calculated.

The epoch buttons are grayed in the zoom mode.

[[Image:Spectral (27).gif]] '''Paging'''

Page backward / forward one interval of the currently selected length. The page buttons are enabled only if the position in the file, and the file length, allow to browse to an earlier / later interval.

The page buttons are grayed in the zoom mode.

=== Display Options ===

To emphasize features of interest, the DSA display can be optimized to normalize and scale the spectral data in different ways.

[[Image:Spectral (28).gif]] '''Percentage Button'''

The status of the '''percentage''' button on the toolbar determines how the color-coded display of the intensity values in frequency bins is normalized. The options are:

* '''Absolute Value''' (button is up):

If this option is selected, the absolute amplitude or power intensity values are displayed.

* '''Percentage''' (default option, button is down)

If this option is selected, the intensity value for each sampling time and frequency is normalized to the summed intensities over all frequency bins averaged over all channels for that sampling time. Thus, the displayed DSA amplitude/power for one frequency bin is its contribution (in %) to the overall activity at that sampling time.

The effect when applying the percentage normalization to data is shown in the example below, where the hemispheric difference with and without percentage normalization is shown:

[[Image:Spectral (29).gif]]

[[Image:Spectral (30).gif]]

''Hemispheric difference display without percentage normalization (top) and with percentage normalization (bottom). The decreasing 9 to 7-Hz seizure activity in the right hemisphere emerges better from the background with percentage normalization.''

[[Image:Spectral (31).gif]] '''Amplitude Button'''

The amplitude button toggles between the display of amplitude and power. The default setting is on amplitude (button is pressed).

If amplitude is selected, displayed intensities are in µV/Hz, fT/Hz, fT/(cmHz), or nAm/Hz.

If power is selected, displayed intensities are in µV²/Hz, fT²/Hz, fT²/(cm²Hz), or nAm²/Hz.

[[Image:Spectral (32).gif]] '''Original Data and Baseline Normalization'''

By default, the original data are shown (button D down). If option B (baseline normalization) is chosen, amplitude/power for each sampling time and frequency and each remontaged channel is normalized by the sum over all sampling times for the given frequency.

This can sometimes help to suppress or intermittent or continuous signals of constant frequency.

[[Image:Spectral (33).gif]]

[[Image:Spectral (34).gif]]

''Hemispheric comparison display without (top) and with (bottom) additional baseline normalization, which enhances the contrast between seizures and background for this example.''

[[Image:Spectral (35).gif]] '''Setting the Display Sampling'''

Since the data file features far more sampling times than pixels available for DSA display, a sub-sampling is required to compress data file sections into the pixels shown in the DSA. The method how this is achieved can be chosen with the sampling popup menu. Using the sampling button in the toolbar, the type of sampling of data for the display can be chosen.

Three options are possible:

* '''Sub-sample Epochs:'''

For each displayed pixel, one sample second in the middle of the represented time interval is selected. For this sample second, the activities are displayed. This is the fastest way to obtain the DSA display. The principle is illustrated in the graphics. In this example, only every fourth sample is computed for the DSA display.

[[Image:Spectral (36).gif]]

* '''Average Epochs''' (default option):

For each displayed pixel, the average over all seconds which are summarized in that pixel is calculated for each frequency bin. In this way, it is ensured that sudden bursts of activity are not accidentally missed out. The principle is illustrated in the graphics.

[[Image:Spectral (37).gif]]

* '''Select Maximum:'''

For each displayed pixel, the maximum over all seconds which are summarized in that pixel is calculated for each frequency bin. This enhances the impact of sudden bursts of activity in the display. The principle is illustrated in the graphics.

[[Image:Spectral (38).gif]]

[[Image:Spectral (39).gif]] '''Scaling Buttons'''

The left button (+) scales intensities up, the right one (-) scales them down. Each time one of the buttons is pressed, scaling is increased/decreased by a factor of ³√2. This means that pressing the same button 3 times results in doubling / halving the normalization intensity.

'''Zooming the Display'''

You can use the left mouse button to drag a rectangle anywhere in the display. A popup menu containing the entries "Zoom In" and "Zoom Out" appears, from which you can choose to zoom into the selected area. In the zoom mode, the epoch and page buttons are up and grayed.

[[Image:Spectral (40).gif]] Zooming out can be done using the Zoom Out button, which is shown only if the display is zoomed. The display then returns to the former view. Otherwise, dragging another rectangle reopens the popup menu.

'''Note:''' for further details on Spectral Analysis (FFT and DSA) in BESA Research, please refer to the Help Chapter ‘''Spectral Analysis’''.

=== Tutorial ===

This tutorial will introduce the main features of the DSA module. A detailed description of all features can be found in the reference section.

The tutorial uses a data file with four concatenated EEG segments of epileptic seizure data (by courtesy of Prof. J. Ebersole, U Chicago). We will learn how to identify events in the data file quickly using the DSA display and how to find epochs with prominent rhythmic activities that differ between hemispheres.

1. Use the '''File / Open''' menu to browse to the folder '''Examples\Epilepsy\Seizures'''. Select the data file ''''Seizure-Right-Temporal.foc'''' and open it. The data are shown in the originally recorded montage. By default, a time constant of 0.3 sec (i.e. Low Filter: 0.53 Hz) is enabled (unless you changed the settings in your '''.ini''' file).

2. In the main window, press pushbutton ''''Src'''' and select the source montage '''TR_Temporal Region'''. This displays the left and right temporal lobe channels in the top 8 traces and reveals strongly lateralized right temporo-basal seizure activity. Press the '''high filter''' pushbutton '''HF''' and select '''35 Hz''' to reduce the EMG artifact.

3. Press the push button "'''DSA"''' at the top of the main window. The DSA window opens. In the DSA display, the horizontal axis represents time, whereas the vertical axis represents frequency (from 1 to 25 Hz). 

With the '''Amplitude button''' [[Image:Spectral (31).gif]]] down, and the '''Percentage button''' [[Image:Spectral (28).gif]]] released, the following image is obtained:

[[Image:Spectral (41).gif]]]

Four seizures can be distinguished in the display (red blocks of large EEG activity). Only two source channels, L and R, are shown, one for each hemisphere. These channels are obtained by calculating the mean left and right source activities using the 5 left and 5 right regional sources of brain source montage BR_BrainRegions to reduce overlap by volume conduction.

4. '''Scale the DSA display''' up using the '''Scaling button''' in the toolbar ([[Image:Spectral (42).gif]]). Pressing it three times decreases the threshold for maximum intensity by a factor of 2. The color map caption text changes correspondingly. '''Scale''' the display down again, either using the next toolbar button, or the ''''Cursor-Down'''' key on the keyboard to set the amplitude scale to 79.4 nAm. This will reveal the dark 'nose-tips' at the beginning of the second and fourth seizure with frequencies decreasing from about 8 to 5 Hz and obvious lateralization to the right hemisphere.

5. '''Move the mouse cursor''' over the data display. Current time and frequency are shown below the color bar and next to the mouse cursor, respectively. '''Click''' on the red-nose tip (~6.5 Hz) around +00:02:09 (12:02:09 AM) in the right source channel (R) to move the EEG display to this epoch at the beginning of the second seizure. A comparison of the traces of the left (traces 1-4) and right (traces 5-8) temporal lobe sources (''Src/TR_Temporal Region'') confirms the lateralization of the seizure onset to the right hemisphere.

[[Image:Spectral (43).gif]]

6. '''Press''' the '''second-left''' toolbar button ([[Image:Spectral (44).gif]]) to switch to the display mode ''''Regional Comparison''''. The DSA display moves to the right of the main window and displays the spectral densities of five regions by summarizing the activities in the lateralized upper parts of the brain, in the temporal regions bilaterally, and in the midline regions.

[[Image:Spectral (45).gif]]

7. '''Press''' the '''third''' toolbar button ([[Image:Spectral (46).gif]]) to switch to the display mode ''''Current Montage'. '''The DSA display on the right of the main window now displays the spectral densities of all channels in the current montage. Enlarge the DSA window by using the full-screen symbol at the top right. It is very apparent now that the seizures start with an interval of increased activity in the 8-5 Hz range. This activity is most noticeable in the anterior three source channels of the right temporal lobe (TBvr_TR, TApr_TR, and TArR_TR).    

[[Image:Spectral (47).gif]]

8. Use the overlapping window icon at the top right of the window to get the window back to its original position at the right of the screen. Then press the '''Sampling '''toolbar button ( [[Image:Spectral (48).gif]] ) to select the menu entry ''''Select Maximum'''' from the dropdown menu which appears. This results in pronouncing maxima of intensities: for each frequency bin, the maximum over the epoch that is related to one pixel of the display is computed. In this case, the noise is enhanced by the procedure. Press the button again to go back to 'Average Epochs', which displays the average over the epoch related to one displayed pixel for each frequency bin.

9. '''Close the DSA window''' using the close symbol at the top right. Press pushbutton ''''Vir'''' to select the virtual '''Horizontal Bipolar''' montage. Press the pushbutton '''DSA''' to recalculate DSA for the new current montage, then press the Amplitude button ( [[Image:Spectral (31).gif]] ) and the third toolbar button ([[Image:Spectral (23).gif]]). You can now see that the scalp montage, although optimized for temporal-basal activity shows a poor separation between hemispheres.

[[Image:Spectral (49).gif]]

10. '''Press''' the '''second-left''' toolbar button ( [[Image:Spectral (44).gif]] ) to select the menu entry ''''Regional Comparison''''. '''Press''' the ''''Delta'''' button ( [[Image:Spectral (25).gif]] ) to switch to regional difference. The channels now show the difference between activities in the homologous brain regions. Then '''press''' the '''Display '''button ([[Image:Spectral (50).gif]]) to switch to the display mode''' 'Percentage''''. Now, the relative spectral amplitude in each frequency bin and time point is displayed.''' Switch''' to displaying '''spectral power''' by releasing the '''Power''' button ( [[Image:Spectral (31).gif]] ). Adjust the scaling to 16% at maximum intensity using the '''scaling''' toolbar buttons or the '''cursor up-down''' keys.

[[Image:Spectral (51).gif]]

This display mode takes away most of the unwanted activity which is not lateralized, and clearly shows the dark clusters in the right hemisphere in the 7 Hz range immediately before the second and fourth seizure.

11. Use the '''left mouse button''' to drag a rectangle around the beginning of the fourth seizure in channel "TmpR+". From the popup menu that appears, select "Zoom In". The display is zoomed to show just the selected area. The seizure onset of the 4th seizure is visible as a decelerating 7Hz oscillation in the right temporal region. Use the right mouse button to zoom out again.

[[Image:Spectral (52).gif]]

This concludes the tutorial on density spectral arrays. It gave a brief introduction into the ways in which the DSA can be used in combination with traditional and brain source montages, and demonstrated its abilities to quickly identify epochs and regions of interest in EEG data files.

[[Category:Research Manual]]

{{BESAManualNav}}

BESA Research Montage Editor

2021-06-01T10:12:33Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = 6.1 or higher
}}

== Montage Editor - Introduction ==

The Montage Editor provides information about the current montage and the available standard montages.

The Montage Editor also offers the possibility to create new user-defined montages, modify a standard montage, or combine channels from different montages.

Edited Montages can be saved and selected in the main window of the BESA Research program using the montage push buttons or the montage menu.

The Montage Editor opens after clicking on the''' EdM''' push button in the BESA Research ''control ribbon.''

The following chapters will guide you through the most important features and the layout of the Montage Editor.

== Layout of the Montage Editor ==

The Montage Editor window is subdivided into three main parts which will be explained briefly in the following sections.

[[Image:Montage Editor (4).jpg|500px]] [[Image:Montage Editor (5).jpg|490px]]

The '''title bar''' shows the name of the ''current montage'' (the montage which is currently displayed).

Most of the functions and commands can be chosen from the main '''menu bar''' and the '''toolbar''' below the title bar. However, many commands are also available via a right mouse click. If you right-click, a context-sensitive popup menu may appear containing the available commands.

The functions of the toolbar and the popup menus are described in the next section. A detailed description of the commands of the menu bar is given in electronic help chapter ''"Montage Editor / Reference".''

=== 2D View ===

The 2D view displays a scheme of the ''current montage''. Additionally, available electrodes which are not used in the current montage can be shown.

The name of the current montage is given at the top. Note: If the montage name starts with '''"Add:"''', an ''additional channel montage'' is displayed. Additional channel montages are described in the chapter ''"Predefined Additional Channel Montages".''

[[Image:Montage Editor (1).png]]

[[Image:Montage Editor (2).png]] Use the '''One 2D Head toolbar button''' if you want to switch between the available 2D head views: the top meridian projection, or the top, bottom, back, front, left and right views.

[[Image:Montage Editor (1).jpg]]

The top meridian projection shows all electrodes of the current montage. Other 2D head views only show the electrodes which are visible from the corresponding side.

[[Image:Montage Editor (4).png]] Use the '''Four 2D Heads toolbar button''' to switch between the available four head layouts.

The following objects are displayed:

[[Image:Montage Editor (5).png]] '''Recorded electrodes''' which are available for the current data file, not interpolated and not marked as 'bad'.

[[Image:Montage Editor (6).png]] '''Interpolated electrodes''' which have been set as 'to be interpolated' in the main program.

[[Image:Montage Editor (7).png]] '''Bad electrodes''' or '''bad MEG sensors''' which have been marked as 'bad' in the main program.

[[Image:Montage Editor (8).png]] '''Virtual electrodes''' at predefined locations. The interpolated 81 electrodes are always available for EEG data files.

[[Image:Montage Editor (9).png]] '''MEG sensors''' which are available for the current data file.

[[Image:Montage Editor (11).png]][[Image:Montage Editor (12).png]][[Image:Montage Editor (10).png]] '''Montage channels''' with the underlying recorded/virtual electrode or MEG sensor as primary channel and no reference channel or a reference channel which is not visible for the current 2D head view or which is no single channel reference – may be a reference calculated by several channels, e.g.'' avr'' or ''ears''. If a montage channel is selected, the inner circle becomes darker.

[[Image:Montage Editor (14).png]][[Image:Montage Editor (13).png]]'''Montage channels''' with underlying recorded/virtual electrode as primary channel (left electrode) and the right electrode as reference, connected with the montage channel line. If a montage channel is selected, the blue/red circle and the montage channel line become darker.

Additional objects are visible if the 'Edit' montage is displayed. The chapter "Montage Editor / Editing a Montage / Editing in the 2D View and Icr/Pgr View" gives a description of these objects and explains how the 'Edit' montage can be modified.

A right mouse click on a montage channel in the 2D view opens a context-sensitive popup menu for fast access to the most important commands.

=== Montage Channel List ===

The montage channel list is displayed to the right of the '''2D View'''. It displays all montage channels of the ''current montage''.

[[Image:Montage Editor (15).png]]

A montage channel consists of a (primary) channel and may be a reference channel against which the primary channel data are calculated. In the example shown above (which really does not make much sense but shows most of the available channel types) the recorded electrode Pz and the virtual electrode Cz are used as references.

Distinctions are made between channel and reference types and states as follows:

*'''Recorded electrodes''': Recorded electrodes which are available for the current data file are displayed in blue. They may be used as primary and reference channels.

*'''Recorded references''': A combined reference based on the recorded electrodes, e.g. avr. They are also displayed in blue.

*'''Interpolated electrodes''': Interpolated electrodes are recorded electrodes that have been set as 'to be interpolated' in the main program. They are displayed in light purple. Interpolated electrodes may be used as primary and reference channels.

*'''Bad channels''': Recorded channels which have been marked as 'bad' for the current data file are displayed in gray. You may use them as primary or reference channels, but the corresponding data waveform will not be displayed in the main program. However, if you switch to a new data file and the channel is no longer marked as 'bad', the corresponding data waveform will be displayed.

*'''Unavailable channels''': Channels which are not available for the current data file are also displayed in gray and the suffix “[NA]” is appended. You may use them as primary or reference channels but the corresponding data waveform will not be displayed in the main program. However, if you switch to a new data file and the channel becomes available, the corresponding data waveform will be displayed.

*'''Virtual electrodes''': Virtual electrodes at predefined locations. They are always available for any (EEG) data file, displayed in red. They may be used as primary and as reference channels.

*'''Virtual references''': A combined reference based on virtual electrodes, e.g. ears. They are also displayed in red.

*'''Source montage channels''': Source montage channels consist of a single dipole or a regional source as primary channel and cannot have a reference. The source labels are displayed in green. The individual source color is given as a small colored bar to the left.

*'''MEG channels''': Recorded MEG channels which are available for the current data file and which are not marked as 'bad' are displayed in dark purple.

*'''Polygraphic channels''': Available polygraphic channels are written in '''black.'''

*'''Intracranial electrodes''': Available intracranial electrodes are given in brown.

*'''Selected montage channels''': Labels of selected montage channels are highlighted with a black background. A montage channel can be selected by a left mouse click on the channel label. Hold down the '''Control '''key to select more than one montage channel simultaneously.

*'''Highlighted montage channel''': The highlighted montage channel is marked by a yellow rectangle around its label. A montage channel is highlighted if the mouse cursor moves slowly over its label or over the corresponding plot in the '''2D view'''. Only one montage channel can be highlighted at a time.

A right mouse click somewhere in the montage channel list opens a context-sensitive '''popup menu''' for fast access to the most important commands.

The chapter "''Editing a Montage in the Montage Channel List"'' gives an explanation of how to modify the''' 'Edit' montage '''in the montage channel list.

=== 3D View ===

The 3D view is used to visualize the equivalent locations of source channels inside the head in the ''current montage'' and to display the recorded EEG channel montage on the 3D head surface.

* If a source montage channel is selected, the 3D view is centred w.r.t. to the source location and the 3D source location is highlighted by a golden halo. If you click on a source in the 3D view, the corresponding montage channel will be selected.
* If scalp electrodes are part of the montage, the 3D whole-head view displays the corresponding electrodes on the head surface.

[[Image:Montage Editor (17).png]] [[Image:Montage Editor (16).png]]

Editing is not possible in the 3D view. Use the''' 2D view '''or the '''montage channel list''' instead.

=== Pgr/Icr View (Polygraphic / Intracranial Channels) ===

This view displays a scheme of the available polygraphic/intracranial Channels.

[[Image:Montage Editor (18).png]]

[[Image:Montage Editor (19).png]] Use the Intracranial Channels button to switch on/off the display of intracranial channels.

[[Image:Montage Editor (20).png]] Use the Polygraphic Channels button to switch on/off the display of polygraphic channels.

The following objects are displayed:

[[Image:Montage Editor (21).png]] '''Intracranial electrodes''' (brown color) which are available for the current data file.

[[Image:Montage Editor (22).png]] '''Polygraphic channels''' (black color) which are available for the current data file.

== Creating and Editing a Montage ==

=== Creating a New Montage ===

[[Image:Montage Editor (23).png]] Press the''' New 'Edit' Montage '''toolbar button. 

[[Image:Montage Editor (24).png]] This clears and opens the '''Edit' montage'' as indicated by the highlighted ''''Edit' Montage '''toolbar button. 

[[Image:Montage Editor (25).png]] Then select the '''Recorded Electrodes''',

[[Image:Montage Editor (26).png]] '''Virtual Electrodes''',

[[Image:Montage Editor (27).png]] '''MEG Sensors''',

[[Image:Montage Editor (20).png]] '''Polygraphic Channels''',

[[Image:Montage Editor (19).png]] or '''Intracranial Channels'''

toolbar buttons depending on which type of channels you want to add.

You can add new montage channels now in three different ways:

1. Add new montage channels in the '''2D view''' and '''Pgr/Icr view''' by selecting channels and dragging to the reference electrode (T7 to P7 in the example below)

[[Image:Montage Editor (28).png]]

2. Click on the ''Set chan. & ref''. text box. This box will start flashing to indicate that new channels can be added. Click alternately on the next channel to be added (in the 2D view, the Pgr/Icr view, or the montage channel list), followed by its reference electrode. Each new click will alternately define a new montage channel and its reference. When done adding new channels, click on the ''Set chan. & ref.'' text box again,'' ''which will stop flashing.

[[Image:Montage Editor (29).png]]

3. Select one or more channels (see “''Editing in the 2D View'' ''and Pgr/Icr View”'' and “''Editing in the Montage Channel List”'') and add them using the '''right-click popup menu'''.

To add '''source '''channels, switch to the desired source montage using the''' Standard Source''' '''Montages''' toolbar button [[Image:Montage Editor (30).png]], select montage channels in the Montage Channel List (see ''“Editing in the Montage Channel List”''), and copy and paste to the 'Edit' Montage.

For more details see the sections “''Editing in the 2D View and Pgr/Icr View”'' and ''“Editing in the Montage Channel List''” below.

=== Editing a Montage ===

In the Montage Editor, only one montage can be edited at a time. This is referred to as the ''''Edit' montage'''. The most convenient ways to edit recorded or virtual scalp montages are described below in the sections [[BESA_Research_Montage_Editor#Editing_a_Montage_in_the_2D_View_and_Pgr.2FIcr_View|Editing a Montage in the 2D View and Pgr/Icr View]] and [[BESA_Research_Montage_Editor#Editing_a_Montage_in_the_Montage_Channel_List|Editing a Montage in the Montage Channel List]]

Whenever you want to modify a predefined standard montage, an available '''user montage''', or an '''additional channel montage''', you have to select the montage you want to modify and copy it to the 'Edit' montage. If you have not yet edited a montage after starting the montage editor, the 'Edit' montage is empty.

When you switch from the selected current montage to the 'Edit' montage using the ''''Edit' Montage toolbar button''' [[Image:Montage Editor (31).png]], then the selected '''current montage''' is automatically copied to the 'Edit' montage. In addition, the Montage Editor copies the current montage to the 'Edit' montage automatically if you start dragging or deleting montage channels when viewing a selected montage.

If the 'Edit' montage is not empty, you can clear it by clicking again on the ''''Edit' Montage toolbar button''' or by clicking on the '''New 'Edit' Montage button''' [[Image:Montage Editor (23).png]] . Then switch''' '''to the montage you want to modify using the '''Standard User''', or '''Additional Montage buttons''' and switch back to the 'Edit' montage using the toolbar buttons. This copies''' '''the selected montage to the 'Edit' montage.

=== Changing the Reference of Montage Channels ===

In the ''''Edit' montage''', select one montage channel by clicking on the related electrode in the 2D View or select the channel from the montage channel list. Select more channels by holding down the '''Control key'''.

To change the reference of the selected channels, use the ''Set Reference ''text box in one of the following ways:

* Either drag from the ''Set Reference'' text box to an electrode in the 2D view, to a channel box in the Pgr/Icr view, to any of the standard reference text boxes at the top of the 2D view (see also [[BESA_Research_Montage_Editor#Editing_a_Montage_in_the_2D_View_and_Pgr.2FIcr_View|Editing a Montage in the 2D View and Pgr/Icr View]]) or onto a montage channel in the montage channel list as shown below.

[[Image:Montage Editor (32).png]]

* Or click on the ''Set Reference ''text box (it will start flashing), and then click on the desired reference channel in the Montage Channel List, in the 2D view, or in the Pgr/Icr view.

[[Image:Montage Editor (33).png]]

'''Note:''' If you want to modify the viewing reference of the '''recorded Referential''' or the '''virtual Referential''' montage, you don’t have to edit a montage. To change the viewing reference in the referential montages simply switch to the corresponding montage and drag from the ''Set Reference ''box to the desired new reference electrode in the 2D view (as shown in the section after next).

=== Creating New Average Channel Groups ===

Average channel groups can be used as references in montage channels. They are computed for each time point as the mean voltage over the amplitudes of included channels. If one channel is bad or not available, average channel groups including this channel are also not available.

For the creation of a new average channel group, at least two channels must be selected (see chapter [[BESA_Research_Montage_Editor#Editing_a_Montage_in_the_2D_View_and_Pgr.2FIcr_View|Editing a Montage in the 2D View and Pgr/Icr View]] for information about how channels are selected). Channels must be of the same type. Source channels and MEG sensors are not allowed in average channel groups.

Channels that have been selected multiple times will enter the average only once.

To create a new average channel group, activate the corresponding menu entry (see chapters “''Montage Channel List Popup Menu”'' and “''Edit Menu”'').

Note that you can get information about average channel groups which are currently available using the ''Average Channel Group Information'' dialog box.

=== Changing the Viewing Reference in Referential Montages ===

If the '''recorded Referential''' or the '''virtual Referential''' montage is displayed, an additional ''Set Reference'' text box is displayed in the '''2D view'''. In the example below, the viewing reference of the''' virtual Referential '''montage is changed from Cz to A2. The'' Set Reference ''box can be used to change the viewing reference in one of the following ways:

* Place the mouse cursor on the ''Set Reference ''text box and press and hold the left mouse button. Start to move the mouse while the left mouse button is still held down (“dragging”). The mouse cursor changes to a black cross as soon as dragging has begun. Move the mouse cursor to one of the visible electrodes in the 2D view or to a montage channel in the montage channel list. If the cursor is on top of an electrode or montage channel which can be set as a viewing reference, the cross-color changes to green. Release the left mouse button while the cursor cross is green. A new viewing reference is set.

[[Image:Montage Editor (34).png]]

* Alternatively, click on the ''Set Reference'' text box. It will start blinking. Then click onto the new reference channel either in the Montage Channel List, in the 2D view, or in the Pgr/Icr view.

[[Image:Montage Editor (35).png]]

Press the''' Exit''' and '''Set toolbar button''' [[Image:Montage Editor (36).png]] to return to the main window of the BESA Research program.

=== Re-reference to Linked Mastoids ===

In case the linked mastoids channels are classified as polygraphic, the following steps can be performed to create a linked mastoids reference montage.
# With the raw data set opened in BESA Research, press '''File''' -> '''Head surface points and sensors''' -> '''Save all file in Head Coordinates'''
# Open the exported ''*.ela'' file in a text editor. You will see that all of your electrodes have the label ''EEG'' and the mastoids will have the label ''POL''.
## Change the label of the mastoids to ''EEG''.
## Rename the mastoids ''M1'' and ''M2''. The renaming will lead to BESA Research detecting the electrodes as mastoids and giving them standard mastoid positions. Save the file.
# Return to BESA Research and press ''Ctrl-L''. This will open the channel and digitized head surface points dialog. Under '''Channel configuration''' browse to the *.ela file that you have just created and load it. You should now see that the mastoids are not displayed in black any longer.
# Press '''Edit''' -> '''Montage'''. In the middle pane select both your mastoid electrodes M1 and M2 holding down the Ctrl key. Right-click and select '''Create new channel group'''. Rename it to '''Linked Mastoids'''. The new channel group should appear over the left head scheme. If not, press ''E'' on the keyboard. Now select all your channels, press '''Set reference''' (bottom left) and click on '''Linked mastoids'''.

=== Editing a Montage in the 2D View and Pgr/Icr View ===

'''Reference Boxes'''

If the ''''Edit' montage''' is displayed, additional reference boxes are displayed at top of the '''2D view''' showing available multiple channel references or average channel groups (see “''Create New Average Channel Group”''). If not all available reference boxes can be shown, an additional text box [[Image:Montage Editor (37).png]]  is displayed. If the mouse cursor is positioned over this box, the remaining reference boxes will be displayed temporarily. Reference text boxes may be used to define references for new montage channels (see below).

Additional references displayed in blue are recorded references. Additional references shown in red are virtual references. The recorded (virtual) '''ears''' reference, for example, is the mean voltage of the amplitudes at recorded (virtual) electrodes A1 and A2. The recorded (virtual)''' mast''' reference is the mean voltage of the amplitudes at recorded (virtual) mastoid electrodes M1 and M2. If the electrodes A1/A2 or M1/M2 are not present in the current electrode configuration, or if the electrode locations have been digitized (i.e. the electrodes are not exactly at the default position), a recorded '''ears''' or recorded''' mast''' reference may be available. This reference is built of the two recorded electrodes that are closest to the standard positions of A1/A2 or M1/M2 if they are within 12 degrees of these standard positions. Note that this assignment of the reference is independent of the actual electrode label in this case. The '''mast''' reference in the example below is calculated as the mean voltage of the amplitudes at P7 and P8, for example. A recorded ears reference is not available in this example as there are no recorded electrodes within 12 degrees of the standard positions of A1/A2.

Note that you can right-click on a reference box of an average channel group to display the ''Average Channel Group Information'' dialog box showing detailed information about available average channel groups.

[[Image:Montage Editor (38).png]]

'''Selecting Montage Channels'''

Montage channels can be selected by clicking on the montage channel line or the channel circle/box. If a montage channel is selected, other selected montage channels will be deselected unless you also hold down the '''Control key'''. With the '''Control key''', the new montage channel is added to the current selection.

You may also drag a box with the left mouse button to select all channels within the rectangle box. Press the '''Control''' key when releasing the mouse button to add the channels to the current selection.

All montage channels are deselected by clicking beneath any montage channel while the''' Control key '''is not pressed, or by hitting the '''Escape key.'''

[[Image:Montage Editor (40).png]] [[Image:Montage Editor (39).png]]

'''Deleting Montage Channels'''

To delete montage channels, select them and activate the corresponding entry in the '''Edit menu''' or in the right-click '''popup menu''', or press the corresponding hot key (default: '''Delete''').

Note: If you want to clear the 'Edit' montage completely, use the corresponding entry in the ''''Edit' Montage popup menu'''.

'''Adding Montage Channels'''

There are four ways of adding new montage channels:

* If you previously copied or cut montage channels using the corresponding menu entry in the '''Edit menu''', you can paste them using the same menu or using the associated hot key (default: '''Control-V'''). The montage channels are inserted before the first selected montage channel in the 'Edit' montage. If no montage channel is selected, they are appended at the end of the '''montage channel list'''.
* Drag from a visible electrode or polygraphic/intracranial channel to another visible electrode or polygraphic/intracranial channel, to one of the additional reference boxes plotted at the top of the 2D view, or to a montage channel in the montage channel list. If the mouse cross becomes green, release the mouse button. The new montage channel will be added at the end of the montage channel list.

Use the '''Recorded Electrodes''' [[Image:Montage Editor (25).png]] ,

'''Virtual Electrodes''' [[Image:Montage Editor (26).png]] ,

'''MEG Sensors''' [[Image:Montage Editor (27).png]] ,

'''Polygraphic Channels''' [[Image:Montage Editor (20).png]] ,

or '''Intracranial Channels''' [[Image: Montage Editor (19).png]] 

toolbar buttons to display or hide the corresponding electrodes/channels.
You can hit the '''Escape''' key while dragging if you want to abort the drag operation.

* Click on the Set chan. & ref. text box. This box will start blinking to indicate that new channels can be added. Click alternatively on the next electrode/channel to be added (in the 2D view, The Pgr/Icr view, or the montage channel list), followed by its reference electrode (if required). Each new click will alternatively add a new montage channel and its reference. When done adding new channels, click again on the Set chan. & ref. text box, which will stop blinking.
* Select channels from the 2D view, the Pgr/Icr view, and the montage channel list and right-click on a selected channel to display a '''popup menu''', to add the selected channels.

'''Sorting Montage Channels'''

In the 2D view or the Pgr/Icr view, there is no way to modify the sequence of montage channels. Use the '''montage channel list''' instead as described in the section [[BESA_Research_Montage_Editor#Editing_a_Montage_in_the_Montage_Channel_List|Editing a Montage in the Montage Channel List]].

'''Changing the Reference'''

Select the montage channel(s) for which you wish to change the reference. If no montage channel is selected, you can modify the reference for all montage channels simultaneously.

Drag from the ''Set Reference'' text box at the bottom of the 2D view to another visible electrode/channel or to one of the additional reference boxes at top of the 2D view. Alternatively, click on the ''Set Reference'' text box (it will start blinking), and then click on the desired reference channel in the montage channel list, in the 2D view, or in the Pgr/Inc view.

Note that you can hit the''' Escape '''key if you want to abort the drag operation.

=== Editing a Montage in the Montage Channel List ===

If the ''''Edit' montage''' is currently displayed, this montage may be modified in the '''montage channel list''' as follows:

'''Selecting Montage Channels'''

Montage channels can be selected by clicking on the primary channel label box or on the reference label box. If a montage channel is selected, other selected montage channels will be deselected unless you also hold down the''' Control''' key. With the '''Control '''key pressed, the new montage channel is added to the current selection.

All montage channels are deselected by clicking beneath any montage channel while the '''Control''' key is not pressed, or by hitting the '''Escape''' key.

'''Deleting Montage Channels'''

To delete montage channels, select them and activate the corresponding entry in the '''Edit menu''' or in the right click '''popup menu''', or press the corresponding hot key (default: '''Delete''').

Another possibility is to drag them over the left border of the montage channel list – the mouse cursor changes to a litter box icon.

Note: If you want to clear the 'Edit' montage completely, use the corresponding entry in the ''''Edit' Montage popup menu'''.

'''Adding New Montage Channels'''

There are two ways to add new montage channels:

* If you previously copied or cut montage channels using the corresponding menu entry in the '''Edit menu''', you can paste them using the same menu or using the associated hot key (default: '''Control-V).''' The montage channels are inserted before the first selected montage channel in the 'Edit' montage. If no montage channel is selected, they are appended at the end of the '''montage channel list.'''
* Drag the selected montage channels to a position you want to insert them and press the '''Control''' key while you release the mouse button. The selected montage channels are copied and inserted at the current mouse position.

Other ways of adding new montage channels are possible in the '''2D view or Pgr/Icr view.'''

'''Sorting Montage Channels'''

Drag the selected montage channel(s) with the mouse to the new list position. When releasing the mouse button, the selected montage channels are cut from their current positions and inserted at the new position.

'''Changing the Reference'''

Changing the reference of a montage channel is not possible in the montage channel list. Please use the 2D view instead, as described in the section [[BESA_Research_Montage_Editor#Changing_the_Reference_of_Montage_Channels|Changing the Reference of Montage Channels]]

=== Editing a Montage in the 3D View ===

It is currently not possible to edit a montage in the 3D view. Please use the '''2D''' '''view '''and the '''montage channel list''' instead and refer to the corresponding chapters.

== Loading and Saving Montages ==

=== Saving Montages ===

In the Montage Editor, the ''''Edit' montage''', '''user montages,''' and '''additional channel''' '''montages''' can be saved. If the 'Edit' montage has been saved using the default settings, it is saved in the User Montages folder and is available from the '''Usr''' button (user montages) in the main window of the BESA Reasearch program.

If a montage is saved under a filename which is already used by another montage, the other montage is unloaded. A message box will inform the user before this happens.

If a montage is saved (or loaded) using the same file base name as an existing montage (e.g. '''Besa Research\Montages\UserMontages\Test.mtg''' and '''C:\Temp\Test.mtg'''), the montage label will receive the appendix “(2)” (''Test (2)'') etc.

Please note that the file selector dialog box which is displayed if a montage is going to be saved (or loaded) provides an additional selection list at the bottom of the dialog box. The ''Folders'' selection list can be used to switch to predefined folders, e.g. the current data file folder, to the ''User Montages'' folder or to the ''Additional Channels'' folder. The list also shows recently used folders.

By default, the extension '''.mtg''' and the User Montages folder is proposed for saving edited montages.

=== Saving Additional Channel Montages ===

If you specify the extension '''.sel''' when selecting the montage filename, you define that the saved montage belongs to the '''additional channel montages'''. Any other extension will result in adding the montage to the '''user montages''' after saving. Please make sure that you save additional channel montages either in the standard Additional Channel Montages folder or in the current data folder if you want to use the montage only for a specific data file.

Note that you can use the filter selection list close to the bottom of the file selector dialog box to switch between “common” montages and additional channel montages.

=== Loading Montages ===

To load a montage that is not located in the current data folder or in the User Montages or Additional Channel Montages folders, press the '''Open Montage push button''' on the toolbar or use the '''File / Open Montage''' menu item. Montages that have already been loaded at program start or by the user can be selected for viewing or editing via the '''User Montages'''  and '''Additional Channel Montages'''  toolbar buttons or via the '''User Montages menu''' or the '''Additional Channel Montages menu''' (please see online help chapter ''"Montage Editor / Reference / Popup Menus"'' for detailed information).

If a montage has already been loaded, it is not reloaded unless the file has been modified – e.g. by saving a montage file in the BESA Source Analysis module.

Note that several montages can be selected in the file selector dialog box to be loaded simultaneously.

=== Automatic Loading of Montages ===

The Montage Editor loads montages found at default locations automatically:

* At program start, all montages found in the ''User Montages folder'' or the ''Additional'' ''Channel Montages folder'' (and first-level subfolders) are loaded. They are displayed in the first section of the '''User Montages menu''' or the '''Additional Channel Montages '''menu.
* If the current data file in the main program is switched or a new data file is loaded, all montages''' '''found in the new data folder are loaded. They are displayed in the second section of the''' User Montages menu'''.
* If a source montage file is stored in the BESA Source Analysis module, it is automatically loaded and displayed in the '''User montages menu.'''

== Standard Montages ==

The Montage Editor provides several standard montages which can be applied to all EEG data files. The standard montages are subdivided into three groups:

* '''Recorded Standard Montages''' which are based on the recorded electrodes of the current
* '''Virtual Standard Montages''' which are based on virtual electrodes at predefined locations, and
* '''Standard Source Montages''' which are used to remontage the measured data to show the estimated underlying brain activity.

Additionally, several predefined '''additional channel montages''' are available which can be applied to all EEG data files or to data files that contain the corresponding channels, e.g. EKG.

* '''Predefined Additional Channel Montages''' are used to display eye activity and EKG or sphenoidal channels below the main montage channels.

See the next sections for details on the different standard montages.

=== Recorded Standard Montages ===

Recorded standard montages are sets of predefined channel configurations based on the recorded electrodes of the current data file. In the Montage Editor, recorded standard montages can be selected

using the '''Recorded Standard Montages popup menu''' which opens after clicking onto the '''Recorded Standard Montages''' toolbar button or activating the corresponding menu entry in the '''Montage menu.'''

The '''Original Recording''' and '''Original Average Reference''' '''montage''' have the same sequence of electrodes as the original recorded data. The other recorded standard montages (as well as the '''virtual standard montages''') are derived from predefined montage lists based on a standard set of 27 10-10 electrodes (Std-27):

<pre>
Fp1 Fpz Fp2

F9 F7 F3 Fz F4 F8 F10

A1  T7  C3  Cz  C4  T8  A2

P9 P7 P3 Pz P4 P8 P10

O1 Oz O2
</pre>

The Std-27 set includes the 21 electrodes of the 10-20 standard with some traditional labels replaced by the newer 10-10 standard (e.g. T3=T7, T5=P7). If the traditional 10-20 labeling is not set after program installation, it can be restored by entering the following lines in the BESA initialization file '''BESA.ini''' under section [Electrodes]:

<pre>
[Electrodes]

T7=T3

P7=T5

T8=T4

P8=T6
</pre>

This will relabel the names of these electrodes everywhere in the program. Thus, the standard-27 electrode set will be displayed as:

<pre>
Fp1 Fpz Fp2

F9 F7 F3 Fz F4 F8 F10

A1  T3  C3  Cz  C4  T4  A2

P9 T5 P3 Pz P4 T6 P10

O1 Oz O2
</pre>

A predefined montage channel is only displayed in the '''2D view''', if the recording electrode set contains an electrode that is equal to or close to its location (e.g. A1, T9, TP9 or P9 will be indicated). If the predefined montage channel is bipolar, e.g. A1-Cz, the recording electrode set has to contain electrodes with locations equal or close to the location of both channel (here A1) and reference (here Cz). Otherwise, the montage channel is not displayed in the 2D view. It is grayed in the '''montage channel list''' and the suffix “[NA]” is appended (“not available”).

If the common reference used for recording is a known single electrode, the common reference electrode is regarded as part of the recording electrode set. Predefined montage channels using the common reference can be displayed. The common reference will be included in the computation of the average reference. This is not possible, however, for EEG systems using a combination of electrodes as the common reference.

The following recorded standard montages are available:

* Average Reference
* Double Banana
* Triple Banana
* Horizontal Bipolar
* A1/A2 Reference
* Referential
* Original Recording
* Original Average Reference

==== Average Reference ====

In this traditional montage, the available channels of the Std-27 electrode set are displayed against the average reference. The average reference is computed for each time point as the mean voltage over the amplitudes of all scalp electrodes that are not bad. If the common reference used for recording is a known single electrode, it will be included in the computation of the average reference.

[[Image:Montage Editor (41).png]]

==== Double Banana ====

This is a longitudinal bipolar montage containing two left hemispheric, two right hemispheric and one midline longitudinal row of montage channels. Longitudinal rows are arranged from front to back. Predefined montage channels are only displayed if both channel and reference are available (i.e. recorded and not bad).

[[Image:Montage Editor (42).png]]

==== Triple Banana ====

The Triple Banana montage is an extended longitudinal bipolar montage. It has an additional inferior row on each side as compared to the '''Double Banana''' montage. Predefined montage channels are only displayed if both channel and reference are available (i.e. recorded and not bad). The Triple Banana montage is not available if less than 2 inferior electrodes are recorded or defined as ‘good’ on each side.

[[Image:Montage Editor (43).png]]

==== Horizontal Bipolar ====

The horizontal bipolar montage contains three transversal rows of montage channels. Transversal rows are arranged from left to right. Predefined montage channels are only displayed if both the channel and reference are available (i.e. recorded and not bad).

[[Image:Montage Editor (44).png]]

==== A1/A2 Reference ====

In this traditional montage, the available left-hemispheric channels of the Std-27 electrode set (except inferior electrodes F9, A1, P9) are displayed against the electrode A1 (or, if A1 is not available, a nearby channel such as P9 > T9 > TP9 > M1). The available right-hemispheric channels of the Std-27 electrode set (except inferior electrodes F10, A2, P10) are displayed against the electrode A2 (or a nearby channel such as P10 > T10 > TP10 > M2). The available midline electrodes of the Std-27 electrode set (except Fpz and Oz) are displayed twice, referenced a) to A1 and b) A2 (or a nearby channel). If neither A1 nor A2 nor one of the nearby channels are recorded or defined as ‘good’, the A1/A2 Reference montage is not available.

[[Image:Montage Editor (45).png]]

For this example, the electrodes A1 and A2 are not available. Therefore, the electrodes T9 and T10 have been used instead.

==== Referential ====

In this traditional montage, the available channels of the Std-27 electrode set are displayed against a common 'viewing reference'. The default viewing reference is Cz. Any of the recording electrodes in the EEG file may be used as viewing reference.

For details on how to change the viewing reference, see chapter [[BESA_Research_Montage_Editor#Changing_the_Viewing_Reference_in_Referential_Montages|Changing the Viewing Reference]].

Note that the viewing reference is independent of the common reference used for recording.

[[Image:Montage Editor (46).png]]

==== Original Recording ====

This montage displays the data as recorded. Note that channels defined as 'bad' are displayed in the '''2D view''' and '''Pgr/Icr view''' with grey color. In this case, the montage channel label is grayed in the '''montage channel list.'''

[[Image:Montage Editor (47).png]]

==== Original Average Reference ====

In this montage, the scalp electrodes are displayed in the recording sequence, versus average reference. The average reference is computed for each time point as the mean voltage over the amplitudes of all scalp electrodes that are not bad.

If the common reference is a known single electrode, it will be included in the computation of the average reference.

This montage is not available if the current data file contains no electrodes (e.g. a pure MEG data file).

[[Image:Montage Editor (48).png]]

=== Virtual Standard Montages ===

Virtual standard montages are sets of predefined channel configurations based on virtual electrodes. In the Montage Editor, virtual standard montages can be selected using the '''Virtual Standard Montages popup menu''' which opens after clicking onto the '''Virtual Standard Montages''' toolbar button or activating the corresponding menu entry in the '''Montage menu'''.

The virtual montages except ''Reference Free'' (10-10) and ''CSD-Laplacian'' (10-10) use predefined montage lists based on the same standard set of 27 10-10 electrodes (Std-27) as the recorded standard montages:

<pre>
Fp1 Fpz Fp2

F9 F7 F3 Fz F4 F8 F10

A1  T7  C3  Cz  C4  T8  A2

P9 P7 P3 Pz P4 P8 P10

O1 Oz O2
</pre>

The Std-27 set includes the 21 electrodes of the international 10-20 electrode standard with four traditional labels named according to the newer 10-10 standard (T3=T7, T4=T8, T5=P7, T6=P8). For the standard coordinates of the 27 electrode locations on the sphere see help chapter [[Electrodes_and_Surface_Locations#Recommendations_for_electrode_placement|Recommendations for Electrode Placement]]. ''Reference Free'' (10-10) and ''CSD-Laplacian'' (10-10) use predefined montage lists based on a standard set of 81 10-10 electrodes.

Virtual montages estimate the voltage at the idealized locations of the standard 27 (81) electrodes on a sphere using spherical spline interpolation. This method is described in Perrin et al. (Electroenceph. clin. Neurophysiol. 72:184-187, 1989); for more details please refer to chapter “''Mapping / Spherical Spline'' ''Maps”''. Using this interpolation, EEG traces can also be displayed for missing or bad electrodes. The use of interpolation is indicated by the keyword ‘virtual’ displayed in the upper left corner of the waveform window above the montage channel labels. In principal, spherical spline interpolation is possible outside the area covered by the recording electrodes. Over the lower half of the head, interpolation benefits greatly from the presence of inferior lateral electrodes (F9, A1, P9, F10, A2, P10). Although only a minimum of 2 separate channels with lower lateral electrodes is required, for example, A1/A2 or M1/M2, the use of 6 or 4 inferior lateral electrodes is recommended.

'''Note''': If the number of scalp electrodes is less than 12, virtual standard montages are not available since spline interpolation and interpolated montages cannot be computed.

The following virtual standard montages are available:

* Reference Free
* 10-10 Average
* CSD-Laplacian
* Double Banana
* Triple Banana
* Horizontal Bipolar
* A1/A2 Reference
* Combined Ears
* Referential
* Reference Free (10-10)
* CSD-Laplacian (10-10)



'''Virtual Standard Montage - Reference Free'''

In this montage, the standard 27 interpolated channels are displayed against a reference free average reference. The reference is estimated as the mean voltage over 642 equidistant locations covering the whole head sphere. Voltages are calculated by spherical spline interpolation. According to physics, the voltage integral over the outer surface of the head is zero. By using the mean voltage over the whole head as the reference a close approximation of the true zero reference is obtained.

[[Image:Montage Editor (49).png]]

'''Virtual Standard Montage - 10-10 Average'''

In this montage, the standard 27 interpolated channels are displayed against a virtual average reference. The average reference is computed for each time point as the mean voltage over the interpolated amplitudes of the extended 81 standard virtual scalp electrodes. Since this standard covers inferior electrodes, the 10-10 virtual average reference is not much different from the reference-free montage.

[[Image:Montage Editor (50).png]]

'''Virtual Standard Montage - CSD-Laplacian'''

In this montage, current source density (Laplacian) for each of the standard 27 interpolated electrodes is displayed. The CSD waveforms and maps are computed as the second spatial derivative by spherical spline interpolation and are implicitly reference-free. Because this method intrinsically uses information from all electrodes, it provides a more accurate estimation of the source current leaving and entering the skull than source derivations using only 3 or 4 neighboring electrodes. This is particularly true for electrodes at the boundary of the electrode array.

[[Image:Montage Editor (51).png]]

'''Virtual Standard Montage - Double Banana'''

This is a longitudinal bipolar montage containing two left hemispheric, two right-hemispheric and one midline longitudinal row of montage channels. Longitudinal rows are arranged from front to back. All channels are interpolated.

[[Image:Montage Editor (52).png]]

'''Virtual Standard Montage - Triple Banana'''

The Triple Banana montage is an extended longitudinal bipolar montage. It has an additional inferior row on each side as compared to the Double Banana montage. All channels are interpolated.

[[Image:Montage Editor (53).png]]

'''Virtual Standard Montage - Horizontal Bipolar'''

The horizontal bipolar montage contains three transversal rows of montage channels.

Transversal rows are arranged from left to right. All channels are interpolated.

[[Image:Montage Editor (54).png]]

'''Virtual Standard Montage - A1/A2 Reference'''

In this montage, the left-hemispheric channels of the standard 27 interpolated channels (except inferior electrodes F9, A1, P9) are displayed against the interpolated voltage at electrode A1. The right-hemispheric channels of the standard 27 interpolated channels (except inferior electrodes F10, A2, P10) are displayed against the interpolated voltage at electrode A2. The midline electrodes of the standard 27 interpolated channels (except Fpz and Oz) are displayed twice, referenced a) to the interpolated voltage at electrode A1 and b) to the interpolated voltage at electrode A2.

[[Image:Montage Editor (55).png]]

'''Virtual Standard Montage - Combined Ears'''

In this montage, the standard 27 interpolated channels are referenced to a computed virtual linked ears reference. The reference is calculated as the mean voltage of the interpolated amplitudes at A1 and A2 determined by spherical spline interpolation. The calculation of the average potential at the ears balances both sides correctly in contrast to the unknown bias when linking the ears or mastoid electrodes directly.

[[Image:Montage Editor (56).png]]

'''Virtual Standard Montage - Referential'''

In this montage, the standard 27 interpolated channels are displayed against a common virtual 'viewing reference'. The default viewing reference is Cz virtual. Any of the extended 81 standard virtual electrodes may be used as viewing reference.

For details on how to change the viewing reference, see the help chapter [[BESA_Research_Montage_Editor#Changing_the_Viewing_Reference_in_Referential_Montages|Changing the Viewing Reference]].

[[Image:Montage Editor (57).png]]

'''Virtual Standard Montage - Reference Free (10-10)'''

In this montage, the extended standard 81 electrode channels are displayed using spherical spline-interpolation and the reference-free mode. The reference is estimated as described for the ''Reference Free'' montage. This montage yields more detailed spatial information as compared to the reference-free 27 channel montage described above.

[[Image:Montage Editor (58).png]]

'''Virtual Standard Montage - CSD-Laplacian (10-10)'''

In this montage, current source density (Laplacian) for each of the standard 81 interpolated electrodes is displayed. The CSD is computed as described for the ''CSD-Laplacian'' montage. This montage may yield more spatial information than the 27 channel CSD-Laplacian montage described above.

[[Image:Montage Editor (59).png]]

=== Standard Source Montages ===

BESA Research provides several standard brain source montages for EEG review. The majority of these were derived from a set of 15 regional sources covering lateral and midline frontal, central and parietal cortex, midline fronto-polar and occipito-polar cortex as well as anterior and posterior temporal lobes bilaterally. The new source space 25s was derived from 25 sources below the standard 25 electrodes of the IFCN.

The following standard sources montages are provided:
* 25s
* BR_Brain Regions
* FR_Frontal Region
* CR_Central Region
* PR_Parietal Region
* TR_Temporal Region
* Evoked Potentials and MEG
* Resting State Montages

'''The frontal, central and parietal brain source montages (FR, CR, PR)''' were derived from the montage BR_Brain Regions in order to emphasize the respective regions in the display. They show the three source activities of each right and left lateral brain region separately along with the 13 other regional sources. The three source activities of each selected region are represented by three '''single dipoles''' with radial and tangential orientations. The activities of the right and left dipoles are displayed in the top six source channels of these montages.

'''The montage focusing onto the temporal lobe''' have 4 dipoles in each temporal lobe to reveal temporal-basal, polar, antero-lateral and postero-lateral source activities. The basal and polar sources are oriented tangentially, the lateral sources radially. The montage TR_Temporal Region separates these 4 aspects of the temporal lobe against the source currents in the other 11 regions irrespective of their orientation.

'''The resting state montages''' contain regional sources in brain regions associated with the Default Mode Network (DMN), fronto-parietal task control system as well as the dorsal attention system and the ventral attention system. They allow investigating resting state EEG and MEG data in a swift and straight-forward manner. For a more detailed description of the resting state montages, see [[#Standard Source Montage - Resting State Montages|Resting State Source Montages]].

'''Brain source montages''' are provided to facilitate the detection of focal source processes in the brain by reversing the overlap from different brain regions seen at the scalp. If brain activity is focal, i.e. represented predominantly in one source waveform, a large amount of the recorded scalp activity reflected in this trace will originate in the related brain region. If source activity is distributed over several traces, the origin is likely to be more widespread or in areas not precisely modelled by the combination of sources in the selected source montage. Each channel in a brain source montage can be viewed as a 'gross virtual electrode' placed onto a particular brain region.

Standardized brain source montages are defined for the 81 standard 10-10 electrodes. Therefore, the recording montage is first interpolated onto the 81 standard electrodes. Then the source waveforms are calculated using the source montage file.

Source montages are labeled using a specific [[#Naming Scheme of Standard Sources|naming scheme]] to characterize the location, orientation, and type of the underlying source.

'''Note''': If the number of scalp electrodes is less than 12, source montages cannot be computed.

==== Naming Scheme of Standard Sources ====

The label of a source channel used in a standard source montage is a combination of the source label itself and the abbreviation of the montage label (separated by an underscore '_').

The source label starts with an abbreviation of the '''brain region '''in which the source is located.

The following abbreviations are available:

* '''C''' ('''c'''entral),
* '''F''' ('''f'''rontal),
* '''Fp''' ('''f'''ronto-'''p'''olar),
* '''Op''' ('''o'''ccipito-'''p'''olar),
* '''P''' ('''p'''arietal),
* '''TA''' ('''t'''emporal '''a'''nterior),
* '''TB''' ('''t'''emporal '''b'''asal), and
* '''TP''' ('''t'''emporal '''p'''osterior)

If the source is a '''single dipole''' (and no '''regional source'''), the '''dipole orientation''' is given in the next lower case character. The orientations are specified as follows:

* '''p''' ('''p'''olar),
* '''r''' ('''r'''adial),
* '''ta''' ('''t'''angential '''a'''nterior), 
* '''tm''' ('''t'''angential '''m'''edial),
* '''tv''' ('''t'''angential '''v'''ertical), and 
* '''v''' ('''v'''ertical).

The last letter before the underscore ('_') which separates the abbreviation of the montage name specifies the '''hemisphere''':

* '''L''' ('''l'''eft hemisphere),
* '''M''' ('''m'''idline), and 
* '''R''' ('''r'''ight hemisphere).

Examples:

* TAL_BR: '''t'''emporal '''a'''nterior regional source, '''l'''eft hemisphere, source montage '''''BR'''_Brain Regions''
* FprM_TA: '''f'''ronto-'''p'''olar '''r'''adial single dipole source, '''m'''idline, source montage '''''TA'''_Temporal Lobe''

==== Source space 25s ====
''(requires BESA Research 7.0 or higher)''

The new source space 25s is based on sources below the standard 25 electrodes of the IFCN (International Federation of Clinical Neurophysiology). The sequence of channels is a reasonable compromise between transversal and longitudinal arrangements while an optimal separation of the major regions, i.e. frontal, central, temporal and parietal-occipital, has been achieved. At the same time, easy hemispheric comparison has been enabled for the frontal and parietal-occipital regions as well as for the left and right temporal channels by grouping these close to each other in the middle of the source space 25s. Thus, when looking at the 25s channels from top to bottom – like onto the head - we are going from frontal to central, include both temporal lobes, and then continue to parietal and occipital.

[[Image:25s_screenshot.png|400px]]

The source channels F9_25s (shown above) and F10_25s have been chosen to reflect mainly temporal polar activity while T9_25s and T10_25s reflect mainly basal activities of the right and left temporal lobes. All other sources reflect primarily the superficial activity of the cortex below each electrode (negative up, dipoles are pointing into cortex). Thus, focal activity (e.g. spikes and some EEG rhythms) can be associated more easily with the regions of origin. Compare focal EEG activity in source space 25s with the montages AV25 (average reference, virtual electrodes), CA25 (common average, recorded electrodes) and RF25 (reference-free, virtual) in folder UserMontages which have a comparable sequence of channels (press Usr for selection).

Below, spike 1 in Examples\Epilepsy\Spikes\SpikeExamples.fsg is displayed. The comparison shows the leading left temporal basal activity most clearly in the new source space 25s:

[[Image:25s_screenshot2.png|800px]]

==== Standard Source Montage - BR_Brain Regions ====

This source montage uses a set of 15 regional sources covering lateral and midline frontal, central and parietal cortex, midline fronto-polar and occipito-polar cortex as well as anterior and posterior temporal lobes bilaterally. It separates the activities of the 15 different brain regions and provides for fast comparison and quantification of the different activities.

Note: If the data contains '''MEG channels''', the corresponding MEG montages ''BRM ''(for magnetometers and axial gradiometers) and ''BRG'' (for planar gradiometers) are located in subfolder '''MEG'''.

<div><ul>
<li style="display: inline-block;"> [[File:Montage_Editor_(60).png|thumb|350px| Highlight on the left temporal anterior (TAL) regional source.]] </li>
<li style="display: inline-block;"> [[File:Montage_Editor_(61).png|thumb|350px|Highlight on the left frontal (FL) regional source. The two temporal sources in the foreground are still visible.]] </li>
<li style="display: inline-block;"> [[File:Montage_Editor_(62).png|thumb|350px|Highlight on the central midline (CM) regional source. The left-side sources in the foreground are also visible.]] </li>
</ul></div>



==== Standard Source Montage - CR_Central Region ====

This source montage displays the radial and tangential activities of the central brain region bilaterally in the first 6 '''single dipole''' channels. The other 13 '''regional sources''' separate the source activities arising from the other brain regions.

'''Note:''' If the data contains '''MEG channels''', the corresponding MEG montages ''BRM'' (for magnetometers and axial gradiometers) and ''BRG'' (for planar gradiometers) are located in subfolder '''MEG.'''

[[Image:Montage Editor (63).png]]

==== Standard Source Montage - FR_Frontal Region ====

This source montage displays the radial and tangential activities of the frontal brain region bilaterally in the first 6 '''single dipole''' channels. The other 13 '''regional sources''' separate the source activities arising from the other brain regions.

'''Note:''' If the data contains '''MEG channels''', the corresponding MEG montages ''BRM'' (for magnetometers and axial gradiometers) and ''BRG'' (for planar gradiometers) are located in subfolder '''MEG'''.

[[Image:Montage Editor (64).png]]

==== Standard Source Montage - PR_Parietal Region ====

This source montage displays the radial and tangential activities of the parietal brain region bilaterally in the first 6 '''single dipole''' channels. The other 13 '''regional sources''' separate the source activities arising from the other brain regions.

'''Note:''' If the data contains '''MEG channels''', the corresponding MEG montages ''BRM'' (for magnetometers and axial gradiometers) and ''BRG'' (for planar gradiometers) are located in subfolder''' MEG'''.

[[Image:Montage Editor (65).png]]

==== Standard Source Montage - TR_Temporal Region ====

This source montage displays the activities of four different aspects of the temporal lobe bilaterally in the first 8 dipole traces. There are 4 equivalent dipole sources in each temporal lobe to reveal temporal-basal, polar, antero-lateral and postero-lateral source activities. The basal and polar sources are oriented tangentially, the lateral sources radially. The montage TR_Temporal Region separates these 4 aspects of the temporal lobe from the source currents in the other 11 regions irrespective of their orientation. Head schemes illustrate location and orientation of each virtual electrode.

The ''Temporal Lobe'' and ''Temporal Region'' montages may be used to facilitate the detection of lateralized temporal lobe activities and of the differences of the activities at the various spatial aspects of both temporal lobes. Note that eye movement artifacts may be well represented by the sources at the tip of the temporal lobe due to similarities in the scalp distribution of the related source activities.

'''Note:''' If the data contains '''MEG channels''', the corresponding MEG montages ''BRM ''(for magnetometers and axial gradiometers) and ''BRG'' (for planar gradiometers) are located in subfolder '''MEG'''.

[[Image:Montage Editor (66).png]]

==== Evoked Potentials ====

BESA Research provides three standard source montages designed specifically for use with '''auditory (AEP), somatosensory (SEP), and visual (VEP) evoked data'''. Brain regions that are specifically relevant for the auditory, somatosensory, and visual pathway, respectively, are modeled with equivalent current dipoles. The remaining brain regions are modelled with regional sources. '''The Evoked Potentials source montages are available for EEG only'''.

==== Standard Source Montage - Resting State Montages ====

===== Introducing Resting State Networks =====

The default mode network (DMN) is the most commonly known brain network associated with resting state activity. It comprises brain regions that become less active, when the subject is engaged with a task, and in turn more active when the subject is resting (Raichle, MacLeod et al. 2001; Buckner, Andrews-Hanna et al. 2008). Thinking of the DMN as a “baseline” state of the brain would be misleading, as DMN brain regions have been linked with remembering the past, envisioning future events, and considering the thoughts and perspectives of other people (Buckner, Andrews-Hanna et al. 2008). This internal reflection is likely to happen when the brain is not otherwise engaged and the corresponding network thus becomes active in resting state. Recent research (Power, Cohen et al. 2011; Bressler and Menon 2010) has shown that several other brain networks known to become active during certain tasks can also be identified in resting state. Among them are the fronto-parietal task control system as well as the dorsal and ventral attention system (Power, Cohen et al. 2011). These networks seem to be stable systems that are internally connected even when no particular task is given. The resting state networks DMN, fronto-parietal task control system as well as the dorsal attention system and the ventral attention system are available in BESA Research as source montages. They allow investigating resting state EEG and MEG data in a swift and straight-forward manner.

===== How the Resting State Source Montages were created =====

BESA resting state source montages are based on source solutions, for which regional sources were placed at the MNI locations of the brain regions of interest. Source locations were derived from the following publications:

{| cellpadding=5
|DMN || Power, Cohen et al. 2011, Supplementary Information
|-
|Fronto-Parietal Task Control Network || Dosenbah, Fair et al. 2007
|-
|Dorsal Attention Network || Power, Cohen et al. 2011, Supplementary Information
|-
|Ventral Attention Network || Corbetta and Shulman 2002
|}



Bilateral Sources representing the same brain regions that were not perfectly symmetrical were symmetrized favoring the position of the less superficial source.

Additional noise sources were placed to increase the sensitivity of the sources of interest. Noise sources are easily identified by their name.

[[Image:Montage Editor (68).png]]

===== Naming scheme of the resting state montages =====

* Occ: Occipital lobe
* Fr (or Front): Frontal lobe
* Par: Parietal lobe
* Temp: Temporal lobe
* a: Anterior
* p: Posterior
* L: Left
* R: Right
* M: Middle

DMN:

* PCC: Posterior cingulate cortex
* mPFC: Medial prefrontal cortex
* AG: Angular gyrus
* LatTemp: Lateral temporal cortex

Dorsal Attention Network:

* FEF: Frontal eye fields
* IPS: Intraparietal sulcus

Fronto-Parietal Task Control Network:

* dlPFC: Dorsolateral prefrontal cortex
* IPL: Inferior parietal lobule
* IPS: Intraparietal sulcus

Ventral Attention Network:

* IFG: Inferior frontal gyrus
* MFG: Middle frontal gyrus
* TPJ: Temporoparietal junction
* STG: Superior temporal gyrus

===== Applying Resting State Source Montages on your data =====

For '''EEG''' data, the resting state source solutions were saved as source montages and are automatically available from the Menu '''"Montage / Source / Resting State Montages"'''. All sources are regularized with a regularization constant of 1%.

[[Image:Montage Editor (69).png]]

For '''MEG''' data, source montages are not pre-saved as there are varying MEG sensor types depending on the MEG system and manufacturer. MEG users should send a segment of their raw data to source analysis and load the desired source solution in the source analysis module.

Source solutions for resting state networks can be found here:

'''“C:\Program Files (x86)\BESA\Research_6_0\Montages\SourceMontages\Resting State Montages”.'''

After loading the source solution, it is possible to save it as a source montage with '''File / Save Source Montage As.''' The source montage will now be applied on the data in the main window and is also available from the menu option '''Montage / User-Defined'''.

===== Mean FFT Analysis in Resting State Source Space =====

Before applying the desired resting state source montage on the raw data, artifacts should be dealt with either by artifact correction and/or artifact rejection (as part of the mean FFT scan).

After applying the resting state source montage, a mean FFT can be calculated on the source waveforms associated with the source channels, i.e. the ongoing brain activity in the resting state network. Mean FFT performs block-wise FFTs on the whole dataset and the mean output is created when the end of the file is reached. Hereby, information can be drawn on the frequency content of the whole dataset.

Mean FFT can be started from the menu '''Process / Mean FFT Spectrum'''. The dialogue allows specifying the data range (by default all data) and the block length, BESA Research will use for calculating individual FFTs. Artifact thresholds for the source channels can also be defined. Mean FFT’s output will give an overview of the frequency content of the individual source channels.

===== TFC Analysis in Resting State Source Space =====

For TFC analysis in BESA Research, it is required to insert triggers in the raw resting state data. This can be done by pressing '''ERP / Insert Triggers'''. After insertion of the triggers, a paradigm must be created ('''ERP / Edit Paradigm''') that will allow the calculation of the time-frequency plots based on the inserted triggers in the final tab. Please make sure that any filters are only applied for artifact scanning in the filter tab and not for “averaging”, as this would also reduce the frequency domain for time-frequency analysis.

For TFC analysis of resting state data it is recommendable to not use any baseline correction in the paradigm window. If possible, however, a control resting condition should be used (e.g. eyes open / eyes closed) that can be contrasted with the resting state condition of interest in the time-frequency window.

In the time-frequency display, the results should be displayed as absolute values (the ABS button [[Image:Montage Editor (70).png]] )

If a control condition is available the two resting state conditions can also be contrasted by pressing the according subtraction button ([[Image:Montage Editor (71).png]]).

Coherence can be calculated between any resting state source channel and all other channels:

[[Image:Montage Editor (72).png]]

''This example shows resting state connectivity between the right-frontal source (red label) and the left-frontal source, as well as the right dorso-lateral prefrontal cortex. No strong coherence is found with the other network sources or the noise sources.''

It is possible to apply beamformer and / or DICS analysis on the time-frequency range of interest, suggesting the following possible workflow:

[[Image:Montage Editor (73).png]]

'''References'''

# Bressler, S. L. and V. Menon (2010). "Large-scale brain networks in cognition: emerging methods and principles." Trends Cogn Sci 14(6): 277-290.
# Buckner, R. L., J. R. Andrews-Hanna, et al. (2008). "The brain's default network: anatomy, function, and relevance to disease." Ann N Y Acad Sci 1124: 1-38.
# Corbetta, M. and G. L. Shulman (2002). "Control of goal-directed and stimulus-driven attention in the brain." Nat Rev Neurosci 3(3): 201-215.
# Dosenbach, N. U., D. A. Fair, et al. (2007). "Distinct brain networks for adaptive and stable task control in humans." Proc Natl Acad Sci U S A 104(26): 11073-11078.
# Power, J. D., A. L. Cohen, et al. (2011). "Functional network organization of the human brain." Neuron 72(4): 665-678.
# Raichle, M. E., A. M. MacLeod, et al. (2001). "A default mode of brain function." Proc Natl Acad Sci USA 98(2): 676-682.

=== Predefined Additional Channel Montages ===

Predefined '''additional channel montages''' may be used to display eye activity and EKG or sphenoidal channels in addition to the main montage channels.

In the Montage Editor, additional channel montages can be selected using the '''Additional Channel''' '''Montages''' popup menu. Open this menu by clicking onto the '''Additional Channel Montages toolbar''' '''button '''or activate the corresponding entry in the '''Montage''' menu.

The following predefined additional channel montages are available:

* EKG
* EOG-HB
* EOG-HV
* EOG-HVB
* EKG+EOG-HB
* EKG+EOG-HV
* EKG+EOG-HVB
* Sphenoidals_Avr
* Sphenoidals_Bip

'''Additional Channel Montage - EKG'''

This additional channel montage defines several polygraphic EKG channels. Depending on the recorded channels of your data file, the available EKG channel or channel combination is used.

Note that this montage is not available if the current data file does not contain any EKG channels.

<div style="color:#00000a;">[[Image:Montage Editor (74).png]]</div>

If you use different conventions for defining EKG channels, you may edit this montage in the Montage Editor using copy and paste from the ''Original Recording'' montage.

'''Additional Channel Montage - EOG-HB'''

This virtual additional channel montage automatically generates a horizontal EOG channel (H_EOG) and an eye blink channel (B_EOG) from the recorded EEG scalp electrodes using spherical splines interpolation to the standard 81 electrodes and a source montage that contrasts brain and eye activity. It is recommended to reference all electrodes including electrodes near the eyes, e.g. F11, F12, LO1, LO2, IO1, IO2, to the common reference, because this virtual montage can then better separate eye and brain activities (cf. Berg and Scherg, 1994). Special bipolar EOG channels cannot be used in this calculation and are, therefore, not recommended.

[[Image:Montage Editor (75).png]]

''The display shows the equivalent centers of the spatial components reflecting the topographies of horizontal eye movements (black) and eye blinks (green).''

This automatic virtual montage is currently available for EEG data files only.

'''Additional Channel Montage - EOG-HV'''

This virtual additional channel montage automatically generates a horizontal (''H_EOG'') and a vertical (''V_EOG'') EOG channel from the recorded EEG scalp electrodes using spherical splines interpolation to the standard 81 electrodes and a source montage that contrasts brain and eye activity. It is recommended to reference all electrodes including electrodes near the eyes, e.g. ''F11, F12, LO1, LO2'', ''IO1, IO2,'' to the common reference, because this virtual montage can then better separate eye and brain activities (cf. Berg and Scherg, 1994). Special bipolar EOG channels cannot be used in this calculation and are, therefore, not recommended.

[[Image:Montage Editor (76).png]]

''The display shows the equivalent centers of the spatial components reflecting the topographies of horizontal (black) and vertical (blue) eye movements.''

This automatic virtual montage is currently available for EEG data files only.

'''Additional Channel Montage - EOG-HVB'''

This '''additional channel montage''' is a combination of the '''EOG-HB''' and the '''EOG-HV''' additional channel montages. Please see there for a detailed description.

'''Additional Channel Montage - EKG+EOG-HB'''

This '''additional channel montage''' is a combination of the '''EKG''' and the '''EOG-HB''' additional channel montages. Please see there for a detailed description.

'''Additional Channel Montage - EKG+EOG-HV'''

This '''additional channel montage''' is a combination of the '''EKG''' and the '''EOG-HV''' additional channel montages. Please see there for a detailed description.

'''Additional Channel Montage - EKG+EOG-HVB'''

This '''additional channel montage''' is a combination of the '''EKG, '''the '''EOG-HB''', and the '''EOG-HV''' additional channel montages. Please see there for a detailed description.

'''Additional Channel Montage - Sphenoidals_Avr'''

This '''additional channel montage''' allows to display sphenoidal electrodes referenced against the common average reference in parallel with any recorded, virtual, or source montage for comparison.

[[Image:Montage Editor (77).png]]

If the current data file has no channels labeled'' SP1'' and ''SP2'', this montage is not available.

'''Additional Channel Montage - Sphenoidals_Bip'''

This '''additional channel montage''' allows to display sphenoidal electrodes using a bipolar reference in parallel with any recorded, virtual, or source montage for comparison. The reference is ''T3/T4'' (or ''T7/T8'') to enhance the hemispheric difference of vertical activity resulting from the activation of the inferior surface of the temporal lobe. Note that the standard source montage ''TR_Temporal Region'' provides for a better hemispheric separation of right and left temporal lobe activities (see e.g. example '''EEG-Focus\EEG2.eeg''').

[[Image:Montage Editor (78).png]]

If the current data file has no channels labeled ''SP1'' and'' SP2'', this montage is not available.

[[Category:Research Manual]]
{{BESAManualNav}}

Wrong characters in BESA software

2021-05-26T08:55:25Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 7.0 or higher
}}

= Problem description =

Recently Windows 10 introduced multi-language support. This can however cause troubles with displaying special characters in any type of software (i.e. µV). Instead, you can see something similar to this:

[[File:CharactersProblem.png]]

[[File:CharactersProblem02.png|400px]]

= Solution =

To solve this you need to change your system "Region & language" preferences.
* Please press the Start button on the taskbar, and press the settings button (the cogwheel icon).
* Select '''Time & Language''' section
* Select '''Region & language'''
** A window similar to the screenshot below will be displayed:

[[File:CharactersProblemReason.png|800px]]

* First, select '''Administrative language settings''' on the right side of the "Settings" window.
* Select '''Administrative''' tab of the "Region" window and then press '''Change system locale...''' button.
** Check if '''Beta: Use Unicode UTF-8 for worldwide language support''' is checked in the "Region Settings" window. If it is checked, please uncheck it.
** NOTE: If wrong characters are displayed in BESA Research after unchecking the above option, please change the '''Current system locale:''' to '''English (United States)''' in the "Region Settings" window.

[[File:Characterproblemsolution2.png|800px]]

You may also need to install the proper language configuration. Press the '''Add a language''' button and select the language pack that is the correct one for you. After installation is complete, make sure that the new language pack is at the top of the list. Alternatively, you can also select one of the installed languages if there is any. When you click on the selected language the up and down arrow will be shown. Press the up arrow until the selected language is at the top. You should end up with a configuration similar to this one:

[[File:CharactersProblemSolution.png|800px]]

Once this is done you may close all the windows and restart BESA Research. If the problem still persists try to install another language pack or contact [https://www.besa.de/support/support-page/ BESA support]

[[Category:Troubleshooting]]

Visualization with BESA Plot in FieldTrip

2021-05-06T12:10:31Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Plot
|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 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:
# 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.

== 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 <tt>ft_timelockanalysis</tt>. Its general form is something like this:
<tt>
avg: [147x271 double]
var: [147x271 double]
time: [1x271 double]
dof: [147x271 double]
label: {147x1 cell}
dimord: 'chan_time'
grad: [1x1 struct]
cfg: [1x1 struct]

</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:

<source lang="matlab">
status = besa_save2Avr(cfg.datapath, DataFile, data_matrix, ...
time_samples, channel_labels, data_scale_factor, time_scale_factor);
</source>

=== 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, ...
SphericalCoords, channel_labels, channel_type);
</source>

=== 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:

<source lang="matlab">
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
</source>

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 (*.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:

<source lang="matlab">
status = besa_save2Dataset(DatasetPath, DataFile, ...
ElpFile, ControlFile, NumChannels, NumTimeSamples, ...
SamplingInterval, FirstTimeSample);
</source>

=== 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: <code>BesaPlot <data_file_name> <control_file_name></code>

'''Example:'''

<source lang="text">
start /b cmd /c ""C:\Program Files (x86)\BESA\Plot\BesaPlot.exe" "D:\Path\to\erf1.avr" "D:\Path\to\erf1.bpctrl""
</source>

Please note that <code>start /b cmd /c</code> is used to start the program in background.

== 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.
* <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>

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:

<source lang="matlab">
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.
</source>

[[File:AverageResults.png|thumb|500px|c|none|Figure 2 Visualization of sensor level data with BESA Plot]]

and

<source lang="matlab">
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.
</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>.
# 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].

[[Category:ERP/ERF]] [[Category:BESA Plot]]

Batch Processing

2021-05-05T15:46:57Z

Abinash: Redirected page to BESA Research Batch Processing

#REDIRECT [[BESA Research Batch Processing]]

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 5.2 or higher

}}

== BESA batches allow you to automate nearly all analysis steps in BESA ==
The batch functionality that you find under the “Process” menu has been around for a while. Over the past few years, the toolkit that is available there has grown to an impressive size, such that with BESA Research 6.0, virtually all analysis steps can be automated, and applied to a list of files. At any point in time, the batch can also be halted to make parameter adjustments, should this be necessary. A complete analysis from pre-filtering, artifact scanning, averaging, source analysis, and export of results for subsequent statistical analysis, can be summarized in few steps. For many recurring tasks, ready-made batches are available already – and batches can also be assigned to function keys for maximum ease of use.

The set of available commands is shown below – sub-divided into
*general commands which allow e.g. loops, error handling, or pausing the batch for user input
*commands affecting the main program including ERP management
*commands for discrete source analysis
*commands for distributed source analysis
*time-frequency commands

[[File:BatchMenu.jpg|none|left]]

For example, to automate averaging and to prepare data for statistical analysis, using an experimental paradigm for a number of subjects, a batch could have the following elements:
*Load the paradigm
*Perform an artifact scan
*Average the conditions
*Export the data of each condition for further analysis with BESA Statistics

In batch code, this will look like the following:

[[File:BatchExample.png|none|left]]

To add any command, e.g. “Average”, select the command from the list of commands and check the options dialog that appears:

[[File:BatchExampleAv.png|700px|none|left]]

Left side: First click the "Add Command" button. Then select a command from the list. Right side: After selecting, a dialog opens where command options can be defined.

Once the batch is complete, it can run over all open files, over a user-defined file list (simply drag files into the list from Explorer), or just over the current file. Note that these batches are produced without entering any line of code by hand – it is all done using the graphical user interface of the Batch dialog.

== An example batch for Averaging step by step ==
The first two commands will load the paradigm file and perform the artifact scan:

<pre>
Paradigm(%Scripts%\Paradigm\Auditory\AEP_Intensity.PDG)
ArtifactScan(Wait)
</pre>

[[File:BatchArtScan.png|500px|none|left]]

The next command will average over the conditions:

<pre>
Average(%basename%_av, %Examples%\ERP-Auditory-Intensity\Averages\, NoDefaultName,OverwriteTarget, NoCorrect)
</pre>

[[File:BatchExampleAv2.png|500px|none|left]]

The next commands will loop over the first 5 segments (condition averages) and export them to different ASCII files to be used in further processing in BESA Statistics or other programs:

<pre>
MAINFileOpen(%Examples%\ERP-Auditory-Intensity\Averages\%basename%_av.fsg)
GENFor(segm, 1, 5, 1, 1)
MAINMarkBlock(WholeSegment,-,%segm%)
MAINExport(%basename%-export%segm%, \, Segment, ASCvec, Original, FiltOff, NoResample, Replace, -, )
GENEndFor()
</pre>

[[File:BatchExampleAv3.png|500px|none|left]]

Of course, many more options are available – check it out! For example, segments can automatically be sent to Source Analysis to perform automated imaging and export these results for further analysis, too.

[[Category:ERP/ERF]]

Batch Error Handling

2021-05-05T14:56:41Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 5.2 till 6.0

}}

=== Overview ===
This page informs about possible issues when running batches, and how to resolve them.

=== Several batches message box ===
If upon starting a batch the following info box appears:
[[File:Batch_error_1.png|none]]

Then it is possible that a previous instance of BESA Research has not shut down correctly, and there may still be a process of BESA Research running in the background. You can check for this by
* closing BESA Research
* right-clicking in the taskbar at the bottom of your window, and selecting the Task Manager. Select the tab "Processes" and display the background processes. There should be no background process running for BESA Research. However, it is likely that there are (hence the message box above). In this case:
** Either log off and on again, or
** Close the BESA Research background processes in the Task Manager (by right-click on the corresponding row in the Task Manager display).

Then re-start BESA Research.

=== Batch error 183 ===
It can occasionally happen that a batch can not be started, and informs you that the batch error 183 occurred (could not set up batch logging).
The reason (and the fix) is most likely the same as described above. If not, logging off and on again (or, in the worst-case scenario, re-booting the computer) will unlock the handle to the log file.

'''Note''': This problem should be fixed from version 6.1 January 2017 onwards.

[[Category:Troubleshooting]]

Batch Error Handling

2021-05-05T14:53:19Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 5.2 or higher

}}

=== Overview ===
This page informs about possible issues when running batches, and how to resolve them.

=== Several batches message box ===
If upon starting a batch the following info box appears:
[[File:Batch_error_1.png|none]]

Then it is possible that a previous instance of BESA Research has not shut down correctly, and there may still be a process of BESA Research running in the background. You can check for this by
* closing BESA Research
* right-clicking in the taskbar at the bottom of your window, and selecting the Task Manager. Select the tab "Processes" and display the background processes. There should be no background process running for BESA Research. However, it is likely that there are (hence the message box above). In this case:
** Either log off and on again, or
** Close the BESA Research background processes in the Task Manager (by right-click on the corresponding row in the Task Manager display).

Then re-start BESA Research.

=== Batch error 183 ===
It can occasionally happen that a batch can not be started, and informs you that the batch error 183 occurred (could not set up batch logging).
The reason (and the fix) is most likely the same as described above. If not, logging off and on again (or, in the worst-case scenario, re-booting the computer) will unlock the handle to the log file.

'''Note''': This problem should be fixed from version 6.1 January 2017 onwards.

[[Category:Troubleshooting]]

Best Strategy to Define a Multiple Source Model

2021-05-05T14:52:46Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 5.2 or higher
}}
== General ==
The best strategy to define a multiple source model is usually a sequential spatio-temporal approach. However, this may depend on the data to be analyzed. For strategies and examples, please read the key papers on multiple source analysis in [http://www.besa.de/publications/methods Publications/Methods].
== Guidelines ==
The following guidelines apply to discrete source analysis in general:

# The idea behind source analysis is to place or fit sources into the brain at all regions contributing to the data. Localization/fitting is hypothesis testing: The computed source waveforms separate the modeled brain activities and answer the question if and when activity takes place in the modeled brain region. Thus BESA Research reconstructs brain activity with high temporal resolution.
# Synchronous activity over several square cm can be modelled by a single equivalent source.
# Sources that are close together, have the same orientation and synchronous activity are indistinguishable.
# Sources that are close together but have different orientations and non-synchronous activity can well be separated by a discrete source model.
# Source waveforms are relatively insensitive to variations in dipole location. Therefore a single regional source can accurately model the activity of multiple gray matter patches in its vicinity. Regional sources should have a mutual distance of approximately 3cm or more between each other to prevent crosstalk of their source waveforms.
# Regional sources tend to provide more reliable solutions in noisy data as compared to single dipoles, because during a fit of a regional source only its location needs to be determined (no orientation has to be fitted).
# Very often the brain responds to a stimulus with bilateral symmetrical activation. Therefore, a pair of symmetrical regional sources is often a good initial source configuration. The resulting source waveforms will then indicate if the activity is really bilateral.
# The criterion for a good source model is not solely the residual variance. Rather, the following criteria should be met:
#* The source model should be in agreement with proven knowledge about the underlying brain activity (e.g. bilateral activation of the auditory cortex after an auditory stimulus as opposed to a single central brain area).
#* The source waveforms are an important indicator for the quality of a source model: When the time course of the obtained source waveforms for a (pair of) source(s) are distinctly different from those of other sources, this indicates that the corresponding source correctly models distinct brain activity. On the contrary, when two source waveforms show nearly the same time course, it should be checked if they pick up the activity of a brain region that is not part of the model, rather than truly modelling brain activity generated at their source locations.
#* PCA can be helpful in determining the minimum number of sources required to adequately model the data.

[[Category:Source Analysis]]

Running BESA Research on the Mac

2021-05-05T14:49:41Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 6.0 or higher

}}

You can run BESA Research on the Mac by means of a Windows emulator.

There are several systems available:
* Open source software
** [https://www.virtualbox.org/ Oracle VM VirtualBox]
* Commercial software
** Parallels Desktop for Mac [https://en.wikipedia.org/wiki/Parallels_Desktop_for_Mac]
** VMWare Fusion [https://en.wikipedia.org/wiki/VMware_Fusion]

=== Parallels Desktop for Mac ===

BESA Research runs with Parallels. However, it must not be run in the so-called "Coherency mode". This will lead to a crash. Outside this mode, BESA Research works.

=== VMWare Fusion ===

BESA Research runs with VMWare Fusion.

[[Category: Setup]]

Source Coherence Introduction and Concepts

2021-05-05T14:46:38Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Complete
|version = BESA Research 6.1 or higher
}}

== Source Coherence Module - Introduction ==

The Source Coherence Module provides new insights into the interaction between brain regions using brain source montages. These are derived from multiple source models of the data. Transforming the scalp surface into the brain signals using source montages greatly enhances the spatial resolution and largely removes one of the major drawbacks of traditional coherence analysis, the widespread overlap at the scalp due to volume conduction.

The Source Coherence Module provides a variety of tools for time-frequency based event-related data analysis.
* Time-frequency diagrams based on brain source or surface channels
* Display of temporal-spectral evolution (TSE) in percent
* Separation of evoked and induced activity
* Joint display of time-frequency or coherence plots with the evoked potential of individual channels
* Coherence estimate between any combination of surface or source channels (coherence or phase coherence)
* Computation and display of phase delay and latency difference between channels in a graphically defined time and frequency window
* Display of the inter-trial phase locking (ITPL)
* Comparison of two conditions
* Probability plots transforming all time-frequency parameters into statistical p-values
* Export of analysis results into ASCII text files

Time-frequency transforms are obtained in a very fast implementation based on complex demodulation. Apart from source channels, intracranial channels, and scalp channels, also other polygraphic channels, e.g. rectified EMG, can be included in the analysis.

A highly optimized graphical user interaction enables fast testing of hypotheses, and quick focusing on the features of interest.

For an introduction and an outline of the underlying concepts of source coherence, please continue with the next topic, "[[Source_Coherence_Introduction_and_Concepts#Concepts_of_Source_Coherence|''Concepts of Source Coherence'']]"

For more details check the following topics:
* [[Source_Coherence_Introduction_and_Concepts#Layout_of_the_Source_Coherence_Window|Layout of the Source Coherence Window]]
* Reference (in the BESA help)

Please also refer to our website at http://www.besa.de for the latest tutorial on source coherence and related topics.

== Concepts of Source Coherence ==

Recently, an increasing number of papers on oscillatory coupling between brain regions in animal studies and on time-frequency analysis of human EEG and MEG data has been published. BESA Research introduces several tools for fast and user-friendly time-frequency analysis including source and scalp coherence.

First, let us introduce some terminology in order to clarify the concepts:
* Surface waveform: a time signal recorded from EEG-electrodes or MEG sensors
* Source waveform: a time signal calculated for a specified brain region or cortical surface
* Source montage: the transformation of the on-going EEG into the estimated contributions or source waveforms of a set of brain regions

[[Image:SourceCoh Concepts (1).gif ]]

* Time-frequency analysis: analysis or display of the event-related time-locked or induced activity in the time-frequency domain
* Time-locked activity: event-related signal with similar wave shape over trials
* Induced activity: oscillatory activity occurring in a certain event-related time window with varying time lag and phase
* Oscillatory activity: activity occurring with several oscillations in a narrow frequency band; can be time-locked and/or induced

[[Image:SourceCoh Concepts (2).gif ]]

* TSE: temporal spectral evolution, change in amplitude or power over time relative to the baseline interval
* ERD/ERS: event-related (de)-synchronization, used as a synonym for TSE
* ERSP: event-related spectral perturbations, change in power or amplitude over time. This is the more general term and comprises ERD/ERS/TSE that is related to baseline.
* Correlation: correlation between two time signals, i.e. scalar product of normalized signals in time domain

[[Image:SourceCoh Concepts (3).gif ]]

* Spectral-temporal density function S(f,t) = A(f,t)*ei*ϕ(f,t): quantifies amplitude A and phase ϕ of a signal at a certain frequency f and latency t relative to an event
* Coherence: squared correlation of two spectral density functions S1(f,t) and S2(f,t) over trials, i.e. squared scalar product of S1(f,t) and S2(f,t) over trials, normalized across all trials
* Phase coherence: correlation of two normalized spectral density functions S1(f,t) and S2(f,t) over trials, quantified by the phase locking value (PLV)
* Phase locking value (PLV): scalar product of S1(f,t) and S2(f,t) over trials, where S1(f,t) and S2(f,t) are normalized, i.e. they become unit vectors in the complex plane

[[Image:SourceCoh Concepts (4).gif ]]

Phase coherence uses only the phase relationships between channels for the coherence estimate, not the amplitudes. The method implemented here was described by Lachaux et al. (1999). Phase coherence is described by the so-called "phase locking value" (PLV).

Comparison of the formulae for coherence and PLV illustrates that for constant amplitudes, PLV is equivalent to the square root of coherence.

=== Scalp Coherence ===

When coherence is calculated at the surface between 2 EEG channels or 2 MEG sensors, activity from various brain regions is picked up in each of the surface channels. Oscillatory activity in one brain region can already lead to a strong coherence between 2 surface channels because of the wide distribution of focal brain activity at the surface. This is due to the nature of the dipole fields when recording remotely and due to the smearing effect of the volume conduction in EEG. As a consequence, a coherence measure between surface channels cannot distinguish between coherence due to propagation and real coherence between the oscillatory activities in two coupled brain regions.

[[Image:SourceCoh Concepts (5).gif ]]

Whether true coherence can be detected at the scalp, depends mainly on the relative orientation of the source currents in the underlying brain regions and, to a lesser extent, on their distance in location. In the case of the auditory cortex, for example, both the left and right temporal planes produce vertical activity with strong bilateral contributions centrally (e.g. at C3/C4 and F3/F4). The spatial correlation of the radial activities at the lateral surfaces of the superior temporal gyrus is also very large between right and left scalp electrodes, e.g. at T3/T4. A current-source density montage (CSD or Laplacian) can reduce the effects of propagation on scalp coherence to a certain extent, because it enhances the radial current from the underlying cortex relative to more remote sources to some extent.

[[Image:SourceCoh Concepts (6).gif ]]

=== Source Coherence ===

An optimal separation is obtained by a source montage derived from a multiple source model. The model is used to create an inverse spatial filter, i.e. a source montage that separates the different brain activities. Activities that are not accounted for by the model, e.g. from background noise or EEG, are distributed amongst the sources and may therefore lead to 'noise coherence' between source channels. This 'noise coherence' can be large for sources that have very similar spatial topographies. It can be reduced by increasing the regularization constant of the inverse at the expense of a larger cross-talk between the sources or by including specific sources accounting for the 'noise'.

The principal steps to calculate a time-frequency diagram and source coherence are illustrated in the figure below for the real data example of error-related negativity (ERN). A multiple source model is created from averaged ERP data and/or sources in brain regions known to contribute from fMRI/PET studies using a similar task. The source model is then used to calculate a source montage and the source waveforms of the single trials. Next, every single trial is transformed into the time-frequency domain by selecting a certain temporal resolution using complex demodulation (a principle similar to FM radio). From the single trials, time-frequency displays are generated by averaging spectral density amplitude or power over trials. Source coherence is calculated by averaging the cross-spectral density of one reference channel with all other channels over trials and normalizing by the averaged auto-spectral densities (cf. figure above).

[[Image:SourceCoh Concepts (7).gif ]]

In this figure, you can see the separation of the occipital alpha rhythm (top 3 source waveforms) from the frontal midline ERN components (lowest 2 traces) which become prominent in most single trials after transforming from the 128 scalp electrodes onto 9 source areas in the brain. The time-frequency display shows a strong evoked ERN activity in the anterior and posterior cingulate gyrus (CG) sources and an induced suppression and rebound of ~20 Hz activity in the sensori-motor cortex bilaterally. Alpha suppression is most prominent in the midline occipital source. A double click onto the TF display of a selected channel leads to the rapid calculation of the coherence between this channel and all other channels.



== Layout of the Source Coherence Window ==

The source coherence window consists of

* title bar with information on the current display mode and the data file name
* menu bar where the display mode and analysis options are selected
* toolbar for quick access to the menu functions
* display area where time-frequency diagrams of all channels are shown
* information text about the current display mode and units (e.g. Power, Amplitude, or Coherence) at the bottom left
* color map with minimum and maximum normalization values at the center bottom. Any value higher or lower than the normalization value is assigned the color of the normalization value
* information text about the condition which is analyzed at the bottom right
* status bar with information about the channel, frequency, latency, and signal amplitude

[[Image:Coherence (1).gif]]

[[Category:Research Manual]]

{{BESAManualNav}}

Source Coherence Introduction and Concepts

2021-05-05T14:45:17Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Complete
|version = BESA Research 6.1 or higher
}}

== Source Coherence Module - Introduction ==

The Source Coherence Module provides new insights into interaction between brain regions using brain source montages. These are derived from multiple source models of the data. Transforming the scalp surface into the brain signals using source montages greatly enhances the spatial resolution and largely removes one of the major drawbacks of traditional coherence analysis, the widespread overlap at the scalp due to volume conduction.

The Source Coherence Module provides a variety of tools for time-frequency based event-related data analysis.
* Time-frequency diagrams based on brain source or surface channels
* Display of temporal-spectral evolution (TSE) in percent
* Separation of evoked and induced activity
* Joint display of time-frequency or coherence plots with the evoked potential of individual channels
* Coherence estimate between any combination of surface or source channels (coherence or phase coherence)
* Computation and display of phase delay and latency difference between channels in a graphically defined time and frequency window
* Display of the inter-trial phase locking (ITPL)
* Comparison of two conditions
* Probability plots transforming all time-frequency parameters into statistical p-values
* Export of analysis results into ASCII text files

Time-frequency transforms are obtained in a very fast implementation based on complex demodulation. Apart from source channels, intracranial channels, and scalp channels, also other polygraphic channels, e.g. rectified EMG, can be included into the analysis.

A highly optimized graphical user interaction enables a fast testing of hypotheses, and quick focusing onto the features of interest.

For an introduction and an outline of the underlying concepts of source coherence, please continue with the next topic, "[[Source_Coherence_Introduction_and_Concepts#Concepts_of_Source_Coherence|''Concepts of Source Coherence'']]"

For more details check the following topics:
* [[Source_Coherence_Introduction_and_Concepts#Layout_of_the_Source_Coherence_Window|Layout of the Source Coherence Window]]
* Reference (in the BESA help)

Please also refer to our website at http://www.besa.de for the latest tutorial on source coherence and related topics.

== Concepts of Source Coherence ==

Recently, an increasing number of papers on oscillatory coupling between brain regions in animal studies and on time-frequency analysis of human EEG and MEG data has been published. BESA Research introduces several tools for fast and user-friendly time-frequency analysis including source and scalp coherence.

First, let us introduce some terminology in order to clarify the concepts:
* Surface waveform: a time signal recorded from EEG-electrodes or MEG sensors
* Source waveform: a time signal calculated for a specified brain region or cortical surface
* Source montage: transformation of the on-going EEG into the estimated contributions or source waveforms of a set of brain regions

[[Image:SourceCoh Concepts (1).gif ]]

* Time-frequency analysis: analysis or display of the event-related time-locked or induced activity in the time-frequency domain
* Time-locked activity: event-related signal with similar wave shape over trials
* Induced activity: oscillatory activity occurring in a certain event-related time window with varying time lag and phase
* Oscillatory activity: activity occurring with several oscillations in a narrow frequency band; can be time-locked and/or induced

[[Image:SourceCoh Concepts (2).gif ]]

* TSE: temporal spectral evolution, change in amplitude or power over time relative to the baseline interval
* ERD/ERS: event-related (de)-synchronization, used as a synonym for TSE
* ERSP: event-related spectral perturbations, change in power or amplitude over time. This is the more general term and comprises ERD/ERS/TSE that are related to baseline.
* Correlation: correlation between two time signals, i.e. scalar product of normalized signals in time domain

[[Image:SourceCoh Concepts (3).gif ]]

* Spectral-temporal density function S(f,t) = A(f,t)*ei*ϕ(f,t): quantifies amplitude A and phase ϕ of a signal at a certain frequency f and latency t relative to an event
* Coherence: squared correlation of two spectral density functions S1(f,t) and S2(f,t) over trials, i.e. squared scalar product of S1(f,t) and S2(f,t) over trials, normalized across all trials
* Phase coherence: correlation of two normalized spectral density functions S1(f,t) and S2(f,t) over trials, quantified by the phase locking value (PLV)
* Phase locking value (PLV): scalar product of S1(f,t) and S2(f,t) over trials, where S1(f,t) and S2(f,t) are normalized, i.e. they become unit vectors in the complex plane

[[Image:SourceCoh Concepts (4).gif ]]

Phase coherence uses only the phase relationships between channels for the coherence estimate, not the amplitudes. The method implemented here was described by Lachaux et al. (1999). Phase coherence is described by the so-called "phase locking value" (PLV).

Comparison of the formulae for coherence and PLV illustrates that for constant amplitudes, PLV is equivalent to the square root of coherence.

=== Scalp Coherence ===

When coherence is calculated at the surface between 2 EEG channels or 2 MEG sensors, activity from various brain regions is picked up in each of the surface channels. Oscillatory activity in one brain region can already lead to a strong coherence between 2 surface channels because of the wide distribution of focal brain activity at the surface. This is due to the nature of the dipole fields when recording remotely and due to the smearing effect of the volume conduction in EEG. As a consequence, a coherence measure between surface channels cannot distinguish between coherence due to propagation and real coherence between the oscillatory activities in two coupled brain regions.

[[Image:SourceCoh Concepts (5).gif ]]

Whether true coherence can be detected at the scalp, depends mainly on the relative orientation of the source currents in the underlying brain regions and, to a lesser extent, on their distance in location. In the case of the auditory cortex, for example, both the left and right temporal planes produce vertical activity with strong bilateral contributions centrally (e.g. at C3/C4 and F3/F4). The spatial correlation of the radial activities at the lateral surfaces of the superior temporal gyrus is also very large between right and left scalp electrodes, e.g. at T3/T4. A current-source density montage (CSD or Laplacian) can reduce the effects of propagation on scalp coherence to a certain extent, because it enhances the radial current from the underlying cortex relative to more remote sources to some extent.

[[Image:SourceCoh Concepts (6).gif ]]

=== Source Coherence ===

An optimal separation is obtained by a source montage derived from a multiple source model. The model is used to create an inverse spatial filter, i.e. a source montage that separates the different brain activities. Activities that are not accounted for by the model, e.g. from background noise or EEG, are distributed amongst the sources and may therefore lead to 'noise coherence' between source channels. This 'noise coherence' can be large for sources which have very similar spatial topographies. It can be reduced by increasing the regularization constant of the inverse at the expense of a larger cross-talk between the sources or by including specific sources accounting for the 'noise'.

The principal steps to calculate a time-frequency diagram and source coherence are illustrated in the figure below for the real data example of error-related negativity (ERN). A multiple source model is created from averaged ERP data and/or sources in brain regions known to contribute from fMRI/PET studies using a similar task. The source model is then used to calculate a source montage and the source waveforms of the single trials. Next, each single trial is transformed into the time-frequency domain by selecting a certain temporal resolution using complex demodulation (a principle similar to FM radio). From the single trials, time-frequency displays are generated by averaging spectral density amplitude or power over trials. Source coherence is calculated by averaging the cross-spectral density of one reference channel with all other channels over trials and normalizing by the averaged auto-spectral densities (cf. figure above).

[[Image:SourceCoh Concepts (7).gif ]]

In this figure, you can see the separation of the occipital alpha rhythm (top 3 source waveforms) from the frontal midline ERN components (lowest 2 traces) which become prominent in most single trials after transforming from the 128 scalp electrodes onto 9 source areas in the brain. The time-frequency display shows a strong evoked ERN activity in the anterior and posterior cingulate gyrus (CG) sources and an induced suppression and rebound of ~20 Hz activity in the sensori-motor cortex bilaterally. Alpha suppression is most prominent in the midline occipital source. A double click onto the TF display of a selected channel leads to the rapid calculation of the coherence between this channel and all other channels.



== Layout of the Source Coherence Window ==

The source coherence window consists of

* title bar with information on the current display mode and the data file name
* menu bar where the display mode and analysis options are selected
* toolbar for quick access to the menu functions
* display area where time-frequency diagrams of all channels are shown
* information text about the current display mode and units (e.g. Power, Amplitude, or Coherence) at the bottom left
* color map with minimum and maximum normalization values at the center bottom. Any value higher or lower than the normalization value is assigned the color of the normalization value
* information text about the condition which is analyzed at the bottom right
* status bar with information about the channel, frequency, latency, and signal amplitude

[[Image:Coherence (1).gif]]

[[Category:Research Manual]]

{{BESAManualNav}}

Time Frequency Resolution In BESA

2021-05-05T14:44:24Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic+Coherence or higher
|version = BESA Research 5.2 or higher

}}

==FAQ==

The time-frequency resolution of the complex demodulation used in BESA depends on the user-settings for “''Frequency and Time Sampling''” in the “''Coherence''” tab of the ERP dialog box. The following table lists the 50% power and amplitude drops, respectively, as a function of the time-frequency sampling setting. Frequencies are given relative to the center frequency of a sharp frequency oscillation, latencies are given to the latency of a sharp time event.
For example, with a time-frequency setting of 1.0 Hz, 50 ms, a sine wave with sharp frequency f will be smoothed to a time-frequency signal that has a full power width at half maximum of 2×1.42 Hz. In other words, at frequencies f ± 1.42 Hz, the displayed power in the time-frequency plot is half of the displayed power at frequency f. A sharp time-event, (e.g. a sharp spike in the time-domain) will be smoothed to a time-frequency signal of 2×78.8 ms full power width at half maximum.

{| class="wikitable"
! style="font-weight: bold;" | Time-Frequency Sampling
! style="font-weight: bold;" | 50% Power Drop
! style="font-weight: bold;" | 50 % Amplitude Drop
|-
| 0.20 Hz / 250 ms
| ±0.283 Hz, ±394 ms
| ±0.397 Hz, ±554 ms
|-
| 0.25 Hz / 200 ms
| ±0.354 Hz, ±315 ms
| ±0.496 Hz, ±443 ms
|-
| 0.5 Hz / 100 ms
| ±0.708 Hz, ±158 ms
| ±0.993 Hz, ±222 ms
|-
| 1.0 Hz / 50 ms
| ±1.42 Hz, ±78.8 ms
| ±1.99 Hz, ±111 ms
|-
| 2.0 Hz / 25 ms
| ±2.83 Hz, ±39.4 ms
| ±3.97 Hz, ±55.4 ms
|-
| 2.5 Hz / 20 ms
| ±3.54 Hz, ±31.5 ms
| ±4.96 Hz, ±44.3 ms
|-
| 5.0 Hz / 10 ms
| ±7.08 Hz, ±15.8 ms
| ±9.93 Hz, ±22.2 ms
|-
| 10.0 Hz / 5 ms
| ±14.2 Hz, ±7.88 ms
| ±19.9 Hz, ±11.1 ms
|}

The following two plots show the frequency blurring (left) and the temporal blurring (right) for a time-frequency sampling of 2.0 Hz / 25 ms. When applying a denser frequency sampling, the frequency resolution will increase, and the time resolution will decrease proportionally (i.e. the x-axis scaling will change proportionally).

[[File: Time_Frequency_Resolution.png]]

[[Category:Time-Frequency]]

Averaging Across EEG Datasets from Different Recording Systems

2021-05-05T14:44:01Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 5.2 or higher
}}

The easiest way to create a grand average of files with differing electrode configurations is to use spatial interpolation to 81 standard positions. This will work for electrode nets with >81 electrodes (basically a spatial down-sampling), but it will also work for electrode nets with < 81 channels as BESA Research uses a spline interpolation that will calculate the signal at any position on the head surface based on the given information. Thus, it is possible to assume 81 standard electrodes distributed across the head and estimate their according signal. To use this spatial interpolation, do the following:
* In the Combine Conditions dialog ''"ERP → Combine Conditions…"'' simply load all the individual average files you want to grand-average, no matter how many electrodes they contain
* In the second tab ''"Condition List"'' define your conditions as usual
* Leave the third tab ''"Channel List"'' untouched
* In the fourth tab ''"Run Script"'' the option ''"Interpolate to standard 81 electrodes"'' will be automatically checked. Make sure that the setting ''"combine data from source files"'' is also checked if you want to create a grand average.
* Press OK to start averaging.

[[Category:ERP/ERF]]

Averaging Across EEG Datasets from Different Recording Systems

2021-05-05T14:42:18Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 6.1 or higher
}}

The easiest way to create a grand average of files with differing electrode configurations is to use spatial interpolation to 81 standard positions. This will work for electrode nets with >81 electrodes (basically a spatial down-sampling), but it will also work for electrode nets with < 81 channels as BESA Research uses a spline interpolation that will calculate the signal at any position on the head surface based on the given information. Thus, it is possible to assume 81 standard electrodes distributed across the head and estimate their according signal. To use this spatial interpolation, do the following:
* In the Combine Conditions dialog ''"ERP → Combine Conditions…"'' simply load all the individual average files you want to grand-average, no matter how many electrodes they contain
* In the second tab ''"Condition List"'' define your conditions as usual
* Leave the third tab ''"Channel List"'' untouched
* In the fourth tab ''"Run Script"'' the option ''"Interpolate to standard 81 electrodes"'' will be automatically checked. Make sure that the setting ''"combine data from source files"'' is also checked if you want to create a grand average.
* Press OK to start averaging.

[[Category:ERP/ERF]]

BESA Anonymizer

2021-05-05T14:41:53Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research
|version = BESA Research 6.1 or higher

}}

== Anonymizing EEG data ==
The BESA Anonymizer is a simple tool which allows you to anonymize EEG data sets that you would like to share for research purposes. You can anonymize single files, or all EEG files in a folder. Several EEG file formats are supported.

BESA Anonymizer comes as a free tool which is part of the installation package of BESA Research. You can start it simply by clicking the Windows Start button – the Anonymizer is part of the BESA program group.

[[File:BESAAnonymizer.png|none]]

== Anonymizing MRI data ==
MRI data sets can be anonymized directly in BESA MRI at the time of loading the data into the project. This workflow has also been improved in the March release of BESA MRI 2.0.
Note that this anonymization only affects BESA MRI projects including the data inside them. The original DICOM files remain unchanged. However, BESA MRI projects can be shared easily, without a need for incorporating the original MRI data.

[[Category:Preprocessing]]

BESA files extensions

2021-05-05T14:08:12Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 5.2 or higher
}}

One of the most important rules in BESA software is that the original data will never be changed during data processing (unless the user explicitly wants to do it by himself). All changes (e.g. signal processing like filtering) performed in BESA are kept in PC memory and not saved in the file. That type of approach has a drawback since all settings have to be re-generated whenever the data file is reopened. Therefore to keep all settings and be able to reload them whenever a file will be opened, BESA saves additional files beside the original one (with the same base name, but different file extensions). Note that this approach has one additional advantage: whenever the user wants to start analysis from scratch he or she just needs to delete the files responsible for a particular setting (or all files to get back to the initial state). Therefore a good understanding of BESA file nomenclature may be useful for advanced BESA users.

==Besa Research file extensions==

{| class="wikitable sortable"
! scope="col" style="width: 7%; | Application
! scope="col" style="width: 7%; | File extension
! scope="col" style="width: 25%; class="unsortable" | File function
! scope="col" style="width: 40%; class="unsortable" | When generated/changed
! scope="col" style="width: 20%; class="unsortable" | Wiki page
|-
| Main || .atf || Artifact coefficients || After setting up artifact correction (right mouse click, ''"Define artifact topography"'' menu) || [[Handling Artifacts in BESA]]
|-
| Main || .bad || Bad channels || Whenever electrode is marked as bad or is interpolated|| [[Review]]
|-
| Main || .cot || Head center coordinate || External file loaded to BESA. Information about file localization on disk is saved in .fst file|| [[Working_With_Additional_Files#cot_.28Head_center.29_file | Working With Additional Files]]
|-
| Main || .ela, .elp, .eps || Additional electrode configuration files || When electrodes configuration was loaded (''"File → Load Channel Configuration"''). *.elp file can be manually saved in ''"File → Head Surface Points and Sensors → Save Electrode File for Current Montatage"''|| <ul><li>[[Electrodes and Surface Locations]]</li> <li>[[Channel Definition File Formats]]</li></ul>
|-
| Main || .evt || Events || External text file. Can be loaded by selecting ''"ERP → open event file…"'' (and saved by ''"ERP → save event file…"''). After loading information is copied to .ftg and also .fst file is updated. || [[Event File Format]]
|-
| Main || .fst || General setup file || When data file is opened for a first time, updated whenever various settings are changed (i.e. filtration parameters, surface point file localization) ||
|-
| Main || .ftg || Triggers || On file close ||
|-
| Main || .ica || ICA topography || Can be saved after ICA analysis by clicking right mouse button on desired component name and selecting ''"Save Topography"'' || [[BESA Research ICA]]
|-
| Main || .mtg || Montages || If montage was changed, just .fst file is updated. Mtg files are kept in "C:\Users\Public\Documents\BESA\Research_6_1\Montages" || [[BESA Research Montage Editor]]
|-
| Main || .sel|| Additional Channel Montages || In Montage Editor window, menu "File → Save Montage As..." → Change 'Save as type' to 'Additional Channel Montages (*.sel)' || [[BESA_Research_Montage_Editor#Saving_Additional_Channel_Montages | Saving Additional Channel Montages]]
|-
| Main || .pdg || Paradigm || After loading or creating the paradigm || [[Paradigm File Format in BESA]]
|-
| Main || .pmg || MEG magnetometer sensors coordinates || External file loaded to BESA. Information about file localization is saved in .fst file || [[MEG Sensor Coordinate Files]]
|-
| Main || .pos || MEG gradiometer sensors coordinates || External file loaded to BESA. Information about file localization is saved in .fst file || [[MEG Sensor Coordinate Files]]
|-
| Main || .sfh || Coregistration info || Created when coregistration with MRI is started (''"File → MRI Coregistration.."''). Can be loaded externally, then information about file localization is saved in .fst file || [[Integration with MRI and fMRI]]
|-
| Main || .sfn || Labels assigned to electrode configuration .eps || External file loaded to BESA. Information about file localization saved in .fst file || [[Electrodes and Surface Locations]]
|-
| Main || .sfp || Digitized head surface points coordinates || External file loaded to BESA. Information about file localization saved in .fst file || [[Electrodes and Surface Locations]]
|-
| Main || .tal || Talairach coordinates || External file loaded to BESA. || <ul><li>[[Integration with MRI and fMRI]]</li> <li>[[Talairach Transformation File#AC-PC to Talairach|AC-PC to Talairach]]</li></ul>
|-
| Export || .avr || ASCII vectorized data file || Can be generated by ''"File → Export…"'' || [[Working_With_Additional_Files#ASCII_vectorized_format_.28.2A.avr.29 | Working With Additional Files]]
|-
| Export || .dat || Simple binary matrix with data || Can be generated by ''"File → Export…"'' || [[Working With Additional Files]]
|-
| Export || .edf || EDF+ (European Data Format) data file || Can be generated by ''"File → Export…"'' || [[Working With Additional Files]]
|-
| Export || .foc || BESA continuous native data file || Can be generated by ''"File → Export…"'' || [[Working_With_Additional_Files#Binary_format_.28.2A.foc.2C_.2A.fsg.29 | Working With Additional Files]]
|-
| Export || .fsg || BESA averaged native data file || Can be generated by ''"File → Export…"'' || [[Working_With_Additional_Files#Binary_format_.28.2A.foc.2C_.2A.fsg.29 | Working With Additional Files]]
|-
| Export || .generic || Additional header file for binary data (.dat) || File automatically created when binary data file was exported. This file is needed to reopen .dat file || [[Working_With_Additional_Files#Generic_File_Format | Working With Additional Files]]
|-
| Export || .mul || ASCII multiplexed data file || Can be generated by ''"File → Export…"'' || <ul><li>[[ASCII File Format]]</li> <li>[[Working_With_Additional_Files#ASCII_Multiplexed_format_.28.2A.mul.29 | Working With Additional Files]]</li></ul>
|-
| Export || 0.001, 0.002 … || ASCII vectorized or multiplexed epochs around triggers || Can be generated by ''"File → Export…"'' File extension indicates epoch number || <ul><li>[[ASCII File Format]]</li> <li>[[Working With Additional Files]]</li></ul>
|-
| Export || .stddev || ASCII standard deviations of data points in .fsg files || Can be generated by ''"File → Export…"'' || [[Export#Type_of_data_to_export|Type of data to export]]
|-
| Top Viewer || .bmp || bitmap file || Save of current state of Top Viewer window (''"File → Save as Bitmap..."'') || [[Advanced Top Viewer Features]]
|-
| Top Viewer || .eps || EPS graphic file || Save of current state of Top Viewer window (''"File → Save as eps file..."'') || [[Advanced Top Viewer Features]]
|-
| Top Viewer || .tva || Top viewer arrangement || On Top Viewer window close, only if settings or electrode position was changed || [[Advanced Top Viewer Features]]
|-
| Top Viewer || .tvs || Top Viewer settings || On Top Viewer window close, only if settings or electrode position was changed || [[Advanced Top Viewer Features]]
|-
| Time Frequency Analysis || .tfc || Averaged time-frequency data || Can be created when Time-Frequency Analysis is used (''"ERP → coherence tab"'') || [[Source Coherence Introduction and Concepts]]
|-
| Time Frequency Analysis || .tfcs || Single trial time-frequency data || Can be created when Time-Frequency Analysis is used (''"ERP → coherence tab"'') || [[Source Coherence Introduction and Concepts]]
|-
| Source Analysis || .bmp || bitmap file || Save of current state of 3D window (''"File → Save 3D window as a bitmap..."'') || [[Source Analysis 3D Imaging]]
|-
| Source Analysis || .bsa || Source analysis solution (i.e. dipoles) || Can be loaded or saved in menu of source analysis window (''"File → Save Solution.."'') || [[Source Analysis Introduction]]
|-
| Source Analysis || .dat || 3D Image ASCII file or voxel values for each dipole orientation || Can be exported in 3D window of Source Analysis (''"Image → Export Image as…"'') if sources for more than one latency was computed you can select option to save voxel values for each dipole orientation || [[Source Analysis 3D Imaging]]
|-
| Source Analysis || .hdr || 3D Image ANALYZE file || Can be exported in 3D window of Source Analysis (''"Image → Export Image as…"'') if sources for more than one latency was computed you can also choose option to save data for all latencies || [[Source Analysis 3D Imaging]]
|-
| Source Analysis || .laura || Result file of LAURA || After computation of LAURA in Source Analysis || [[Source Analysis 3D Imaging]]
|-
| Source Analysis || .loreta || Result file of LORETA || After computation of LORETA in Source Analysis || [[Source Analysis 3D Imaging]]
|-
| Source Analysis || .swf || Source waveforms || Can be saved in file menu of source analysis window (''"File → Save Source Waveforms..."'') || [[Export Dipole Moments of Fitted Sources]]
|-
| Source Analysis || .vmp || 3D Image BrainVoyager File (can be written with current resolution or with 1 mm) || Can be exported in 3D window of Source Analysis (''"Image → Export Image as…"'') || [[Source Analysis 3D Imaging]]
|-
| Source Analysis || .vtc || BrainVoyager VTC File for all latencies || If sources for more than one latency was computed it can be exported in 3D window of Source Analysis (''"Image → Export Image as…"'') || [[Source Analysis 3D Imaging]]
|-
| Source Analysis || .vts || Image ASCII voxel time series || If sources for more than one latency was computed it can be exported in 3D window of Source Analysis (''"Image → Export Image as…"'') || [[Source Analysis 3D Imaging]]
|-
| FFT || .faa, .fap, .far, .fai || Exported amplitude (fma), power (fmp), real (fmr) and imaginary part (fmi) of signal spectrum for average reference (Interpolated-81) montage || One of the export options in FFT window ''"File → Export FFT data menu"'' with ''"Interpolated-81"'' menu item selected (in the same menu) || [[BESA Research Spectral Analysis]]
|-
| FFT || .fba || Exported Amplitude in Bands || In FFT window menu ''"File → Export Amplitude in Bands"''|| [[BESA Research Spectral Analysis]]
|-
| FFT || .fbp || Exported Power in Bands || In FFT window menu ''"File → Export Power in Bands"''|| [[BESA Research Spectral Analysis]]
|-
| FFT || .fft || result of FFT || In FFT window ''"File → save…"''|| [[BESA Research Spectral Analysis]]
|-
| FFT || .fma, .fmp, .fmr, .fmi || Exported amplitude (fma), power (fmp), real (fmr) and imaginary part (fmi) of spectrum for current montage || One of export options in FFT window ''"File → Export FFT data"'' menu with ''"Current montage"'' menu item selected (in the same menu)|| [[BESA Research Spectral Analysis]]
|}

Batch Processing

2021-05-05T14:02:39Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 5.2 or higher

}}

== BESA batches allow you to automate nearly all analysis steps in BESA ==
The batch functionality that you find under the “Process” menu has been around for a while. Over the past few years, the toolkit that is available there has grown to an impressive size, such that with BESA Research 6.0, virtually all analysis steps can be automated, and applied to a list of files. At any point in time, the batch can also be halted to make parameter adjustments, should this be necessary. A complete analysis from pre-filtering, artifact scanning, averaging, source analysis, and export of results for subsequent statistical analysis, can be summarized in few steps. For many recurring tasks, ready-made batches are available already – and batches can also be assigned to function keys for maximum ease of use.

The set of available commands is shown below – sub-divided into
*general commands which allow e.g. loops, error handling, or pausing the batch for user input
*commands affecting the main program including ERP management
*commands for discrete source analysis
*commands for distributed source analysis
*time-frequency commands

[[File:BatchMenu.jpg|none|left]]

For example, to automate averaging and to prepare data for statistical analysis, using an experimental paradigm for a number of subjects, a batch could have the following elements:
*Load the paradigm
*Perform an artifact scan
*Average the conditions
*Export the data of each condition for further analysis with BESA Statistics

In batch code, this will look like the following:

[[File:BatchExample.png|none|left]]

To add any command, e.g. “Average”, select the command from the list of commands and check the options dialog that appears:

[[File:BatchExampleAv.png|700px|none|left]]

Left side: First click the "Add Command" button. Then select a command from the list. Right side: After selecting, a dialog opens where command options can be defined.

Once the batch is complete, it can run over all open files, over a user-defined file list (simply drag files into the list from Explorer), or just over the current file. Note that these batches are produced without entering any line of code by hand – it is all done using the graphical user interface of the Batch dialog.

== An example batch for Averaging step by step ==
The first two commands will load the paradigm file and perform the artifact scan:

<pre>
Paradigm(%Scripts%\Paradigm\Auditory\AEP_Intensity.PDG)
ArtifactScan(Wait)
</pre>

[[File:BatchArtScan.png|500px|none|left]]

The next command will average over the conditions:

<pre>
Average(%basename%_av, %Examples%\ERP-Auditory-Intensity\Averages\, NoDefaultName,OverwriteTarget, NoCorrect)
</pre>

[[File:BatchExampleAv2.png|500px|none|left]]

The next commands will loop over the first 5 segments (condition averages) and export them to different ASCII files to be used in further processing in BESA Statistics or other programs:

<pre>
MAINFileOpen(%Examples%\ERP-Auditory-Intensity\Averages\%basename%_av.fsg)
GENFor(segm, 1, 5, 1, 1)
MAINMarkBlock(WholeSegment,-,%segm%)
MAINExport(%basename%-export%segm%, \, Segment, ASCvec, Original, FiltOff, NoResample, Replace, -, )
GENEndFor()
</pre>

[[File:BatchExampleAv3.png|500px|none|left]]

Of course, many more options are available – check it out! For example, segments can automatically be sent to Source Analysis to perform automated imaging and export these results for further analysis, too.

[[Category:ERP/ERF]]

BESA Research Mapping

2021-05-05T13:39:22Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 6.1 or higher
}}

== Mapping ==

=== Mapping Window ===

The 3D mapping window displays whole-head 3D maps that reflect the voltage topography of the ongoing EEG using the current filter settings. The mapping procedure interpolates the EEG voltage or current source density (CSD) values over the whole head on the basis of the spherical splines method with moderate smoothing (Perrin et al. 1989). Maps are projected onto a 3D standardized head surface for a more realistic display of the voltage topography. The head surface was generated by averaging the MRI images of 50 normal subjects after transformation into Talairach space.

A single 3D map is displayed automatically at the detection peak of a clustered event when selecting an event or cluster in the cluster or hyper cluster displays. The single 3D map is rotated automatically to set the viewpoint to the center of gravity in the map to provide for immediate optimal inspection of dipolar topography. To adjust the viewpoint for a more detailed inspection, use the standard rotation buttons introduced below or use the mouse drag over the head.

[[Image:Mapping (1).gif ]]

''2D (left) and 3D (right) voltage maps in single head view at one time point. The EEG shows a detected event in the Av33 user-defined montage.''

The mapping window appears also when a cursor is set in the EEG data display by clicking onto the EEG.

The mapping window can appear in four different layouts: Single map, 6 maps in standard view, 15 serial maps, or customized series of maps. For details on 3D maps see the section ''"3D Maps".''

=== 3D Maps ===

'''Introduction'''

Maps are projected onto a 3D standardized head surface for a more realistic display of voltage topography. The head surface was generated by averaging the MRI images of 24 normal subjects after transformation to the Talairach space using the BrainVoyagerTM software. The standard 10-10 electrodes were adjusted to each individual head using the nasion, pre-auricular points (T9, T10), the inion and the eye canthii as landmarks. Using the spherical spline interpolation over the whole head, reference-free maps are calculated.

'''Controls'''

Use the mouse and the keyboard as follows:

* Click on a map in the standard whole head view with 6 preset viewpoints to display 15 serial maps in the selected view.
* Click on a serial map to select a specific time for the display of the 6 standard whole-head maps.

[[Image:Mapping (1).png ]]

''3D whole head maps at one latency using 6 standard viewpoints (left) and at a sequence of 15 latencies in serial view (right)''

* Double-click on a standard or serial map to obtain a single enlarged map.

[[Image:Mapping (3).gif ]]

* Drag over the head to rotate or use standard rotation buttons (for more details see below).
* Click or double click on the single head to obtain the 15 serial maps.
* Click on the EEG-Voltage label (bottom left) to display CSD maps. Click on the EEG-C.S.D. label which appears to redisplay voltage maps,
* or type''''' M''''' or '''''V''''' for voltage maps and '''''C''''' for CSD maps.
* When you move the mouse pointer over an electrode, the electrode label (and voltage if in voltage mode) is displayed.
* Left and right cursor keys plot new maps one time unit before or after the current time point. The time units can be adjusted using the '''Timing Interval''' toolbar button. [[Image:Mapping (4).gif ]]
* Up and down cursor keys raise or lower the scaling units of the map display. 3 steps change the scaling by a factor of 2.
* In the sequential and single map views, the head can be rotated, zoomed, or moved, by clicking and dragging with the mouse, depending on which of the '''3D Rotate''', '''3D''''''Magnify''', '''3D Move''' buttons in the toolbar has been depressed (see below). In addition, the three mouse dragging functions can be controlled directly by holding down the '''Shift''',''' Ctrl''', or '''Ctrl+Shift''' keys:

* <div style="margin-left:1.259cm;margin-right:0cm;">'''Shift-Drag''': Rotate</div>
* <div style="margin-left:1.259cm;margin-right:0cm;">'''Ctrl-Drag''': Move</div>
* <div style="margin-left:1.259cm;margin-right:0cm;">'''Shift+Ctrl-Drag''': Magnify/Zoom</div>

* Hit the '''Escape '''key to close the map window.

<div style="color:#00000a;margin-left:1.27cm;margin-right:0cm;"></div>

'''Toolbar'''

[[Image:Mapping (5).gif ]]

The toolbar offers a convenient way to modify the mapping display. The buttons are grouped as follows:

[[Image:Mapping (6).gif ]]

The '''3D Rotate''', '''3D Magnify''', and '''3D Move '''buttons select what happens when you click and drag with the mouse on a map:

Maps can be rotated (left button pressed), zoomed (middle button pressed), or moved (right button pressed).

The buttons are only enabled when 3D maps series or single heads are displayed. They are grayed in the standard 6-head view.

[[Image:Mapping (7).gif ]]

The '''3D Fast Rotation''' buttons rotate maps in steps of 45°, to the left (left button pressed), to the right (middle button pressed), or vertically (right button pressed).

The buttons are only enabled when maps series or single heads are displayed. They are grayed in the standard 6-head view.

[[Image:Mapping (8).gif ]]

These buttons control mapping layout and options.

The left button, '''Seq-Std Display''', toggles between the standard 6-head view (6 maps from different viewpoints) and the standard sequential top view display with 15 serial maps.

The middle button, '''Serial Arrangement''', opens a dropdown menu that allows for selection of either 5 x 7, 5 x 3 serial maps, a single map (1 x 1), or a custom array of serial maps:

[[Image:Mapping (9).gif ]]

The right button, '''Options''', opens the Options popup menu that allows for general settings of the maps:

[[Image:Mapping (10).gif ]]

* Toggle between 3D or 2D mapping
* Toggle between whole head mapping and top meridian projection
* Toggle between voltage and CSD display
* Toggle between serial and standard maps
* Toggle whether maps cover the entire head or are cut off at the lower part of the head
* Toggle display of electrodes on the maps
* Open the online Help

<div style="color:#00000a;"></div>

[[Image:Mapping (11).gif ]]

These buttons control the timing of maps: Pressing the left button, '''Timing Left''', generates maps one time unit earlier than the current map. Pressing the middle button, '''Timing Right''', generates maps one time unit later than the current map. In serial maps, clicking on the '''Timing Left/Right''' buttons in the toolbar moves the center latency to the first or last latency displayed, i.e. by 7 intervals in the standard 15 serial view.

Pressing the right button, '''Timing Interval''', opens a dropdown menu, allowing for the definition of the time interval between sequential maps or the frequency spacing between FFT maps. Voltages and CSD are interpolated to allow for the following standard and custom interval settings:

[[Image:Mapping (12).gif ]]

[[Image:Mapping (13).gif ]]

The final two buttons, '''Scaling''', raise (left) or lower (right) the scaling of the

maps. 3 steps change the scaling by a factor of 2.

'''Right Click Popup Menu'''

A right click on the voltage or CSD maps displays the Options popup menu that allows for general settings of the maps:

[[Image:Mapping (10).gif ]]

A right click on FFT maps displays the '''Options '''popup menu with specific settings for FFT and phase maps:

[[Image:Mapping (14).gif ]]

=== 2D Maps ===

2D Maps are generated by '''spherical spline interpolation''' and are projected onto a spherical head outline. The display shows contour lines. Red contour lines denote positive voltage, whereas blue contour lines stand for negative voltage. In addition, areas of negative voltage are denoted by a dotted pattern.

The user interaction in 2D maps is essentially the same as in 3D maps. 

Only the differences are listed here:

# [[Image:Mapping (7).gif ]] In sequential time view, dragging with the left mouse button over the heads rotates them by 90 degrees. The same is achieved using the '''standard rotation''' toolbar buttons 
# The buttons '''3D Rotate''', '''3D Magnify''', '''3D Move''', are disabled in 2D maps.

<div style="color:#00000a;"></div>

A top meridian projection of the heads can be selected either using the options menu (available from the '''Options''' toolbar button), or by right click with the mouse onto a map. Top meridian projected maps are cut off at a theta value of 110°.

The 2D maps use equipotential line mapping instead of color maps to avoid bias due to the selection of the color scale and in order to emphasize the shape of the voltage or CSD distribution rather than peak areas. The noise in the EEG tends to produce arbitrary shapes in the maps around zero. Therefore, we have spaced the equipotential lines symmetrically around zero at levels of ±1/2, ±3/2, ±5/2....., and shaded negativities below -1/2 of the scaling between lines. This produces maps that are less biased by EEG noise, especially when larger scales are used. In 3D maps, an additional color shading is shown for each of the potential compartments.

A minimum of 12 scalp channels is required to calculate the spline maps. However, a larger array of electrodes is recommended, including electrodes at inferior lateral sites (see help chapter ''"Special Topics / Working with Electrodes... / Electrodes / Recommendations for Electrode Placement"'').

=== Mapping of the FFT ===

FFT spectra can be mapped in a similar way as the voltage maps of the ongoing EEG. The maps are initiated from the FFT window (see the chapter ''"Spectral Analysis / FFT"'' for more information on FFT analysis).

The results can be shown in three different ways, which are described in detail below:

# FFT maps of amplitude or power showing the topography at a single frequency
# FFT maps of amplitude or power showing the mean over a preset frequency band
# Phase maps showing the voltage amplitude topography at a selected frequency and at a specific or different phase angles. Serial phase maps are encoded to show phase delay (in ms) for better comparison with EEG voltage maps, since phase shift is proportional to time delay. Phase maps are only available if the FFT was computed over a single data block.

<div style="color:#00000a;margin-left:1.27cm;margin-right:0cm;"></div>

The type of map and further mapping options can be selected from the menus '''Map''' and '''Options/Mapping''' in the FFT window.

<div style="color:#00000a;">[[Image:Mapping (15).gif ]]</div>

''Map menu of the FFT window''

Note: Mapping of FFT spectra is only possible if there are at least 12 electrodes!

'''Topographies at a given frequency and at a series of frequencies'''

The topography of the amplitude/power at any frequency can be viewed by clicking (single or double click) on an FFT spectral plot at that frequency. As with the voltage/source maps, maps are then plotted on the right of the screen.

[[Image:Mapping (16).gif ]]

''3D amplitude maps at a single frequency (left) and at a sequence of frequencies (right) ''

''for one viewing angle''

Analogous to voltage maps, clicking on a map will toggle between views from six sides of the head at one frequency (as above left), and a display showing a series of maps at 15 consecutive frequencies in one view (as above right). In the serial view, click on the left/right arrows in the toolbar to page 7 frequencies backward or forward. Pressing the arrow keys on the keyboard pages only one frequency.

The frequency spacing between consecutive maps can be adjusted using the [[Image:Mapping (4).gif ]] symbol on the toolbar. Clicking on the''' Timing Left/Right '''buttons in the toolbar shifts the consecutive frequency maps analogous to the serial voltage maps.

'''Topography at the peak frequency'''

In the FFT window, double click on the peak amplitude or click on the peak frequency value at the right of the FFT spectrum of a prominent channel to view the topography of the peak (dominant) frequency. For bad channels mapping of the peak frequency is disabled.

'''Topography of a frequency band'''

To view the topography of the amplitude/ power density within a given frequency band from 6 different views, select the band in the '''Map''' menu (for example, to view maps of the theta band, press '''Alt+M T''' on the keyboard). To view the topography of the summed amplitude/power over the total frequency range, select the menu item '''Map/Total'''. Click on one of the maps to view maps of each frequency band in one head view, together with a map showing the mean over the total frequency range.

If a frequency band is grayed out, its upper or lower limit is out of range for the current FFT. Use the item '''Band Name''' and '''Width''' in the '''Options '''menu of the FFT window to redefine frequency band settings.

'''Phase maps at a given frequency'''

Frequency maps visualize the frequency specific distribution of absolute amplitude or power over the scalp. However, these maps do not reveal phase lags caused by multiple underlying processes. Therefore, a series of spherical spline maps (phase maps) is calculated at successive phase angles α, according to

H(f, α) = cos(α) Re(f) + sin(α) Im(f)

where Re(f) and Im(f) are the real and imaginary voltage amplitude topographies at frequency f over the marked block which was transformed by FFT.

A '''change of topography''' in consecutive maps indicates '''multiple underlying processes'''. Only if there is '''no change''' in topography with phase, a '''single generator process''' may be assumed. The phase shifts can directly be translated into time lags between the different topographies that are displayed in the phase maps.

To view phase maps at a specific frequency, double click on the FFT signals or click on the peak amplitude value to generate amplitude or power maps at the selected frequency in the standard 6-head view. Then right click onto the map with the best viewpoint to obtain the '''Options '''popup menu for FFT maps:

[[Image:Mapping (14).gif ]]

Select ''Switch to Phase Mapping'' to obtain a series of 15 serial phase maps in 5 ms intervals. Changes to this interval and other mapping options are described above in section ''"3D Maps".'' Clicking on the '''Timing''' '''Left/Right''' buttons in the toolbar shifts the phase similar to the serial voltage and consecutive frequency maps.

Phase maps can also be initiated from the FFT window using the '''Map''' menu.

[[Image:Mapping (17).gif ]]

''3D phase maps: This sequence shows a change in topography, indicating that more than one process generates the EEG signals.''

Phase maps cannot be generated for mean spectra: generating means over frequencies or over a set of FFTs causes phase information to be lost. Thus, phase maps cannot be shown for frequency bands or for the result of mean FFTs between markers.

'''Toggling between EEG/MEG FFT maps'''

For a combined EEG and MEG measurement, the type of map (either EEG or MEG) that is currently selected is displayed in the left upper corner of the FFT window. Initially EEG is displayed. Click on the text to toggle between EEG and MEG FFT maps. A currently open map window will be updated immediately.

=== Source Images ===

Source images show the activation of brain regions which are represented by individual channels in source montages (for more information on source montages, see the chapter ''"Review / Remontaging"'').

To start a source image, first set a cursor on the pattern of interest by double clicking with the mouse. Use the '''IMG '''push button in the control ribbon or hit the ''''I'''' key on the keyboard to display a source image.

<div style="color:#00000a;"></div>

[[Image:Mapping (18).gif ]]

When a cursor is set in the waveforms display, you can toggle between voltage maps and source images by pressing or releasing the '''IMG''' button. Note that the montage switches automatically to a source montage when the '''IMG''' button is pressed. The last active source montage is displayed. If no source montage has been specified for the current EEG data set, the montage ''TR_Temporal Region'' is used.

For each dipole channel in the current montage, the activation is shown inside the approximate brain region which is modeled by the dipole source. Regional sources are not included in the image. As in maps, it is possible to toggle between six different views at one latency, and a sequence of 15 images. The activation is shown in 7 shades. The amplitude range is measured in nAm, since the current flow inside the brain is depicted.

Using the arrow buttons at the top, you can change the latency range which is displayed, and the interval between subsequent maps:

* Left group of arrow buttons: These buttons jump 7 maps forward (or backward) in time (i.e. the last (or first) map in the sequence becomes the central map.
* Right group of arrow buttons: These buttons increase (or decrease) the interval between the maps in the sequence 

<div style="color:#00000a;"></div>

Using the arrow buttons at the bottom, you can adjust the scaling of the source images. They change the amplitude range of the individual shades. The amplitude range between minimum and maximum color is shown at the bottom. In the example below, it is 0 ... 158 nAm.

[[Image:Mapping (19).gif ]]

''Images of brain activation during spike propagation in the left temporal lobe from the basal (-20 ms) to the polar (-5 ms) and antero-lateral aspects (0 ms). Each dipole source in the source montage is represented by an ellipsoid which covers the approximate volume modeled by the source. As in maps, different views at the same latency, or a sequence of maps in one view can be shown.''

=== Spherical Spline Maps ===

''Why use spherical spline interpolation?''

Spherical spline maps present an interpolation of the potential distribution at the scalp with zero integral over the whole head and maximum smoothness (Pascual et al. 1988; Pernier et al. 1989). Based on these assumptions, the spherical spline method provides an optimal interpolation within the area covered by electrodes on the scalp as well as an optimal extrapolation to the part of the sphere not covered by electrodes. The strength of the spherical spline method stems from the underlying physical boundary

condition: The voltages at the lower part must sum with those at the upper part to zero. Provided that the electrode coordinates are appropriately assigned to equivalent locations on a sphere, maximum smoothness is achieved by the intrinsic properties of splines which can be compared to bending an elastic bar around multiple supporting poles:

[[Image:Mapping (20).gif ]]

''Comparison of the effects of spherical splines (left) and linear interpolation (right).''

The spherical spline method allows to interpolate and integrate the scalp voltage differences across the entire sphere or whole head. Therefore, it can be used to provide a reference free estimate of the scalp voltages (Rfr-montage), and an estimate of the mean voltage at the ears (Ears-montage). We have compared the spherical spline maps with voltage maps generated by simulated dipole fields due to sources within a multi-shell spherical head model. Even with a small number of scalp electrodes located at the upper half of the head, a very accurate estimate of the reference signal can be obtained. In the worst case of vertical dipole fields (compare example '''eeg2.eeg''') the negative peak at the lower half of the head could be estimated with fair accuracy.

Traditional mapping and source derivations are based on interpolation of the voltages at selected nearby electrodes. This causes problems at electrodes at the boundary of the array and discontinuities within the electrode array. Further, if a voltage maximum lies between electrodes it will not be recognized. In contrast, the spherical spline method provides a maximally smooth interpolation between all electrodes and is capable of extrapolating voltage maxima within and outside of the electrode array. Intrinsically, the spherical splines also provide the optimal estimation of current source density (CSD) which reflects the current flow out of the brain through the skull.

BESA uses an implementation of the spherical splines method as described in the publication 'Spherical splines for scalp potential and current density mapping' by Perrin et al. (Electroencephalogr. Clin. Neurophysiol. 72:184-187, 1989). BESA uses 4th order spherical splines, including Legendre polynomials up to 50th degree. The smoothing constant l can be specified from the menu entry '''Options / Mapping / Spline Interpolation Smoothing Constant.'''

=== Current Source Density (CSD) ===

''What is Current Source Density (CSD)?''

'''The surface Laplacian operator '''(second spatial derivative of the voltage distribution in tissue) calculates the volume current flow out of the brain through the skull into the skin. That is why we use the term '''Current Source Density '''(CSD). The CSD montage will show a large signal if the cortical surface (convexity) is active. This corresponds to a radial superficial dipole.

If the brain activity is in a fissure (tangential dipole) the CSD signal is much weaker. The current flow in a tangential direction, so you will see two peaks of opposite polarity in the CSD maps, corresponding to where the volume current is leaving (+) and entering (-) the skull. The two zones of maximum current are closer together than in voltage maps, because the voltage is an integral over current source density.

Units of current source density are voltage per unit distance per unit distance (e.g. µV/cm²) or current per unit area (e.g. µA/cm²). Conversion from the second derivative of the voltage to current units is a complex issue because this requires knowledge about conductivities of the skull and scalp surfaces. Therefore, µV/cm² is used, i.e. just the second derivative of the voltage distribution.

=== Mapping/Tutorial ===

The aim of this section is to generate map and source image displays. It is assumed that you have loaded EEG2 (data: sub-folder '''Examples\EEG_Focus\eeg2.eeg''', electrode file: '''eeg2.elb''', filters variable 1.6-35 Hz, ''Org ''montage).

'''Basic steps'''

* 1. Move to the '''periodic pattern''' in EEG2 by clicking on the event marked at the middle of the event bar.

[[Image:Mapping (21).gif]]

* 2. Double click on any of the peak deflections to set a mark at the cursor position. A '''vertical bar''' (dark red on a yellow background) will be set, and '''Voltage maps''' will be displayed automatically. The latency will be shown at the bottom of the map window.

[[Image:Mapping (22).gif]]

* 3. Repeat double clicking on several different peaks to view the maps at different latencies. Type the '''Esc''' key to close the map window.
* 4. Press the '''SRC''' button, and from the dropdown menu select the'' TR-Temporal Region ''montage. Double-click on one of the peaks to display voltage maps again.
* 5. Press the '''IMG '''button, so that it remains down. The map display changes to '''source images''' calculated from the magnitude of the source channels at the marked latency.

[[Image:Mapping (23).gif]]

* 6. Repeat double clicking on several different peaks to view the source images at different latencies. Click on the up/down arrows to the right or left of the scaling bar below the images to increase or decrease scaling.
* 7. Select a prominent peak and double click to display the source images. On the keyboard press the '''left and right arrows''' to display source images at the next/previous sampling point or 5 ms later/earlier. Click on the up/down arrows right or left of the scale bar to increase or decrease scaling.
* 8. The latency should still be marked from the previous step. Type M to display voltage maps instead of the source images at the currently marked latency, and type 'i' again if you want to view the source images.
* 9. Press the '''IMG''' button again. Source images are switched off and 3D amplitude maps are displayed. Click on a map to convert the display from''' standard''' to '''sequential''' view.
* 10. Click and drag on a map to rotate the head to a new position. Note how all the maps in the sequential view are redrawn in the new position.
* 11. Try out the various controls on the 3D map toolbar (at the top of the map window. See chapter ''“3D Maps”'' for descriptions of the toolbar controls. Finally, switch back to 2D maps by disengaging the '''3D''' button.
*12. You may also select '''Voltage maps''' or any other process from the '''Process '''menu when a latency is marked and a source montage is displayed. Note that voltage maps can be displayed in all montages by clicking anywhere on the EEG, if the '''IMG''' button is not down.
* 13. Select average reference montage '''''Avr''''', and repeat double clicking on several different peaks (Note that typing 'i' will change to the last active source montage again and display source images).
* 14. Display voltage maps and make sure that electrodes are shown (if not, right-click on one of the heads, and select '''Show Electrodes''' from the popup menu. If selected, the electrode locations, projected on the 6 different views of the head model, will be displayed. Select '''Top Meridian Projection''' from the '''Options/Mapping''' menu to display a sequence of maps in equidistant steps relative to the marked latency. Note that the sequential maps present top views in meridian projection down to the level of F9, T9, P9, F10, T10, P10. By using spline interpolation, the maps are capable of covering this wider range as compared to traditional maps. Deselect top view sequential maps again.

'''Map and source image sequences'''
* 1. Select file '''segm1.eeg''' and select the ''TA_Temporal Lobe ''source montage. Engage the '''IMG '''button. The '''''TA '''''montage includes basal, anterior, and lateral temporal brain regions. Note how this montage suggests the onset of the spike in the left basal temporal lobe, with subsequent components in the anterior tip and lateral surface of the left temporal lobe.
* 2. Double click on the positive (upward-going) peak on the third channel from the top of the screen (left lateral temporal lobe). The source image will be displayed.
* 3. Click on the left lateral head view (top left source image). Note how the cursor changes to a hand over areas where clicks initiate an action. A series of 15 equidistant source images around the cursor latency will be displayed.

[[Image:Mapping (24).gif]]

* 4. Click on the left/right arrows at the left at the top of the map display to page 7 maps backward or forward.
* 5. Click on the left/right arrow at the right at the top of the map display to decrease or increase the interval between the sequential maps. Alternatively, you may set the interval in '''Interval between Sequential Maps''' in the '''Options/Mapping''' menu.
* 6. Type 'm' or 'v' to view a sequence of amplitude maps in the same time range (click the rotate-left button and the rotate-up-down button twice each to arrive at the head positions shown below):

[[Image:Mapping (25).gif]]

[[Category:Research Manual]]
{{BESAManualNav}}

BESA Research Manual

2021-05-05T13:32:29Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 6.1 or higher
}}

Welcome to BESA Research

BESA Research is the most widely used software for source analysis and dipole localization in EEG, MEG, Evoked Potentials and ERP research. BESA Research has been developed on the basis of over 20 years of experience in human brain research by Michael Scherg, University of Heidelberg, and Patrick Berg, University of Konstanz.

BESA Research provides many advanced features for automatic source localization, fast modelling and easy, interactive hypothesis testing. Source analysis can be performed simultaneously on multiple conditions with advanced constraints based on anatomy and physiology. In addition to discrete multiple dipole modelling, all major distributed imaging methods are also available for comparison. This makes BESA a complete all-in-one tool for source imaging.

BESA has all the features required to perform offline processing of continuously acquired EEG and MEG data using external and internal triggers, e.g. generated from an EMG channel or by spatio-temporal pattern search. Triggers are automatically mapped into predefined paradigms to provide for a fast selection of combinations of averages (addition, subtraction, subsets). Based on the spatial components approach of Berg and Scherg (1994), artifacts (e.g. eye and ECG) can be corrected on the fly from EEG, MEG, and ERP data.

Special viewing options allow for easy selection of averaged or single epochs of interest (e.g. spikes) and for immediate source localization and analysis. Digitized 3D sensor locations can be used to coregister EEG or MEG data with structural and functional MRI. Fitted dipole sources can be superimposed directly to the individual MR image. Using the interactive link with the famous BrainVoyager software of Dr. Rainer Goebel, BOLD clusters in functional MRI (fMRI) can be used directly as seeds for dipoles sources.

Information about updates and new releases can be found on the BESA homepage http://www.besa.de

== Review ==

[[Review]]

[[BESA Research Montage Editor|Montage Editor]]

[[BESA Research Mapping|Mapping]]

[[BESA Research Artifact Correction|Artifact Correction]]

[[BESA Research Spectral Analysis|Spectral Analysis (FFT and DSA)]]

[[BESA Research ERP Processing|ERP Processing]]

[[BESA Research ICA|Independent Component Analysis (ICA)]]

[[BESA Research Batch Processing|Batch Processing]]

== Source Analysis ==

[[Source Analysis Introduction|Starting the Source Analysis Module]]

[[Discrete Sources]]

[[Source Analysis Functions of the Window|Functions of the Source Analysis Window]]

[[Source Analysis Head Models|Head Models]]

[[Source Analysis 3D Imaging|3D Imaging]]

== Integration with MRI and fMRI ==

[[Integration with MRI and fMRI]]

== Source Coherence ==

[[Source Coherence Introduction and Concepts]]

[[Source Coherence How to...]]

== Export ==

[[Export]]

== MATLAB Interface ==

[[MATLAB Interface]]

== Special Topics ==

[[Electrodes and Surface Locations|Working with Electrodes and Surface Locations]]

[[The Initialization File: BESA.ini]]

[[Working With Additional Files]]

[[Category:Research Manual]]

{{BESAManualNav}}

BESA Research ERP Processing

2021-05-05T13:29:59Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 6.1 or higher
}}
== ERP Processing and Averaging ==

=== The Event-Related Potentials (ERP) Module - Introduction ===

The Event-Related Potentials (ERP) module provides many features that assist you with the analysis of event-related and evoked potentials and fields. These features, which are explained below, include

* defining triggers and conditions on the basis of experimental paradigms
* simultaneous averaging of multiple conditions
* viewing and analyzing averaged results in a Top Viewer window, e.g. for peak finding and measurement of amplitudes
* Grand Average and combining of conditions
* a Schmitt Trigger tool which makes it easy to convert EMG/EEG artifacts into trigger events
* a tool for editing triggers
* import and export of triggers from/to ASCII file

Coherence analysis is covered in the chapter on ''Source Coherence''.

A comprehensive review of the features is given in the online help chapter ''"ERP / Reference". ''Detailed tutorials can be found in help chapter ''" ERP / Functions of the ERP module"'' under the corresponding section.

=== Paradigms for Averaging ===

==== Introduction ====

Paradigms allow to use scripting techniques for averaging of multiple recordings.

They keep track of all relevant settings for averaging and make it easy to perform all necessary steps for optimal averaging of the data with a few mouse clicks. Each experimental task is described by a condition, in which trigger events are selected for averaging on the basis of user-defined boolean statements. Conditions can later be combined, e.g. to create grand averages or to form different conditions.

The process of editing paradigm definitions is started using the menu entries '''ERP / Open Paradigm''' or '''ERP / Edit Paradigm''', or the''' ERP''' push button in the main window, as shown in the figure below.

<div><ul>
<li style="display: inline-block;"> [[Image:ERP Processing (1).gif|thumb|300px|ERP menu. Select Open Paradigm to open a pre-defined paradigm file.]] </li>
<li style="display: inline-block;"> [[Image:ERP Processing (2).gif|thumb|500px|BESA Research browses to the folder of pre-defined paradigms automatically. From the 'Directories' drop-down menu, the current data directory can be quickly accessed as well.]] </li>
</ul></div>

Whereas '''''Open Paradigm''''' asks for a pre-defined paradigm file, '''''Edit Paradigm''''' opens the last used paradigm file for the current data set. If no paradigm is present, a new paradigm with default settings is created automatically. The '''ERP''' push button tries to open the last used paradigm file. If it does not exist, the '''''File Open''''' box appears.

The paradigm is defined using 6 (with Source Coherence Module 7) different dialog tabs. Each summarizes one aspect of the paradigm:

* Trigger: define trigger codes by assigning names and other attributes. Attributes (e.g. "intensity") help to group triggers.
* Condition: define a condition that selects trigger events from the experiment. Logical expressions can be combined to filter, for example, only the correct responses to a given task.
* Epoch: define epochs for averaging, baseline, artifact rejection, stimulus artifacts, and possibly a delay in trigger administration
* Filter: edit filter settings for averaging
* Artifact: reject artifacts by means of an interactive graphical rejection tool
* Average: select conditions for averaging and perform the average
* Coherence: specify settings for the time-frequency transformation (Source Coherence Module required)

==== Trigger ====

By default, triggers are defined by the trigger code. However, this definition is arbitrary and working with numbers instead of names is error-prone. The Trigger dialog tab in the Paradigm property sheet enables naming triggers and grouping triggers by making use of attributes. These attributes can be freely assigned, and each trigger obtains a unique definition for its attributes.

Generally, the suggested order in which to proceed for trigger definition is:

# Define the attributes which cover all the different sub-groups of triggers
# For each attribute, define the different values the attribute can take
# Define the triggers by selecting the code and the appropriate attribute values, and using the '''Set '''button

The ''Trigger ''dialog tab contains two main sections: The upper part is used to define attributes and attribute values for the triggers, whereas the lower part shows the current definitions.

For example, to assign names to the trigger codes:

* Enter names in the edit boxes of the ''Attribute Values'' section (below the attribute “name”)
* Add them to the list using the '''Add to List''' button.
* Define them by selecting code and name in the list box under the attribute “name” and clicking the '''Set''' button.

[[Image:ERP Processing (3).gif ]]

''Trigger tab. The trigger codes are shown. The attribute “name” is defined automatically.''

==== Condition ====

A condition holds all information connected with a task or a specific event type.

In the ERP module, averaging is performed on the basis of conditions. A condition is given by a logical expression that defines which trigger events are accepted for averaging. The "condition" tab makes it possible to define complex logic expressions and to see immediately how many matching trigger events result.

The example conditions shown in the figure below are defined in Tutorial 1: ''‘Using a P300 Paradigm for'' ''Averaging ''' in help chapter ''“ERP / Functions… / Paradigms for Averaging”,'' which gives a comprehensive overview of the features of the averaging module.

[[Image:ERP Processing (2).png ]]

''Editing a paradigm: Conditions can be defined by combining trigger definitions using boolean logic. This example shows definitions of three conditions (Rare, Standard, Hit) with a different number of matching events (40, 160, 134).''

==== Epoch ====

The dialog tab'' Epoch'' is used to set the epochs which define the averaging interval. For each condition, an individual set of epochs can be defined for averaging by the edit boxes at the top of the dialog tab. At the bottom of the tab, the current settings for all conditions can be viewed.

The push buttons in the center of the tab control the editing process. Two push buttons at the bottom right are for loading and saving a paradigm file.

[[Image:ERP Processing (3).png]]

''Epoch tab. 4 different epochs can be defined for each condition. A stimulus delay time can also be specified.''

==== Filter ====

The ''Filter ''dialog tab allows you to change filter settings prior to averaging the data. The low and high pass filters can be chosen differently for the artifact scan and the average. '''Note''': If the paradigm is edited for the first time, default filter settings are used. These can differ from the filter settings which you set in the review window. If a paradigm file was opened which does not contain filter settings, the filter settings which were chosen in the base module are displayed in the dialog tab.

[[Image:ERP Processing (4).png]]

''Filter tab. Low cutoff, high cutoff, and band pass filters can be applied.''

==== Artifact ====

The ''Artifact'' dialog tab provides an easy way to define artifact rejection thresholds and to exclude bad channels and bad sweeps from the analysis. This is achieved by scanning the data file and then using the graphics display presented in the center of the dialog tab, which shows channels and sweeps sorted according to user-defined criteria.

If the user does not check any of the options ''Fixed Thresholds'' and ''Artifact Scan Tool'', only regions that were explicitly marked as artifacts by the user will be excluded from the averages. If the option ''Fixed Thresholds'' is checked, the thresholds given in the edit boxes for amplitude and gradient are used to reject sweeps contaminated by artifacts.

The option ''Artifact Scan Tool'' provides an interactive tool for the comprehensive detection and rejection of both artifact-loaded channels and sweeps.

The figure below shows the result of an artifact scan. The trials are depicted in the columns of the display, sorted according to the highest amplitudes. Trials are rejected by mouse drag of the vertical cursor or by adjusting the rejection threshold for maximum amplitude, gradient, or minimum variance within a trial. The channels are depicted in the rows of the display, sorted according to the mean amplitude values over the trials. Similarly to excluding trials, a mouse drag of the horizontal cursor at the top of the display excludes channels.

[[Image:ERP Processing (5).gif ]]

''Artifact scan result. The channel at the top shows significantly higher amplitudes than the rest, indicated by the lighter color. Trials in the rightmost columns have been excluded from averaging.''

==== Average ====

The ''Average'' dialog tab is used to define

* which conditions are averaged
* which range of the data file is searched for trigger events matching the conditions
* whether automatic or query search is performed

The left part of the ''Average'' tab contains radio buttons to select the search range within the data file.

The central part contains a list of available conditions and of available constraints for averaging.

The list box array at the bottom shows the active and inactive conditions, the total number of matches, and the selected constraints. It provides an overview about the conditions which are selected. To add a condition to the list, select the condition and the constraint in the list boxes at the top, and click the '''Add to List''' button.

The right part contains additional sections for defining statistics and toggling between query averaging and automatic averaging.

Two push buttons at the bottom right are for loading and saving a paradigm file.

[[Image:ERP Processing (6).gif ]]

''Averaging tab. Range, conditions, and constraints for split-half averaging can be adjusted.''

The tutorial in help chapter ''"ERP / Functions... / Paradigms... / Tutorial 1: Using a P300 Paradigm for'' ''Averaging"'' gives an introduction to the available features. Different conditions can be combined to analyze experimental paradigms of high complexity.

A detailed description of the features can be found in the electronic help chapter ''"ERP / Reference / Using Paradigms to Average".''

==== Tutorial 1: Using a P300 Paradigm for Averaging ====

This example illustrates how to define and evaluate experimental paradigms using the ERP module. We will work on an experiment with an auditory oddball paradigm. The paradigm involves frequent and rare tones of different pitch and a motor response. The following list shows the encoding of the three different events to triggers:

{| style="border-spacing:0;width:16.374cm;"
|- style="background-color:#ffffff;border:0.5pt solid #00000a;padding-top:0cm;padding-bottom:0cm;padding-left:0.199cm;padding-right:0.191cm;"
|| '''File name'''
|| '''Triggers'''
| style="color:#00000a;" |
|| '''Motor response to'''
|- style="background-color:#ffffff;border:0.5pt solid #00000a;padding-top:0cm;padding-bottom:0cm;padding-left:0.199cm;padding-right:0.191cm;"
|| Freq-1200Hz-Resp-L.cnt
|| Frequent tone (1200Hz)

Rare tone (800Hz)

Motor response (left hand)
|| Trg. 1

Trg. 2

Trg. 128
|| frequent tone
|-
|}

The electrode positions were digitized. The file with the extension Freq-1200Hz-Resp-L.sfp contains the digitized 3D coordinates for the EEG.

Follow the steps in the next section to see how the ERP module allows to customize the paradigm and to evaluate and average conditions.

'''A. Open a pre-defined paradigm'''

'''1. Load data'''

* Load data file "'''Freq-1200Hz-Resp-L.cnt'''" in the folder "''Examples\ERP-P300-Auditory''".
* Select ''File/Head Surface Points'' and ''Sensors/Load Coordinate Files...'' Browse for the coordinate files '''P300-Aud.ela''' and '''P300-Aud.sfp ''' in the first two rows. They contain the type and location of the recorded electrodes. Enter '8mm' as electrode thickness, because in this example the coordinates specified in the sfp-file were measured 8mm away from the head surface.

[[Image:ERP Processing (7).gif ]]

'''2. Open a pre-defined paradigm definition'''

* Choose the menu entry '''ERP/Open Paradigm'''. A file selection box appears.

[[Image:ERP Processing (2).gif ]]

* Choose the folder ''"Auditory"'' and open the paradigm file "'''P300.PDG'''". Note that the combo box at the bottom of the file selection box enables a fast change between the default paradigm directory, and the directory where the data is stored.

The dialog box that appears consists of several pages ("tabs"). The tab which you see is divided into three sections. The list box on the left shows the current number of matches for all defined conditions. In this case, 3 conditions are defined:

* Rare
* Standard
* Hit

[[Image:ERP Processing (2).png ]]

Upon reading the paradigm, the conditions were automatically evaluated. For all three conditions, matches were found.

* In the list box in the center of the page, the currently defined conditions are displayed. The right part contains the command buttons. We will learn more about them later.
* Leave the page by selecting the tab "Epoch" at the top.

'''B. Average conditions'''

'''1. Edit Averaging Epochs'''

[[Image:ERP Processing (3).png]]

All three lines are highlighted since they all hold the same epoch settings which were entered into the edit boxes in the top half of the tab.

The epoch which is used for calculating the baseline is set to -100 ms (start position) and 0 ms (end position) by default.

* Select the last condition "Hit" in the list by a single click with the left mouse button. The settings are automatically copied to the edit boxes. In the edit section, change the averaging epoch to -800 ms (start position) and +100 ms (end position). Click the button '''"Assign to Selected"''' which changes the epoch settings for this condition only. This allows you to average the pre-stimulus potentials for the motor response selectively. You will notice that the artifact rejection interval was also updated, to fit into the newly defined averaging interval. Before you move on to the tab "Filter", adjust the Baseline Definition Epoch to [-800 ms, -700 ms] and click the button "'''Assign to Selected".'''

'''2. Filter Settings'''

In the "Filter" tab, the low-frequency cutoff filter and the high-frequency cutoff filter can be edited.

* If the high cutoff filter is enabled for either artifact scan or averaging, disable it by clicking off the checkboxes. Switch to the "Artifact" tab.

'''3. Artifact Rejection'''

The artifact rejection tool offers two methods of artifact rejection. If the check box "''Fixed Thresholds''" is checked, the thresholds given at the right of the tab are used as limits that must not be exceeded in a trial. If the check box "''Artifact Scan Tool''" is checked, a scan of the data set is used to find artifacts.

* Press the green "'''Start Scan'''" button. The data file is scanned for artifacts. After the scan is completed, a color-coded representation of maximum signal in channels and trials appears. This scan only has to be performed once for a data file, unless conditions are changed. The next time the paradigm is opened with the "''Edit Paradigm"'' command (cf. part C of this tutorial), the scan result will be available.

[[Image:ERP Processing (5).png]]

* The trials of the three active conditions are sorted according to their maximum amplitude from left to right. The red bar at the bottom indicates which of the trials are currently marked as artifacts due to their high amplitude. The channels are sorted according to the mean of the maximum amplitudes of the trials from bottom to top. Move the mouse pointer to the top of the display. The cursor changes to an up-down arrow. Click and drag the cursor down with the left mouse button to exclude the topmost channel, which carries an EKG artifact.
* Click on the button "'''Gradient'''" at the bottom of the dialog tab. The display changes to show the maximum gradients in the trials. The gradient is defined as the amplitude difference between two neighboring samples. Move the mouse pointer to the right edge of the display. When the cursor changes to a left-right arrow, click and drag the cursor to the left with the left mouse button to exclude the sweeps with the highest gradients, which are due to eye artifacts.
* At the new position of the dividing line which separates artifacts from good trials, press the right mouse button. A popup menu with information about the channel and trial at the cursor position appears.

[[Image:ERP Processing (9).gif ]]

* Choose the menu entry "'''Show Trial".''' The trial is displayed in the EEG. If it still carries an artifact, more sweeps should be excluded.
* For more information about the artifact scan tool, please refer to the corresponding reference section in the electronic help. Switch to the "Average" tab now.

'''4. Averaging'''

* At the bottom of the Average dialog tab, a list of currently selected conditions for averaging is shown. It already contains the three conditions for which matches were found in the EEG file. The right-most column indicates that all trigger events which matched the conditions will be averaged ("A").
* Double-click on the condition "Hit" in the list box at the bottom. The cross in front of the condition name disappears, which indicates that this condition will not be averaged. Double-click it again to activate averaging of the condition again.
* Click the green button '''"Average"''' on the right to start averaging. The progress is shown in an information window.

[[Image:ERP1.png]]

To cancel the averaging process, press any key. A message box appears. If you choose "'''No'''" averaging is continued. Choosing "'''Yes'''" stops the averaging process and asks you for a file name for each condition. After saving, the new averaged file is opened and the averaged segments are automatically displayed in the Top Viewer window. If you choose "'''Cancel'''", the results for the condition are not saved.

'''C. Edit a pre-defined paradigm'''

'''1. Load data and paradigm file'''

* With file "'''Freq-1200Hz-Resp-L.cnt'''" open, choose menu entry '''ERP/Edit Paradigm''', which opens the paradigm again (the copy of the paradigm file that was stored in the data directory), including the changes which were made in the last session.

'''2. Edit trigger definition'''

* Choose the tab "Trigger" on the top left. You now see the definition of triggers in the list view box at the bottom.

[[Image:ERP Processing (8).png]]

* The top half of the tab contains the edit section. In the top row, attributes which describe experimental categories can be defined or deleted. The next row shows the attribute values which are available. The values which are currently active for the selected trigger code (left) are highlighted.
* Trigger code 128 does not have a proper definition for the attribute "frequency". To change the definition:
** In the list box below the attribute "code" (left), choose code 128.
** In the edit box below the attribute "frequency", type in "undefined". Click the push button "'''Add to List'''" on the righthand side, which adds the new value into the list box and selects it automatically.
** Click the button "'''Set'''" to set the new definition for trigger code 128.
** Alternatively: right-click with the mouse directly on the value which you want to change in the list view box at the bottom of the tab. See what happens... (more information about defining triggers can be found in the electronic help reference section).
** The definition for trigger 128 has changed. Choose the tab "Condition" (top of the page) to get back to the condition page.

'''3. Edit conditions'''

* Switch to the 'Condition' tab. Select the last line of the condition edit list box (center of page) by a single click with the left mouse button. The name of the condition appears in the top left corner of this section of the page.

You can edit the name in the name edit field, and rename the condition by clicking the "'''Replace"'''" button.

Now we will add a new condition that links the standard stimulus with a response time:
A new condition is defined as follows: In the name field, type in a new name, e.g. "Resp_Time".

In the list box "Qualifier", select "CURRENT".

In the list box "Attribute", select "type".

In the list box "Operator", select "IS".

In the list box "Value", select "auditory".

Click the '''"Insert"''' button to start up the new condition. The name is automatically assigned to the new condition.

In the list box "Qualifier", select "NEXT".

In the list box "Attribute", select "Interval".

In the list box "Operator", select "IS LESS THAN".

In the edit box that appeared under "Value", type 500.

Click the "'''AND"''' button to extend the condition.

In the list box "Qualifier", select "NEXT".

In the list box "Attribute", select "name".

In the list box "Operator", select "IS".

In the list box "Value", select "response".

Finish off the condition by clicking the '''"AND"''' button again.

* The new condition is automatically evaluated. 160 matches are found, i.e. in all cases, the response was within 500 ms.
* Select the line "Next.Interval IS LESS THAN 500 ms" in the condition. Enter the value "300" in the edit box at the top right of the tab and click the "'''Replace'''" button. The condition changes accordingly and is re-evaluated. Only 142 matches are found now.

[[Image:ERP Processing (9).png]]

* If you leave the dialog box with the "'''OK'''" button, the settings are automatically stored in the data directory if the directory is writeable. If you choose the menu entry '''ERP/Edit Paradigm''' in the future, this specific definition will be opened.
* Choose ''ERP/Average'' again. You will see that four conditions are selected for averaging. The newly defined condition is active. If you just want to compare the condition "Resp_Time" with the one that did not have a time limit ("Standard"), select the other two entries (by holding down the "'''CTRL'''" button on the keyboard while selecting) and click the button "'''Remove from List'''" to remove these conditions from the averaging list. Only two conditions are now active for averaging.

=== Top View of Data Segments ===

Any EEG or MEG data segment can be viewed and analyzed in the Top View window. Waveforms are arranged according to their position on the head. The various options include peak finding, analysis and annotation, 3D mapping of amplitude or current source density, overplot of several conditions, and many more.

A detailed description of the features is given in online help chapter “''ERP / Reference / Viewing and Analyzing Data in the Top View”.''

[[Image:ERP Processing (10).png]]

''Topographic view of averaged data in a 32-channel auditory evoked ERP experiment. Two conditions are overplotted. A map of the N100 in one condition is shown. Channel amplitudes at the N100 latency are displayed''

To view a segment or a set of segments in the Top View window, right-click on the segment waveforms and select '''''Top View''''' from the popup menu that appears. The Top Viewer window comes up, displaying the first segment in the data file. To switch to another segment, click on the segment name in the top line; select several segments for overplot by holding down the '''<CTRL>''' key while clicking on the segment names. Note that even if several conditions are shown, only one condition is active for analysis. The active condition is indicated by bold print in the top line, and in the title bar of the window.

'''Measuring peaks and amplitudes'''

'''Note: There are powerful tools for peak and amplitude analysis and export in the Combine Conditions, Channels, Find Peaks Module.'''

'''''Peaks'''''

To measure peaks and peak areas in the Top Viewer, right-click into a waveform between the baseline and the peak, and select the option '''''Find and Mark Peak''''' from the popup menu. If the peak is small, operate on the zoomed waveform: Right-click onto the waveform, select '''''Zoom Waveform''''' from the popup menu and then proceed to mark the peak. The ''Peak Finding'' dialog box appears and shows the result of the peak search:

[[Image:ERP Processing (14).gif ]]

''Result of a peak search in the waveform of electrode T3 of a single epileptic spike. The peak amplitude is -50.7 µV. The peak latency is 5 milliseconds after the mid-latency of the search pattern.''

A peak search can also be initiated from the menu entry '''Analysis / Find Peaks'''. The search channel and time range can then be specified in the top row of the dialog box. Click the '''Find '''button to start the search.

Please refer to the online help'' Reference ''chapter for a detailed description of the peak finding tool.

'''''Waveform amplitudes'''''

To display amplitudes at specific latencies, double-click on a waveform and drag the cursor to the desired latency or use the '''left-right arrow keys''' on the keyboard. The latency is displayed at the bottom of the window, and a 3D map appears in the top right corner. From the '''View '''menu, select the '''''Preferences''''' option. In the dialog box which appears, select the tick marks '''''Show Labels''''' and '''''Show Amplitudes''''':

[[Image:ERP Processing (15).gif ]]

'''Please note:''' Peak latencies and amplitudes can be determined over multiple files in a quick automatized way using scripts. Please refer to Chapter "''Batch Processing'' ''and Combining Conditions / Combine Conditions".''

'''Montages'''

The displayed montage in the Top Viewer can be any arbitrary montage. Peak amplitudes are automatically adapted to the currently applied montage. When the Top Viewer window opens, the montage selected in the BESA Research main window is selected by default. Use the '''Montage '''menu or click on the text at the bottom left to switch to another montage.

'''Advanced viewing options'''

Further options include:

* Moving waveforms in the display, zooming individual channels, hiding channels, zooming the whole display.
* Selecting only a part of the epoch for display.
* 3D whole head mapping of voltage or current source density.
* Changing display options such as tick marks, channel labels, baseline information, font sizes, colors, and more.
* Display of standard deviations, and event-related (de-)synchronization (this requires bandpass filtering of the data during averaging, see the corresponding help chapter).

Please refer to the online help chapter “''ERP / Reference / Viewing and Analyzing Data in the Top View'' for more information.

=== Grand Averaging and Combining Conditions ===

[[Image:ERP Processing (16).gif ]]

The ERP Module allows for a quick combination of averaged segments, e.g. to create Grand Averages over subjects or to compute weighted sums and differences of conditions.

Conditions from different recordings/subjects can be combined in a convenient way using scripts. The menu entry "'''ERP/Combine Conditions, Channels, Find Peaks'''" allows for grand averaging and creating sums and differences between conditions. It also provides a tool for spatial and temporal resampling, and allows to perform an automatic peak analysis of multiple averaged files. For a detailed description of the 'Combine Conditions, Channels, Find Peaks' functions, please refer to the help chapter "'''[[BESA_Research_Batch_Processing#Combine_Conditions.2C_Channels|Batch Processing and Combining Conditions / Combine Conditions]]'''".

[[Image:ERP Processing (17).gif ]]

=== Managing Triggers ===

==== Creating Triggers from EMG/EEG Channels ====

It is possible to create new trigger events from any of the recorded channels. This is achieved by defining parameters that characterize the features of the event. After the parameters are defined, the whole EEG /MEG is searched for events which match the parameters, and new trigger events are created. The steps to be taken are illustrated in the help tutorial chapter [[BESA_Research_ERP_Processing#Tutorial_2:_Creating_Triggers_from_EMG|"''ERP / Functions... / Managing Triggers / Tutorial 2: Creating Triggers from EMG''"]].

Briefly, the procedure to create triggers for a recurring pattern is as follows:

1. Mark a typical occurrence of the pattern by left mouse drag.

2. Use menu item '''ERP / Create Triggers from EMG/EEG''' to open the ''Schmitt Trigger'' dialog box.

3. In the dialog box, select the channel you want to scan for triggers under'' Chan+.'' In most cases, it is advisable to go through section ''Trigger Channel Prefiltering'' and check the tick marks ''Differentiate, Rectify, Smooth After Rect'' and enter a value between 50 Hz and 100 Hz for the smoothing frequency (see figure below).

4. Set the Schmitt Trigger parameters. The Schmitt Trigger is characterized by 4 parameters:

* '''Threshold''' (upper threshold): the threshold that the signal has to exceed
* '''Limit During Dead Time''' (lower threshold): the threshold that the signal must not exceed during the dead time before the trigger
* '''Dead Time (Prior to Trig)''': the time interval before the trigger where the signal must be lower than the lower thresholds
* '''Return Time (Below Limit)''': the time during which the signal has to return below the threshold

Click the button '''View Current Settings'''. In the window that pops up, use the mouse drag to adjust the edges of the yellow block so that the lower threshold is above the pre-trigger baseline, and that the higher threshold stays well under the peak (vertical mouse dragging). Adjust the pre-trigger dead time (length of block left of the red line) which prevents recognizing each threshold crossing in a burst as trigger event, and the return time (horizontal mouse dragging).

5. Click '''OK'''. The parameters are updated in the ''Schmitt Trigger'' dialog box.

6. Click the buttons '''Add to List''' and '''Search Selected''' to start the trigger search.

Triggers can be deleted again by calling the ''Schmitt Trigger'' dialog box again, selecting the corresponding entry in the list box, and clicking the''' Delete Selected '''button. Triggers can also be deleted using the'' Edit'' ''Triggers'' command (see next section).

A complete reference of the features is given in the online help chapter ''"ERP / Reference / Managing Triggers / Creating Triggers''". An advanced topic explains the use of different filter settings using a myoclonic burst as an example (Strategies for Schmitt Trigger definition).

'''Tutorial 2: Creating Triggers from EMG'''

[[Image:ERP Processing (18).gif ]]

''The waveform of a trigger channel can be rectified and filtered to define trigger events. In the example above, the EMG channel FDIL is scanned for myoclonic discharges. The small window shows the waveform of the marked epoch after appropriate filtering.''

==== Editing Triggers ====

Patterns, tags, and markers can be converted into trigger events using the '''''Edit Triggers''''' tool. After conversion, tags found in a pattern search can be used in conditions: they can be analyzed by the paradigm tool which controls and stores the complete pre-averaging process. This facilitates for example the averaging of epileptic spikes which were hand-marked or found by a pattern search (cf. chapter ''"Review / Searching and Averaging"'').

The '''''Edit Triggers''''' tool is also useful to delete triggers which were created earlier, to change trigger codes, or to create triggers for FFT averaging with graphical artifact rejection on the basis of the paradigm tool.

A detailed description of the features is given in the online help chapter ''"ERP / Reference / Managing Triggers / Editing Triggers".''

[[Image:ERP Processing (19).gif ]]

''The'' Edit Triggers ''dialog box is divided into different sections to convert tags to triggers, delete triggers, convert other event types like markers to triggers, and change trigger codes.'' Creating triggers for spectral processing using the artifact scan tool of the ERP paradigm is covered by a different dialog.

''Converting other event types to triggers'': This feature requires BESA Research 7.1 or higher.

==== Event Files ====

BESA Research stores events in a binary event file in the program data base. However, it can be useful to be able to export, edit, or import events. The ERP module allows to export and import event files in ASCII format with the menu commands '''ERP / Save Events As '''and '''ERP / Open Event File'''. These event files can hold all types of events which occur during EEG or MEG recordings, e.g. triggers, comments, epochs, or tags. They can also be edited to change the type, latency, or number of events. For example, trigger events may be read in from an ASCII file, or the frequency of events of a certain type may be analyzed in a statistics software after exporting events.

A detailed description of the features and the format of ASCII event files is given in the online help chapter "''Help / ERP / Reference / Managing Triggers / Working with Event Files''".

==== Tutorial 2: Creating Triggers from EMG ====

In this tutorial, myoclonic activity that was recorded via polygraphic channels is converted into trigger events.

* Open the MEG+EEG file segment "'''myo_sect.foc'''" in the folder "''Examples\EEG -MEG -Myoclonic-Jerks''". We will only inspect EEG channels during this tutorial and select the two relevant EMG channels as additional channels. Press the "'''Scp'''" button to display only EEG channels. Set the time interval to 4s and switch off the high cutoff filter (choose menu entry '''"Filters/High Cutoff Filter / High Cutoff Filter Off"''' or use the ''''HF'''' button). Press the ''''Add' '''button at the top right of the window and select the additional channel montage 'FDI-EMG'. The channels FDIL/FDIR which can be seen at the bottom of the window are the EMG channels recorded from the FDI muscles of the left and right hand.
* By clicking on the scaling button on the bottom right of the screen, adjust the voltage of the additional channels to 20 µV.

Mark a block that encloses a time interval where the feature occurs, e.g. an EMG discharge (jerk) in channel FDIL:

[[Image:ERP Processing (20).gif ]]

* From the '''ERP''' menu, select '''"Create Triggers from EMG/EEG'''". The '''Schmitt Trigger settings''' dialog box appears.
* Press the ''''Load' '''button and open the pre-defined trigger definition ''''EMG-Jerks.smt''''.

[[Image:ERP Processing (21).gif]]

Two definitions for triggers have already been set for comparison. They are listed in the list box at the bottom.

Apart from the definition list, the box comprises three main sections.

* In the section ''"Trigger Channel''s" choose a trigger code which you want to assign to the EMG artifact. As a default setting, the code 403 is suggested. In this example, accepted this default.
* Select the channel that contains the information (FDIL) in the "''Chan. +"'' dropdown list.
* If you want to reference the channel against another channel, choose a reference channel from the "''Chan. –"'' dropdown list. This is not necessary here.
* In the section "''Trigger Channel Prefiltering''" check the respective options if you want the channel pre-filtered according to the current filter settings ("''Initial Filtering"),'' differentiated, rectified, and smoothed with an additional low-pass filter after rectification. Check the options 2, 3, and 4 (all except "Initial Filtering"). The cut-off frequency for the smoothing can be adjusted manually. Try 70 Hz as the smoothing frequency.
* Click the button "'''View Current Settings'''" to view the effect of the current filter settings on the signal in the specified channel. In our example, the result looks like this:

[[Image:ERP Processing (22).gif]]

* The yellow rectangle denotes the parameters which define whether the signal is accepted as a trigger event. Four parameters can be varied:
* The top edge of the rectangle denotes the threshold which must be exceeded by the signal (green line).
* The bottom edge of the rectangle denotes the pre-trigger threshold which must not be exceeded by the signal prior to the trigger event (red line). This ensures that in the case of multiple trigger events, events are excluded which may contain contributions from previous triggers.
* The left edge denotes the "dead time" prior to the trigger event during which no other event is allowed to occur.
* The right edge denotes the "return time" during which the signal must return below the bottom edge. If the event shows a slow decay, it is excluded. This prevents merged multiple events to be included.
* Drag the bottom and the top of the rectangle up with the left mouse button to increase the thresholds. The result can look like this:

[[Image:ERP Processing (23).gif]]

* Clicking the '''OK''' button leads back to the dialog box, where the four parameters (shown in the section "''Trigger Settings''") have now been adjusted. By typing in the values manually, adjust the threshold to 40 µV, the limit during dead time to 25 µV, the dead time to 70 ms, and the return time to 30 ms.
* Click the button "'''Add to List'''" to complete the definition of the trigger event. 
* Click the button "'''Search Selected'''" to search the file for occurrences of the trigger event. After the end of the search, the number of detected trigger events is given in the list box. In this example, 39 trigger events were found.
* Leave the dialog box with "'''OK'''". The current settings are automatically saved in a file with the filename of the data file with the extension "SMT".
* Press the ''''SCP'''' button again and page forward in the file using the space bar. In the screen that appears, mark a relatively small myoclonic signal in the FDIR channel:

[[Image:ERP Processing (24).gif]]

* Choose the menu entry '''Create Triggers from EMG/EEG''' again. The dialog box automatically suggests a new trigger code. Choose the channel "FDIR" in the "Chan.+" combo box. Select the title bar in the list box at the bottom of the dialog box to make sure that no already defined trigger definition is selected. Click the button "'''View Current Settings'''". The thresholds have to be lowered to yield a picture like this (corresponding to upper and lower thresholds of 14.8 µV and 8.5 µV):

[[Image:ERP Processing (25).gif]]

* Click the button "'''Search Selected'''". Since no trigger definition is selected in the list box at the bottom of the dialog box, the settings which you have just entered are copied to the list box, and a search for myoclonic events in the FDIR channel is performed. For the settings quoted above, 17 trigger events are found.

If the file is opened again later and the menu entry '''Create Triggers from EMG/EEG''' is chosen, the settings made earlier are automatically loaded from file. It is also possible to load different files or to save the settings to a different filename using the "'''Load'''" and "'''Save'''" buttons.

'''Note''': If one of the entries in the list box other than the header line is selected, the button "'''View current settings'''" shows the settings of this particular entry. Since it is a fixed definition of a trigger, the thresholds cannot be changed graphically.

For further information about conversion of EMG/EEG artifacts into trigger events, please consult the online help section in the Averaging Module Reference on "''Strategies for Schmitt Trigger Definition''".

[[Category:Research Manual]]

{{BESAManualNav}}

BESA Research ICA

2021-05-05T13:23:31Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 6.1 or higher
}}

== Independent Component Analysis ==

=== ICA Analysis - Main Window ===

ICA analysis allows decomposing EEG/MEG data into independent components. ICA decomposition is performed on the current screen and can be started from the ICA entry in the menu bar or by pressing the ICA button located in the button menu. The amount of data available in the current screen can be manipulated by using the time scaling button in the bottom right corner of the main window. The ICA menu contains the entries '''Current Screen''', '''Select Components''', '''Load Components''', and '''Options'''.


[[Image:ICA_Analysis1a.png|600px]]

Choosing the option '''ICA / Current Screen''' will lead to the computation of an independent component analysis of the data available on the current screen. Filters are taken into account; bad channels are excluded. The amount of data available in the current screen can be changed by using the time scaling button in the bottom right corner of the main window (max. 1200 s).

In case EEG and MEG data are both available, ICA analysis will only run on the data type that is selected by the EEG/MEG button. Running ICA on combined gradiometer/magnetometer data is not possible. It can only run on one channel type at a time.

Before ICA is calculated, the dimensionality of data is optionally reduced by PCA. By default, all PCA components are ignored that explain less than 1% variance. The use of PCA can be switched off or the variance cutoff can be altered by pressing '''ICA / Options'''.

* '''Extended Infomax algorithm''' is based on the maximization of entropy and presents a natural gradient form for the independent components computation.
** Lee TW et al. Independent component analysis using an extended infomax algorithm for mixed sub-Gaussian and super-Gaussian sources. Neural Computation, 11(2), 1999, 409-433
*'''Second-order blind identification (SOBI)''' algorithm relies on second-order statistics that takes advantage of temporal correlations in the source activities.
**Belouchrani A et al. A blind source separation technique using second-order statistics. IEEE Transactions on Signal Processing, 45(2), 1997, 434-444

[[Image:ica2.png|300px]]

While ICA is being computed, the current analysis step is displayed in a dialog box along with the changing weights (see figure below). The first ICA step may take longer for many samples than the subsequent steps. In case the number of steps does not change within one second, one full stop is displayed after the step value, two full stops after 2 seconds, 3 full stops after 3 seconds, none after 4 seconds, 1 full stop after 5 seconds, etc. If ICA weights rise too strongly, ICA decomposition restarts with a smaller learning rate. In this case “Restarting” is displayed in the dialogue box. ICA analysis stops when the change of weights from 1 step to the next is smaller than 1.e-6 or after max. 500 steps. ICA analysis can be stopped by pressing the '''Abort '''button in the dialog box.

[[Image:ica3.png|300px]]

The result of the ICA analysis is displayed like a montage (see figure below). ICA waveforms have the labels ICA1 – ICAx. The menu item '''ICA / Current screen '''is ticked and the ICA button is pressed down. ICA components are sorted in descending order of their explained variance.

The displayed ICA montage is automatically recomputed whenever ICA options change or the data change, e.g. when paging, filtering, changing the time-range to display, etc.

The current ICA decomposition is calculated only taking the data of the current screen into account, but the result is applied on the whole data set. In case the time interval of the data shown on the current screen changes, no automatic recomputation of the ICA decomposition is going to be performed. Instead, an explicit re-calculation is required by clicking the menu item '''ICA / Current screen'''.

Choosing the option '''''Load Components''''', an ASCII file of previously stored or externally calculated ICA topographies can be loaded and displayed. The file must have the format of '''<nowiki>*.ica</nowiki>''' files described further down with the '''''Save Topography''''' option.

[[Image:ica4.png|600px]]

Right-clicking on an ICA label marks the label and opens a pop-up menu with the following options:

[[Image:ica5.png|600px]]

The pop-up menu can also be opened when more than one ICA components are selected (using the '''Ctrl'''-key).

'''Map Topography '''opens the 3D map of the currently selected ICA component (only one component can be selected for this option). The label of the currently selected ICA component is displayed in the bottom left corner of the mapping window. The function ''"Time-Series-Mapping” ''is deactivated when mapping ICA components as the topography does not change over time. Each map is scaled at 120% of its absolute maximum value.

The option '''Define as Artifact Topography''' opens the “''Select Topographies” ''tab of the Artifact Correction Dialog (analogous to pressing ''Artifact / Select''). In this tab, the selected ICA component can be assigned to artifact categories HEOG, VEOG, Blink, EKG, Other1 or Other2. A maximum number of 10 ICA components can be selected at a time when using the artifact categories Other1 and Other2. For the other artifact categories, only 1 ICA component can be selected.  After assigning an ICA topography to an artifact category, the topography map and artifact view are shown. Data are not automatically corrected, as this would prompt a new ICA calculation on artifact-corrected data. If the data contain more than one channel type, artifact correction based on ICA components is only available for the channel type on which the ICA was calculated.

'''Send Topography to Source Analysis''' sends all selected ICA topographies to the Source Analysis module as ICA components. This is only possible if the Source Analysis window is open. Within the Source Analysis window, the ICA components can be displayed by pressing the ICA button. Right-clicking on an ICA label allows adding the ICA component(s) to the solution as spatial topographies.

'''Save Topography''' saves all selected ICA topographies in an ASCII-file. This file can be opened in the Source Analysis window or reloaded with ''Load Components. ''File name and path can be selected in the standard saving dialog. The default name is the basename of the current file with the extension “'''<nowiki>*.ica</nowiki>'''”. If the data contain different channel types, the filename will be “*_'''channeltype.ica'''” (e.g. “*_'''Eeg.ica'''”). The format of '''<nowiki>*.ica</nowiki>''' files is similar to artifact topography files ('''<nowiki>*.atf</nowiki>'''). The first line contains the number of elements (channels) per ICA component (Nchan). The second line contains a list of channel labels and the channel type (Type). The following lines contain the ICA topographies, one topography per line. Each line begins with the corresponding ICA label. Please note that ICA topographies are not average referenced!

<pre>
Nchan= <Number of elements (channels) per ICA topography>

<List of Nchan channel labels> Type= <BSA channel type als integer>

<Label of the first ICA topography, e.g. ICA1> <ICA topography with Nchan elements>

<Label of the second ICA topography, e.g. ICA2> <ICA topography with Nchan elements>

...

<Label of the ith ICA topography, e.g. ICA8> <ICA topography with Nchan elements>
</pre>

'''Export ICA Reconstructed Data Without Selected Components''': Current Screen creates a new dataset '''without '''the selected ICA components and with the current filter settings only of the data shown on the '''current screen'''. This can be done on the basis of spatial components associated with the ICA topographies analogous to calculating model waveforms from source solutions. The ICA-reconstructed file is saved in BESA binary format with the extension “'''<nowiki>*.ica.fsg</nowiki>'''” and contains only those channels for which an ICA was initially computed. If the original data contain more than one channel types, the filename will be labeled according to the channel type used for the reconstruction, e.g. "*_'''Eeg.ica.fsg'''”. ICA-reconstructed data can for example be sent to source analysis to only perform source analysis on specific ICA components of interest.

'''Export ICA Reconstructed Data Without Selected Components''': '''Whole File''' creates a new dataset '''without''' the selected ICA components and with the current filter settings of the '''entire dataset'''.

Operations on the decomposed data can also be performed from the '''ICA Select''' window (menu item '''ICA''' '''/ Select components''' - see figure below). The component name is displayed at the left, the explained variance at the right. When the Extended Infomax algorithm is used, components are sorted by variance. In SOBI algorithm case, the components are sorted by auto-correlation. If the option '''''Map when clicked''''' is checked, the topography of every component is displayed after clicking on it. A component can be selected by double-clicking. It will be marked by an asterisk and it is going to be omitted from the data when exporting with the options '''''Reconstruct: Screen''''' or '''''Reconstruct: Whole File'''''. The button '''Channel Display''' can be used to only show a part of the available ICA components on the screen. Finally, the button '''Save Topographies''' can be used to save the selected topographies (see the menu item '''Save Topography''' from the popup menu above).

[[Image:ica6.png|600px]]

=== ICA Analysis - Source Analysis Window ===

ICA components can be used in the Source Analysis window either by sending ICA topographies directly from the main window or by loading an ICA topography file ('''<nowiki>*.ica</nowiki>''') in the Source Analysis window ('''File /''' '''Load ICA components''').

Please note that ICA decomposition is not computed within the Source Analysis window. The Source Analysis window must be opened before sending ICA topographies. The channel configuration of the ICA components and the data in the Source Analysis window must match. When ICA topographies are available in the Source Analysis window, the ICA/PCA toggle button is set to ICA. A waveform for the data-segment available in the Source Analysis window is reconstructed for each ICA component. The amount of variance each ICA component explains is displayed to the right of the according waveform. Additional ICA components can be appended to the ones already present in the Source Analysis window by pressing '''File / Append ICA components'''. One or more ICA components can be selected by using the''' shift '''or '''ctrl'''-key and left-clicking in the ICA component labels. Right-clicking on one or several selected ICA component labels opens a menu with several ICA-related options (see. fig. 1):

[[Image:ica7.png]]

''Figure 1''

'''Switch off / on ICA component(s)'''

Selected ICA components are ignored in the Source Analysis window. Their labels and waveforms are greyed out. If data are sorted by the channel order, un-selected ICA components are automatically sorted to the bottom of the waveform panel. This can be helpful when many ICA components are sent to or loaded in the Source Analysis window. Un-selected ICA-components can be switched back on.

'''Add selected / all ICA components to solution'''

One spatial component, corresponding to one ICA topography, per selected ICA label is added to the source solution. The absolute position of the displayed dipoles should not be interpreted as an accurate location, as it is located at the center of gravity of the according map. The source waveform associated with the spatial component is displayed in the Source Waveform panel in the middle of the Source Analysis window. Spatial components are the preferable choice for modelling artifact topographies in

a source solution (rather than performing source analysis on artifact-corrected data). Spatial components can also be useful if parts of the signal are to be explained that are not of primary interest to the research question in order to reduce the amount of variance that needs to be explained by discrete source analysis.

[[Category:Research Manual]]

{{BESAManualNav}}

BESA Research Automatic Artifact Correction

2021-05-05T13:21:26Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 6.1 or higher
}}



Automatic correction is the easiest way to obtain artifact-cleared data for review. The estimation of the correction coefficients can be done using the whole EEG or an epoch defined by markers. If only one marker is set, the EEG is scanned from the beginning to the marker, or from the marker to the end, depending on the current position of the display. The longer the range, the more precisely the topography of the artifact can be defined. However, longer ranges increase computation time.

In the Review Window, select the menu entry '''Artifact / Automatic''' to bring up the artifact selection dialog box:

[[Image:Artifact Correction (3).gif]]

By default, EOG correction is computed using an internal model of eye artifact topographies. For automatic EKG correction, an EKG channel has to be defined. If markers are defined (see the figure below), the option ''Between Markers'' is ticked automatically.

Clicking '''OK''' starts the assignment of the artifact topographies, which can be interrupted at any time using the ''''ESC' '''key on the keyboard.


[[Image:Artifact Correction (4) new.png|500px]]

''A block of EEG (the example file '''''Examples\EEG-FOCUS\eeg2.eeg''''') is shown containing eye artifacts. Markers have been placed on either side of the artifacts.''


[[Image:Artifact Correction (5) new.png|500px]]

''Waveform display after automatic artifact correction. Virtual channels which carry the artifact signal are automatically appended at the bottom.''

The corrected waveforms are shown, together with the channels HEOG and VEOG that depict the artifact signals. The oscillatory brain activity is not distorted by artifact correction. Note that correction is applied to scalp channels only. Non-scalp channels, e.g. polygraphic channels, are not corrected and are therefore unaffected by the correction.

[[Image:Artifact Correction (6).gif]]

''Above, a later segment of the EEG is shown, using the TA_Temporal-Lobe source montage, with and without correction. Note that, without artifact correction, the eye movements are depicted on the channels representing the anterior temporal lobe and frontal brain activity. After correction, the artifacts are greatly reduced without distorting the topography of the periodic discharges.''

== Method ==

For automatic correction of eye artifacts, sensor data is transformed back into source space using predefined source montages. The BR29 source montage is combined with the EOG-HVB source montage. This provides the advantage of separating brain activity of interest from artifacts.

[[File:BR29 Source Montage - 3D view.png|640px|BR29 Source Montage]]
 ''BR29 Source Montage''

The BR29 source montage contains 29 (un-oriented) regional sources distributed in the entire brain space.

[[File:EOG-HVB Source Montage - 3D view Sag.png|240px|EOG-HVB Source Montage (Sagittal view)]]
[[File:EOG-HVB Source Montage - 3D view Tra.png|240px|EOG-HVB Source Montage (Transversal view)]]
 ''EOG-HVB Source Montage (Sagittal and transversal view)''

The EOG-HVB source montage contains 3 spatial components to account for eye blinks (B-EOG), as well as vertical (V-EOG) and horizontal eye movements (H-EOG). 
After the transformation, only the temporal activity of the three spatial components for the EOG-HVB source montage is used to compute the topographies for the average reference montage in sensor space. For this, the waveforms of the V-EOG and B-EOG dipoles are combined as one component using the following formula:

:<math display="block">VB – EOG = V – EOG^2 + B – EOG^2</math>

The H-EOG waveform is not modified. The H-EOG and VB-EOG waveforms are then correlated with the original data to detect EOG artifacts. The corresponding amplitude thresholds can be defined in the '''Automatic Artifact Correction''' dialog. In the Review Window, select the menu entry '''Artifact / Automatic''' to bring up the dialog box.

[[File:Artifact Correction (3).gif|320px|Automatic Artifact Correction Dialog]]
 ''Automatic Artifact Correction Dialog''

If the thresholds are exceeded, the current topography will be added to the accumulated topography. Please note that the eye artifact topography will change when scanning for artifacts in the data file and will become more accurate the more eye artifacts are found.

'''References'''

* Ille N., Berg P., and Scherg M. A Spatial Components Method for Continuous Artifact Correction in EEG and MEG. Biomed. Tech., 1997, 42 (suppl. 1): 80-83.
* Ille, N., Berg, P., Scherg, M. Artifact correction of the ongoing EEG using spatial filters based on artifact and brain signal topographies. J. Clin. Neurophysiol. 2002, 19: 113-124.

* Uusitalo, M.A., Ilmoniemi, R.J. Signal-space projection method for separating MEG or EEG into components. Med. Biol. Eng. Comput., 1997, 35: 135-140.

[[Category:Research Manual]]
[[Category:Methods]]
[[Category:Mathematical]]

{{BESAManualNav}}

BESA Research Batch Processing

2021-05-05T13:19:44Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 6.1 or higher
}}



== Combine Conditions and Batch Module: Introduction ==

Functions of this module are started by selecting the menu operations "'''ERP / Combine Conditions...'''" and "'''Process / Batch Scripts...'''".

* '''Combine Condition Scripts''' provides various operations on BESA averages.
* '''Batch Scripts''' provides batch operations on all data files.
* Note that a batch script can also be performed on the current file by selecting "'''Process / Run Batch...'''" or by typing the shortcut key "'''R'''".

== File List Tab ==

Define a list of files on which the operations will be performed. The tab is the same for Combine Conditions Scripts and for Batch Scripts. Combine Conditions Scripts only allows you to open BESA average files (e.g. '''<nowiki>*.fsg</nowiki>''' and '''<nowiki>*.avr</nowiki>''', but also '''.mul''', '''.raw''', '''.swf''', and '''.foc''' if the files have a defined pre-stimulus interval), whereas Batch Scripts allows you to open any data file whose format is known to BESA Research.

When the Combine-Conditions or the Batch module is started, all currently opened (Combine-Conditions: averages only) files are displayed in the list.

To the right of each file name, the number of electrodes, total number of channels, and the sampling rate used in the file are displayed. In the Combine-Conditions module, the number of Epochs (segments) and the number of differently-named conditions are also shown.

'''Add files to the list'''

* Press the '''Add File ''' button.
* Drag one or more files from Windows Explorer onto the window.

'''Remove files from the list'''

* Right click on the file name and confirm the delete operation in the resulting dialog.
* Mark one or more file names in the list (e.g. hold down the''' Ctrl''' key to mark multiple files). Right click to obtain the context menu and select "'''Delete'''", or just press the '''Del '''key.

'''Reorder files within the current file list'''

* Right click on the file name and select "'''''Move Up'''''" or "'''''Move Down'''''".
* Mark one or more file names in the list (e.g. hold down the '''Ctr'''l key to mark multiple files). Right click to obtain the context menu and select "'''''Move Up'''''" or "'''''Move Down'''''", or hold down the''' Ctrl''' key '''and '''press the '''Up''' and '''Down arrows'''.

'''Sort the current file list alphabetically'''

* Click on the File bar above the list

'''Save the current file list'''

* Press the '''Save File List''' button.

'''Load a file list'''

* Press the '''Load File List''' button, or the '''Load Previous''' button to load the most recently used file list.

'''Which conditions are read from a source file? (Combine-Conditions module only)'''

* Normally, all conditions are read from a source file. To exclude one or more segments from operations in the Combine Conditions module, mark the segments as artifacts in the main program display. It is sufficient for the beginning or the end of an artifact interval to be within the segment for the segment to be excluded.

'''File list from Combine Conditions:'''

[[Image:Batch processing (1).png]]

'''Don't try to open here... (Batch only)'''

By default, this checkbox is unchecked.

In the checked state, BESA Research doesn't check if it can open the file. Use this function '''only''' if the file is ASCII and you want to use the '''ImportASCII '''batch command.

'''File List from Batch Scripts''':

[[Image:Batch processing (2).png]]

== Batch Processing ==

=== Batch Processing Scripts ===

With Batch Scripts, you can define a set of operations (e.g. Artifact Scan, Average, etc.) and apply these to several data files.

These operations include

* Load Paradigm
* Artifact Scan
* Average
* Export (and Merge)
* File Open (switch to another data file)
* Set filters
* Specify a montage (used, for example, for export to current montage)
* Run automatic eye and EKG artifact correction
* Define artifact topographies
* Turn artifact correction and view on and off
* Read and write events
* Edit default block epoch (for export around triggers)
* Edit triggers (for export around triggers)
* Mark a block for export, or send the block to Source Analysis or Top View
* Convert patterns to triggers
* Attach auxiliary files (e.g. elp, sfp) to the data file
* Send to MATLAB
* Specify display configurations for the BESA Research Main, SA, and Top View windows
* and more - see the full list of [[#Batch Commands|Batch Commands]]

An additional set of commands are available for operations in the '''Source Analysis Module''', allowing to load, create and fit dipole models, and save the results.

A further set of commands apply to '''Time-Frequency Analysis''', allowing to start TFC, change the display, save results, and run the beamformer or DICS analyses on a selected time-frequency range.

[[Image:Batch commands1.png]]

These operations will be extended in future program releases.

The module includes two tabbed windows:

* '''File List''': Define a list of files on which the operations will be performed.
* '''Batch''': Define or load '''batch commands'''. Run the batch.

=== Batch Tab ===

Load or define batch commands, and then apply them to the files in the File List.

[[Image:Batch processing (4).png]]

'''Add Command'''

* Press '''Add Command''' to add a new command to the batch. The following dialog is opened, showing the available commands:

[[Image:Batch commands1.png]]

* Select the desired command and press '''OK''' or double-click on the command. A dialog box is opened, allowing to specify individual command parameters.
* If you click on "Apply at beginning of batch" or "Apply at end of batch", the command will only be run at the beginning or the end of a batch. You can use this, for example, at the end of a batch to start a MATLAB script to perform statistics on the results of the batch.

'''Load and Save Batch'''

* Press '''Load Batch''' to load a previously defined batch or '''Save Batch''' to save the current batch to a file ('''<nowiki>*.bbat</nowiki>''').

'''Load Previous'''

* Press '''Load Previous''' to load the most recently used batch file. Whenever a batch is run, the current set of commands is written to the file '''Previous.bbat in''' the '''Scripts/Batch''' subdirectory. This file is loaded when you press '''Load Previous'''.

'''Clear All'''

* Clears all commands from the window.

'''View Log File'''

* Each time a batch is run, BESA Research adds information about the batch to a log file, with headings showing the date and time the batch was started. The file is opened automatically in Internet Explorer if errors occurred during processing. Otherwise you may open the file by pressing the '''View Log File''' button here or in the dialog that is displayed at the end of batch processing. 
* The log file is saved in xml format, and a JavaScript is used to format the display in web browsers. JavaScript should be enabled in the browser to obtain an optimal display of the results. If JavaScript is enabled, the log file is displayed as a list of headings for each batch. Click on a heading to display the results of the corresponding batch.
* To open the log file in the Notepad, hold the''' Shift '''key down when pressing the '''View Log File''' button.

'''Batch Command List'''

* Double-click on a command to edit it. See [[#Batch Commands|Batch Commands]] for descriptions of the dialogs that are opened to edit each command.
* Right click on a command to open a context menu allowing more options.

[[Image:Batch processing (5).png]]

* '''Delete''', '''Move Up''', '''and Move Down''' can also be applied to multiple selections.
* If you have made a multiple selection, the '''Del '''button will delete all the marked commands. '''Ctrl '''plus '''Up''' or '''Down''' '''cursor keys''' will move the marked commands up or down.
* '''Toggle Comment''' will add or remove a semicolon (;) in front of the command, to deactivate or reactivate the command.
* '''Toggle Command Only at Start/End''' will add or remove the text "Start_" or "End_" in front of the command. With these prefixes, the command will only be performed when the first file ("Start_") or the last file ("End_") in the file list is being processed.

'''Single Step Mode'''

* Check this item to step through the batch, one command at a time. A dialog is opened after each command, allowing to run the next command, continue the batch without single steps, or stop running the batch. See the'' “Pause''” command for further details.
* During a batch, press and hold down the '''Pause''' or '''Delete''' key to interrupt the batch and enter Single Step Mode. Press and hold down the '''Esc''' key to cancel the batch.

'''Changes in batch written to database'''

* Checked by default. If this item is unchecked, file display settings, such as Montage setting and Artifact correction display, are not written to the database. When the file is next opened in BESA Research, the settings made in the batch are not retained.

'''Leave files in the file list open after running the batch'''

* If this item is checked, files in the file list will remain open after the batch. This is useful, for instance, if you want to open a set of files, specifying the same montage and/or filter settings for each file.

Press '''OK''' to start running the batch. Each command is then applied in succession to each file in the File List.

Note that, while a batch is running press and hold down the''' Pause''' or '''Delete''' key to interrupt the batch and enter Single Step Mode. Press and hold down the '''Esc''' key to cancel the batch.

=== The log file ===

A protocol of each batch is written to the log file '''Scripts/Log/Batch.xml.'''

When you press the '''View Log File '''button, the file is opened in your default browser for xml files. The file will be opened automatically if there was an error during batch processing unless you have used the ''BatchError'' batch command to suppress this behaviour.

'''DHTML formatting of the log file'''

The xml file is formatted using JavaScript (Dynamic HTML). If JavaScript is enabled in your browser, you will first see a list of batch protocol titles, labelled by the date and time at which the batch was started. The most recent batch is at the top of the list.:

[[Image:Batch processing (6).png|200px]]

Click on the title to view the protocol for the corresponding batch:

[[Image:Batch processing (7).png|600px]]

'''JavaScript and XP Service Pack 2'''

By default, if the log file is opened in Internet Explorer after XP Service Pack 2 has been installed, IE will warn you with the message: "''To help protect your security, Internet Explorer has restricted this file from'' ''showing active content that could access your computer".'' All the protocols in the log file are displayed. You may safely click on the options to allow active content in the log file, if you want to display the file as described above.

'''Backup of the log file'''

When the log file is written, a backup of the previous version is written to '''batch.xml.bak'''.

If the size of the log file exceeds 200 KB, it is renamed to '''batch.xml_date_time''' (e.g. '''Batch.xml_2004-10-08_10-53-32'''), and a new version of '''batch.xml''' is created.

=== Placeholders ===

A powerful feature of the batch commands is the ability to define file names and specify standard paths using placeholders. These are text strings enclosed by percentage (%) signs. They can be used in all batch commands where file names are specified.

'''Basename'''

{| class="wikitable"
! Placeholder !! Description !! Example
|-
|style="text-align:center;" width="10%"|'''%basename%'''
|width="40%"|replaced by the basename of the currently opened file.
|width="40%"|If the data file is named "f-spike.fsg", "%basename%-export.fsg" will be interpreted as "f-spike-export.fsg".
|-
|style="text-align:center;"|'''%basename-n%'''
|replaced by the basename of the currently opened file, but removing the last "n" characters from the name.
|If the data file is named "dongle-BB.fsg", "%basename-3%" will be replaced by "dongle", because the last 3 characters of the basename have been removed.
|-
|style="text-align:center;"|'''%-nbasename%'''
|replaced by the basename of the currently opened file, but removing the first "n" characters from the name.
|If the data file is named "BB-dongle.fsg", "%-3basename%" will be replaced by "dongle", because the first 3 characters of the basename have been removed.
|-
|style="text-align:center;"|'''%orgbasename%'''
|replace by basename of the current file in the file list (it has the same meaning as %basename% if no MAINFileOpen batch command was used in command list)
|
|-
|style="text-align:center;"|'''%base%'''
|replace by basename of the current file without the path
|
|-
|style="text-align:center;"|'''%orgbase%'''
|replace by basename of the current file in the file list without the path
|-
|style="text-align:center;"|'''%ext%'''
|replace by extension of the current file
|
|-
|style="text-align:center;"|'''%orgext%'''
|replace by extension of the current file in the file list
|
|-
|style="text-align:center;"|'''%basefolder%'''
|replace by folder of the current file
|
|-
|style="text-align:center;"|'''%orgbasefolder%'''
|replace by folder of the current file in the file list
|
|-
|style="text-align:center;"|'''%t%'''
|Log batch command only: time since start of batch on current file
|
|-
|style="text-align:center;"|'''%T%'''
|Log batch command only: current date and time
|
|-
|style="text-align:center;"|'''%label%'''
|Replace label of the most recent marked block by the block label, not including no. of averages
|
|-
|style="text-align:center;"|'''%LABEL%'''
| Replace label of the most recent marked block by the block label, including no. of averages

|
|-
|style="text-align:center;"|'''%scripts%'''
|replaced by the path to the Scripts folder.
|"%scripts%Batch" is where batches are saved by default; "%scripts%MATLAB" is the location of the standard MATLAB scripts used by BESA Research.
|-
|style="text-align:center;"|'''%montages%'''
|replaced by the path to the Montages folder.
|
|-
|style="text-align:center;"|'''%examples%'''
|replaced by the path to the Examples folder.
|
|}



'''Placeholders for folders'''

The following placeholders are the same as those used in the [Folders] section of '''Besa.ini''':

The strings enclosed by percent signs (%) are placeholders for the following folders in English-language versions of Windows. Folder names are different for the system and for other language settings. BESA Research will substitute the placeholders by the appropriate folder name for the Windows system and the system language:

* '''Windows 10 (English)'''

<div style="margin-left:1.27cm;margin-right:0cm;"> '''%localapp%''' = ""C:\Users[user]\AppData\Local\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Desktop as ""Desktop[user]\AppData\Local\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;"> '''%publicprog%''' = "Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = ""C:\Users\[user]\Documents\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as "Desktop\[User]\Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as''' %progdir%'''</div>

* '''Windows 7 (English):'''

<div style="margin-left:1.27cm;margin-right:0cm;">'''%localapp%''' = "C:\Users\[user]\AppData\Local\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Desktop as "Desktop\[user]\AppData\Local\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%publicprog%''' = "C:\Users\Public\Public Documents\BESA\Research_7_1". This folder is directly accessible from the Windows Explorer under "Libraries\Documents\Public Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = "C:\Users\[user]\Documents\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as ""Libraries\Documents\My Documents\Research_7_1" or "Desktop\[User]\My Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as''' %progdir%  '''</div>

=== Batch Commands ===

Batch commands are selected when the "'''Add Command'''" button is pressed in the "Batch" Tab. The commands are subdivided into five categories: General commands, commands for the Main module, for the Source Analysis module, imaging commands in the Source Analysis module, and commands for Time-Frequency Analysis. The commands have prefixes,''' GEN''', '''MAIN''',''' SA''', '''SAIMAGE''', and''' TFC'''), which identify the category. For compatibility with older program versions, old batches without the prefixes are accepted.

Detailed descriptions of each batch command are available in the electronic help chapter “''Batch Processing and Combining Conditions / Batch Processing / Batch Commands”.''

'''General commands''' - prefixed with "'''GEN'''" (can be used anywhere):

{| cellspacing="8" style
| style="width: 180pt"| GENBatchError || used to change program behavior when errors occur
|-
| GENBatchWindowPosition || set the position of the batch window relative to the main window
|-
| GENComment || comment in the batch script: no batch functionality
|-
| GENMATLABcommand || send a command string to MATLAB
|-
| GENMATLABwaitForVariable || tells BESA to wait until Matlab has created a variable with the specified name.
|-
| GENPause || pause batch operations, allowing step-by-step operations
|-
| GENFor/GENEndFor|| a programming language-like FOR loop
|-
| GENRunProcess || runs a command-line process, e.g. an external program to perform part of the data analysis in the batch
|-
| GENsaveBitmap || save a screenshot of the Source Analysis or the 3D window
|-
| SetVariable || the value of the variable is inserted into subsequent batch commands where the text contains the name flanked by % signs
|-
| GENWindowPosition || set window size and positions to a selection of standard settings, e.g. for bitmap export
|}

'''Commands for the Main Module''' - prefixed with "'''MAIN'''":

{| cellspacing="8"
| style="width: 180pt"| MAINArtifactCorrect || run automatic artifact correction
|-
| MAINArtifactMethod || specify the method for artifact correction
|-
| MAINArtifactOn || turn artifact correction an artifact view on or off
|-
| MAINArtifact Scan || run an artifact scan as from the Paradigm Dialog
|-
| MAINAuxiliaryFiles || associate auxiliary files (e.g. *.''ela'', *.''sfp'') with the data file
|-
| MAINAverage || average the data
|-
| MAINBaseline || specify the parameters for baseline correction
|-
| MAINDefineArtifactTopography || define an artifact topography
|-
| MAINEditDefaultEpoch || edit the default block epoch
|-
| MAINEventRead || read events from an ASCII event file
|-
| MAINEventWrite || write events to an ASCII event file
|-
| MAINExport || export or append data in the selected target format
|-
| MAINExportToBESAConnectivity || export data segments to BESA Connectivity
|-
| MAINFFT || calculates the FFT spectrum of the marked data interval
|-
| MAINFFTmean || starts an averaging procedure that calculates the mean spectral properties in pre-defined regions
|-
| MAINFFTsave || saves FFT data (generated using the ''FFT Average option'' in the ''Average ''command) to disk (*.''fma)''
|-
| MAINFileOpen || close the current file and open a new file to which the remaining batch commands will be applied
|-
| MAINFileClose || close the currently open file in a batch, provided it is not the current file in the File List
|-
| MAINFilter || set filters
|-
| MAINfMRIArtifact || turns on the fMRI artifact removal
|-
| MAINGoTo || jumps with the cursor to the specified time point
|-
| MAINICA || starts ICA decomposition of data on the current screen
|-
| MAINICAsave || saves selected ICA components as topographies in a file
|-
| MAINICAselect || opens component selection dialog for managing ICA components
|-
| MAINImportASCII || import an ASCII file into a ''<nowiki>*.fsg</nowiki>'' file.
|-
| MAINMarkBlock || mark a data block (optionally send to Source Analysis)
|-
| MAINMarkChannels || mark one or more channels, as given by the list
|-
| MAINMaxInInterval || within the current marked block, search for the largest absolute value on the specified channel
|-
| MAINMontage || change the montage (used by the Export command when saving to current montage)
|-
| MAINParadigm || load a paradigm file
|-
| MAINPatternToTrigger || convert a tag into a trigger
|-
| MAINPolygraphicFilters || sets filters for polygraphic or added channels
|-
| MAINScale || set amplitude and time scales
|-
| MAINSearchAverageView || start search average view
|-
| MAINSendToMATLAB || send data to MATLAB
|-
| MAINSplineConstant || set the spline constant used in spherical spline maps and channel interpolation
|-
| MAINTriggerRecode || the command recodes a specified trigger number to a new number
|-
| MAINTriggerSelect || edit the trigger list (cf. ''Edit / Trigger Values''...)
|-
| MAINTriggerTagDelete || delete one or more triggers or tags
|-
| MAINViewAverageBuffer || turn on the Average Buffer View and place the specified buffer number to the left in the display
|-
| MAINViewChannelType || select the channel type to display, and select channel types for mapping, export, etc
|-
| MAINViewSelected || turns selected view on or off
|}

'''General commands for Source Analysis''' - prefixed with "'''SA'''" (but see also ''MarkBlock'', which is used to send a block of data to SA and open the SA window):

{| cellspacing="8"
| style="width: 180pt"| SAAddSource || add a dipole or regional source to a model
|-
| SAChannelTypeForFit || switch between EEG, magnetometers or axial gradiometers, and planar gradiometers
|-
| SAConvertSource || convert a source from dipole to regional source, or from regional source to dipole
|-
| SAcorticalClara || run Cortical CLARA
|-
| SAcorticalLoreta || run Cortical LORETA
|-
| SADelete || delete current solution or all solutions or remove current fit interval or cursor
|-
| SADICS || start DICS computation (if DICS has been precomputed in the time-frequency image command)
|-
| SADisplayMRI || switch MRI display on/off and select small or large window
|-
| SAElectrodeConfiguration || equivalent to pressing the Org or Std button in the Channel box of the Source analysis window
|-
| SAExit || close Source Module
|-
| SAFit || start fit
|-
| SAFitConstraint || set fit constraints, e.g. Residual Variance, Energy, Maximum Distance, Image Weighting, and their weights.
|-
| SAFitInterval || set fit or baseline interval
|-
| SAHeadModel || set the head model
|-
| SALabelSource || set the label of the specified source number
|-
| SAMinimumNorm || run a minimum norm analysis
|-
| SANewSolution || open a new solution
|-
| SAOpenSolution || open a solution from a file
|-
| SAPCA || toggle PCA display of data or residual, and transfer a selected number of components to the source model
|-
| SARegularization || set the regularization values both for discrete and distributed source images
|-
| SASaveBitmap || save a screenshot of the Source Analysis or the 3D window
|-
| SASaveLeadfields || save the leadfields of the current source model
|-
| SASaveModelWaveforms || save model waveforms
|-
| SASaveResidualWaveforms || save residual waveforms
|-
| SASaveRVandGFPWaveforms || save residual variance and global field power waveforms
|-
| SASaveSolution || save the current solution
|-
| SASaveSourceMontage || save a source montage
|-
| SASaveSourceWaveforms || save source waveforms
|-
| SASendToMATLAB || send data, model, source waveforms, images, etc. to Matlab
|-
| SASetCursor || set the cursor
|-
| SASetDefaultSourceType || set the default source type (dipole or regional source)
|-
| SASetOrActivateSource || Turn specified source on or off, or enable/disable source for fitting
|-
| SASetOrientation || set orientation (of regional source)
|-
| SASwitchCondition || switch to a specified condition
|}

'''Commands for Distributed 3D Volume Images'''

{| cellspacing="8"
| style="width: 180pt"| SAIMAGEBeamformer || switch between Single Source and Bilateral Beamformer image
|-
| SAIMAGEBeamformerTimeDomain || start beamformer computation in the time domain
|-
| SAimageBrainAtlas || turns on the Brain Atlas overlay on volumetric image
|-
| SAIMAGECLARA || generate CLARA image
|-
| SAIMAGEClip || clip image values under a threshold
|-
| SAIMAGEExport || save the results of minimum norm or 3D imaging method
|-
| SAIMAGEGotoMax || set the crosshair cursor at the nth maximum in the image
|-
| SAIMAGEImport || load a 3D volume image from file
|-
| SAimageImportFMRI || import fMRI image to Source Analysis Module
|-
| SAIMAGELAURA || create LAURA image
|-
| SAIMAGELORETA || create LORETA image
|-
| SAIMAGESLoreta || create sLORETA image
|-
| SAimageSESAME || start SESAME computation
|-
| SAIMAGESSLOFO || create SSLOFO image
|-
| SAIMAGEUser-Defined || create user-defined image
|-
| SAIMAGESaveLeadfields || save the leadfields of all the voxel sources in a 3D image
|-
| SAIMAGEClip || clip current 3D image
|-
| SAIMAGESmooth || smooth current 3D image
|-
| SAIMAGESetCrosshair || set the position of the crosshair in the 3D image
|}

'''Commands for Time-Frequency Analysis''' ('''TFC''')

{| cellspacing="8"
| style="width: 180pt"| TFCStartTFAnalysis ||(previously TFCgo) start TFC analysis using the current paradigm settings
|-
| TFCdisplay || change the TFC display (e.g. power/amplitude, coherence)
|-
| TFCsave || save numerical results to an ASCII file, or save a screenshot of the TFC window
|-
| TFCimage || start beamformer analysis on a selected time-frequency range
|-
| TFCSendToMATLAB || send TF results or single-trial data to MATLAB
|}

=== How to Average Your Data in a Batch ===

Using batch processing, several files from an experiment can be averaged at a time.

Here we summarize the steps required:

'''Before running the batch'''

* Create the paradigm, and save the paradigm file.
* Open each individual data file to check the data:
** Make sure auxiliary files are defined and loaded properly, and the data are displayed correctly.
** Eyeball the data.
** Define bad (and interpolated) channels.
** Mark artifact time ranges.
** If required, set up artifact correction for the file.
** The data file can be closed again after this step.

'''Preparing the batch'''

* Open at least one file and select ''Process / Batch Scripts''.... The file(s) should be displayed in the file list. Alternatively, just select ''Process / Batch Scripts...,'' and add the files by
** pressing the '''Add File''' button
** dragging the files from Windows Explorer
** Opening a previously saved list with ''Load File List''

* You can delete files from the list (press '''Del''') or edit the file sequence using the right click context menu.
* Select the ''Batch Tab''.
* Add commands to your script. For averaging, these would normally be
** '''Paradigm''' -- to load the paradigm file
** '''Artifact Scan''' -- to run the artifact scan
** '''Average''' -- to perform the average

* Save these commands (press '''Save Batch''').
* Test the commands on the files in the current file list: press '''OK'''
* Look at the log file (press '''View Log File''') to check the results of averaging.
* Look at the data averages to make sure they have been done correctly.
* Repeat these steps until averaging is working properly.

'''Running the batch'''

* Select ''Process / Batch Scripts''....
* Open the files you want to average in the batch in the file list:
** Any files that were open in BESA are included in the list
** Files can be added using the '''Add File''' button
** You may drag one or more files from Windows Explorer to the file list
** Alternatively, load a previously saved file list.

* Edit the file list, e.g. delete unwanted files (use the '''Del''' key or the right click context menu), or reorder the files (use '''Ctrl + cursor keys''' or context menu).
* Note that the order of files in the list specifies the order in which they will be processed in the batch script. This order will be important if all results are saved to the same target file. Otherwise the file sequence is not important.
* Optionally, save the file list (press '''Save Batch'''
* Select the ''Batch Tab'', and load the previously defined batch script with ''Load Batch''.
* Press '''OK''' to run the batch.

=== How to Merge and Compress raw data ===

Using the Export command in a batch, several data files can be merged into a single data file in BESA's data format ('''<nowiki>*.foc</nowiki>''').

This can be useful if data from one subject have been collected in several data blocks, and you want to analyze all data blocks together.

Optionally, to save space, data can be saved in compressed format.

'''Files can be merged:'''

* if they have identical channel configurations, or
* there are at least 16 EEG channels, and the export format is Standard 81 (i.e. EEG channels are interpolated to 81 standard locations).

'''How to merge files:'''

* Select '''Process / Batch Scripts...'''
* Add all the files that are to be merged to the file list:
** Any files that were open in BESA Research are included in the list
** Files can be added using the '''Add File''' button
** You may drag one or more files from Windows Explorer to the file list
** Alternatively, load a previously saved file list (''Load File List'').
* Rearrange the files in the file list to the sequence in which they should be merged.
* Select the ''Batch Tab ''and insert an "''Export"'' command, as described below.

The following dialog shows a possible configuration of the ''Export'' command:

[[Image:Batch processing (4).gif]]

* The parameters shown in the Information box are the settings chosen in the ''Export Dialog'' when the '''Select Options''' button has been pressed.
* '''Append if file already exists''' must be checked in order to merge the files.
* The '''target file name''' must be fixed, i.e. don't use the '''%basename%''' variable, because that will result in a different target file name for each source file.
* There are two variables that can be used for the segment label:
** '''%filename%''' will insert the basename of the source file into the segment label.
** '''%c%''' will insert the file number into the segment label. The number gives the position of the file in the file list. For instance, "File %c%" will generate the label "File 2" for the second file in the list.

=== Example: Data averaging in the auditory intensity experiment ===

In this example, two raw data files, '''s1.cnt''' and '''s2.cnt''', from the auditory intensity experiment will be batch averaged.

Please note that there are further tutorials covering this experiment. The first file is contaminated by many eyeblinks, and more epochs would be averaged if eye correction were used (see Viewlet demonstration on artifact correction on the BESA website). However, in this tutorial we will just use artifact rejection.

'''A. Various ways of creating a File List'''

1. '''Files that were open in BESA Research are automatically added to the File List.''' Start BESA Research and open the files '''s1.cnt '''and '''s2.cnt '''in the directory ''Examples\ERP-Auditory-Intensity''.

2. Select ''Process / Batch Scripts''.... You should see the file names in the '''''File List Tab''''' something like this:

[[Image:Batch processing (5).gif]]

3. You can resort the files in the file list alphabetically by clicking onto the '''''File List column header''''':

[[Image:Batch processing (6).gif]]

Alternatively, you can mark any file, hold down the '''Ctrl '''key and press the '''Up''' or '''Down arrow '''to move the file name up or down the list. This is the sequence in which files will be processed in the batch.

[[Image:Batch processing (7).gif]]

4. Press '''Save File List''' and save the list you have created to '''ERP-Aud-Ex1.flist'''.

5. Highlight both names and press the''' Del '''button to remove them from the list.

6. '''Files can be dragged from Windows Explorer'''. Start Windows Explorer and navigate to the ''ERP-Auditory-Intensity'' subdirectory of your BESA Research examples folder (located in the ''Public Documents'' folder of your computer). Click on '''s1.cnt''' and drag it with the mouse onto the '''''File List Tab'''''. Let go of the mouse. BESA Research opens the file, and displays the name in the File List. Repeat for '''s2.cnt.'''

7. Highlight both names and press the '''Del '''button to remove them from the list.

8. '''Files can be added using the ''Add File'' button'''. Press '''Add File''' and navigate to the ''Examples\ERP-Auditory-Intensity'' subdirectory. Select '''s1.cnt'''. Press '''Ctrl''' and select '''s2.cnt'''. Both names should then be displayed in the ''File Open'' dialog. Press '''OK''' to add the files to the file list.

9. Highlight both names and press the '''Del''' button to remove them from the list.

10. '''Files can be loaded from a previously saved file list'''. Press '''Load File List '''and select '''ERP-Aud-Ex1.flist''', the list you saved in step 6 above.

'''B. Setting up the batch'''

1. We will add three commands, '''Paradigm''', '''Artifact Scan''', and '''Average''', to create a batch that will be applied to the two files in the file list.

2. Click on the '''Batch Tab'''.

[[Image:Batch processing (8).gif]]

3. Press the '''Add Command''' button to obtain the ''Select Command'' window:

[[Image:Batch processing (9).gif]]

4. Click on '''Paradigm''' and then on '''OK''' (alternatively, double-click on '''Paradigm'''). Hit '''Browse''', navigate to the ''Auditory'' folder, and select '''AEP_Intensity.pdg''', the paradigm for the auditory intensity experiment.

[[Image:Batch processing (10).gif]]

5. Press '''OK''' to obtain the ''Load Paradigm Task'' window.

[[Image:Batch processing (11).gif]]

6. Press '''OK''', and the first task in the batch is ready, and listed in the Batch Command window. If you want to modify the command, double-click on it to open the above window, that allows to browse for a different paradigm file.

[[Image:Batch processing (12).gif]]

7. Next, we add the '''Artifact Scan''' command. Click on the '''Add Command''' button, and select ''Artifact Scan.''

[[Image:Batch processing (13).gif]]

8. Press '''OK''' to open the ''Artifact Scan Task'' window. We want to be able to view the results of the scan, and adjust thresholds and bad channels if necessary. Therefore, check the ''Wait after scan'' checkbox.

[[Image:Batch processing (14).gif]]

9. Press '''OK''' to close the ''Artifact Scan Task'' window. Our batch now contains two commands.

[[Image:Batch processing (15).gif]]

10. Finally, we will add an '''Average''' command. Press the '''Add Command''' button and select ''Average''. Press '''OK''' to open the ''Average Task ''window.

[[Image:Batch processing (16).gif]]

11. With the default settings, the average would be saved to the same directory as the data. The file name mask is set by default so that in this example the two averages would be saved to '''s1-av.fsg '''and '''s2-av.fsg'''. We will save the averaged files to subdirectory ''"Averages''" of the data directory. Uncheck the ''Use default target'' check box, change the File name mask to '''%basename%_av-test''' in order not to overwrite the predefined files.

[[Image:Batch processing (17).gif]]

12. Press '''OK '''to close the ''Average Task'' window. Our batch is now complete.

[[Image:Batch processing (18).gif]]

13. We will now save the batch so that it can be used again. Press the '''Save Batch''' button, and save to the file '''ERP-Aud-ex1.bbat'''. Note that an easy way to generate new averaging batches is to load a previously save batch and edit the commands -- it may only be necessary to edit the '''Paradigm''' command to select the relevant paradigm file, and maybe to adjust the target directory in the '''Average''' command.

14. Press '''OK''' in the ''Batch'' Window to start the batch running. As requested, the batch pauses after the artifact scan:.

[[Image:Batch processing (19).gif]]

You may now adjust the number of rejected trials, e.g. by moving the vertical red bar to the left, or exclude bad channels.

15. Press '''OK''' to continue with averaging.

[[Image:Batch processing (20).gif]]

16. Note that, in the background, the ''Batch Running'' window is providing feedback about the current file and current task.

[[Image:Batch processing (6).jpg|400px]]

17. The batch will stop again after the next artifact scan. Press '''OK''' to allow the batch to run to the end.

[[Image:Batch processing (21).gif|400px]]

18. Press '''View Log''' to view the batch protocol. If you are using Internet Explorer or Netscape family (Mozilla, Firefox) browsers, and JavaScript is enabled, you will first see just batch titles defined by the date and time the batch was started. The most recent title is at the top of the list. For other browsers, or if JavaScript was not enabled, all protocol texts are expanded as in 19 (below).

[[Image:Batch processing (22).gif|200px]]

19. Click on the first title to expand its protocol. Here, for example, the protocol gives feedback about the number of epochs that were averaged for each file.

[[Image:Batch processing (23).gif]]

20. Finally, press '''OK''' to return to the main BESA Research display. Open the averages in the ''Averages'' subdirectory to confirm that they were generated properly.

=== Example: Merging files using the Export Command ===

Here we will demonstrate the use of the '''Export '''command to merge two files. We will combine the two averages from the previous example (Data averaging in the auditory intensity experiment) into one target file.

'''A. Generate the file list'''

# Start BESA Research and load the two data files '''S1_av-test.fsg''' and '''S2_av-test.fsg''' that were saved in the previous example.
# Select ''Process / Batch Scripts....''The two file names should be displayed in the file list.
# In the file list, make sure that '''s1_av-test.fsg '''is the first file in the list. If it is not, highlight the file, and move it up using '''Ctrl+up''', or right click and select ''Move Up'' in the context menu.

'''B. Generate the batch'''

1. Press the '''Add Command''' button, and select the '''Export''' command.

2. Press '''OK''' to open the ''Export Task'' window.

[[Image:Batch processing (24).gif]]

3. Press the '''Select Options'''... button to open the ''Export Dialog''.

[[Image:Batch processing (25).gif]]

4. Since we are combining averages, select ''Hires (no compression)'' in the '''Target data format''' drop-down list (If we were merging raw data files, it is better to select compression. Press '''OK '''to close the dialog. Check'' Append if file already exists'', so that the files will be merged. Enter '''s1+s2''' in the target file name mask edit box. This ensures that both files will be saved to the same target: '''S1+S2.fsg'''.

[[Image:Batch processing (26).gif]]

5. Press '''OK '''to close the ''Export Task'' window. The '''Export '''command is displayed.  

[[Image:Batch processing (27).gif]]

6. Optionally, you may save the batch file by pressing '''Save Batch'''.

7. Press '''OK''' to run the batch, and '''OK''' in the ''Batch Completed'' window to return to the BESA main window.

8. Finally, open the file '''S1+S2.fsg''' to confirm that it contains the two merged files.

'''C. Merge raw data'''

# Repeat the above task to merge the two raw data files '''S1.cnt''' and '''S2.cnt''' into a single target file '''S1+S2.foc'''. In this case, select one of the compression options as the target data format. Note that you would not normally want to merge two files from different subjects. However, several data blocks from the same subject can conveniently be merged using this method.

Note that ''<nowiki>*.fsg</nowiki>'' files can also be merged using the ''Combine Conditions'' dialog. 

== Combine Conditions, Channels ==

=== Combine Condition Scripts ===

With the Combine-Conditions module you can do a variety of operations on BESA averages (files with the extension '''<nowiki>*.fsg</nowiki>''', and other segment files, such as '''<nowiki>*.mul</nowiki>''', '''<nowiki>*.avr</nowiki>''', '''<nowiki>*.swf</nowiki>'''):

* Create grand averages
* Combine averages (add, subtract, weighted/unweighted)
* Merge files
* Exclude unwanted averages
* Rename conditions
* Rename or resort channels
* Generate averages or differences over selected channels
* Transform the data: standard interpolated 81 electrodes, change sampling rate, change interval
* Determine peaks, mean amplitudes, or integrals on data averages
* These operations can be performed on one or more files simultaneously. Results of an operation are stored in a single target file.

The module includes four tabbed windows:

* File List: Define a list of files on which the operations will be performed.
* Condition List: List the condition names, define target condition names, and how input conditions are combined into target conditions.
* Channel List: List the channel names, define target channel names, and how input channels are combined into target channels.
* Run Scripts: Define global options for the output (e.g. spatial interpolation, resampling, copy/merge or average, peak analysis). Start the operation.
* Note that in all four tabs, configurations can be saved for future use, and the '''Load Previous''' button restores the most recently used configuration.

=== Condition List Tab ===

List the condition names, define target condition names, and how input conditions are combined into target conditions.

The first column of the list box shows a list of all the condition names found in the source files.

Rows of the list box define the source conditions. Columns define the target conditions.

'''Initial setting'''

When first selecting the tab, each column shows each condition name found in the source files (as in the example below). In the list box, there is a "+1" along the diagonal. The result of this selection is that target conditions will have the same name as source conditions. Right click on source condition labels to view properties (e.g. no. of samples, time range, sampling rate).

[[Image:Batch processing (28).gif]]

'''Editing the condition list'''

* Target condition names can be edited, inserted or deleted by clicking on the label at the top of each column.
* Click on a box within the list to toggle between "+1", "-1" and blank. These correspond to the operations:
** "+1" = add
** "-1" = subtract
** blank = do nothing
* Right click on a box for further operations: conditions can be weighted by a given factor other than 1.

'''Divide result by sum of PLUS factors'''

* Normally, when creating an average over conditions, the sum is divided by the number of conditions, or a weighted average is generated (see below).  If "''Divide the result by the sum of PLUS factors''" is unchecked, the conditions will be summed rather than averaged.
* Note that, when making differences between conditions, no such division is required. BESA Research will uncheck the checkbox automatically if subtraction ("-1") is specified somewhere in the condition list.

'''Weighting of averages'''

* Below the list, click on the ''Weighted Average'' row to toggle "YES" and "NO". "YES" means that averages will be weighted by the number of epochs contributing to the average. For instance, if average A contained 100 epochs and average B contained 200 epochs, the weighted average will be computed as

<div style="margin-left:1cm;margin-right:0cm;">(100 * A +  200 * B) / (100 + 200)</div>

<div style="margin-left:1cm;margin-right:0cm;">Select "NO" for an unweighted average. For the above example, the average is computed as</div>

<div style="margin-left:1cm;margin-right:0cm;">(A + B) / 2</div>

<div style="margin-left:1cm;margin-right:0cm;">Weighted averages are not permitted if one of the boxes contains a negative value.</div>

* Values other than +1 or -1 in the boxes apply a different kind of weighting. For instance, we want to compute the difference between the means of conditions A, B, C and D, E. Use a right-click to specify the fraction 1/3 for each of A, B, and C, and -1/2 for each of D and E (see example below).

[[Image:Batch processing (29).gif]]

'''Save the current condition list'''

* Press the '''Save Condition List''' button.

'''Load a condition list'''

* Press the '''Load Condition List''' button.

'''Load previous settings'''

* Press the '''Load Previous''' button

'''Feedback'''

* Conditions that have different numbers of electrodes (averaging across different files) can only be combined if channels are interpolated to a standard set of electrodes.
* Conditions that have different durations or sampling rates can only be combined if the sampling rate and durations are made the same.
* Feedback about the above situations is displayed by the presence of tick marks above the list box.

=== Channel List Tab ===

List the channel names, define target channel names, and how input channels are combined into target channels.

Note that this tab is very similar in usage to the '''Condition List Tab'''. Note also that some of the functions performed in this tab could also be done in the Montage Editor. It may be a matter of convenience whether you choose to perform these operations here or in the Montage Editor.

The first column of the list box shows a list of all the channel names found in the source files.

Rows of the list box define the ''source'' channel. Columns define the'' target'' channel.

'''Initial setting'''

When first selecting the tab, each column shows each channel name found in the source files (as in the example below). In the list box, there is a "+1" along the diagonal. The result of this selection is that target channel will have the same name as source channel.

'''Combining files'''

If files with different channel configurations are included in the File List, the rows and columns of the Channel List Tab will only contain the labels for the channels that are in common among the files.

If the files in the File List have a different sequence of channels, the sequence of the first file in the list will be adopted in the Channel List.

Thus, for the initial setting, unless the "''Ignore Settings in this Tab''" checkbox is checked, the target grand average or peak/amplitude analysis, etc. will be applied using only channels that are in common among the input files, and using the channel sequence of the first file in the File List. By changing the target channels or by changing the entries in the Channel List, new channels consisting of averages or differences can be generated.

'''What can the Channel List be used for?'''

Some examples:

* Reorder or relabel channels
* Create channel differences
* Create averages over channel groups, e.g. for peak analysis
* Extract a selection of channels for peak analysis or mean amplitudes
* Create grand averages across files with different channel configurations, just using channels in common among the files

[[Image:Batch processing (30).gif]]

'''Editing the channel list'''

* Target channel names can be edited, inserted or deleted by clicking on the label at the top of each column.
* Click on a box within the list to toggle between "+1", "-1" and blank. These correspond to the operations:
** "+1" = add
** "-1" = subtract
** blank = do nothing
* Right click on a box for further operations: channels can be weighted by a given factor other than 1.

'''Divide result by sum of PLUS factors'''

* Normally, when creating an average over channels, the sum is divided by the number of channels, or a weighted average is generated (see below).  If "Divide result by the sum of PLUS factors" is unchecked, the channels will be summed rather than averaged.
* Note that, when making differences between channels, no such division is required. BESA Research will uncheck the checkbox automatically if subtraction ("-1") is specified somewhere in the channel list.

'''Save the current channel list'''

* Press the '''Save Channel List''' button.

'''Load a channel list'''

* Press the '''Load Channel List '''button.

'''Load previous settings'''

* Press the '''Load Previous''' button

=== Run Scripts Tab ===

Define global options for the output (e.g. spatial interpolation, resampling, copy/merge or average, peak detection. Start the operation.

[[Image:Batch processing (7).jpg]]

'''Load or Save Settings'''

* You can save the current settings of this tab to a file (*.run) which can be loaded later.
* When you run the script, the current settings are saved automatically to a file "'''PreviousSettings.run'''".

'''Load Previous'''

* Press this button to load the previous settings (from "'''PreviousSettings.run'''").

'''Averages to Generate'''

* '''Generate separate averages for each source file'''. Averages are performed over conditions within the source file, and are then appended to the target file.
* '''Combine data from source files'''. Conditions are combined over all source files into a single target average.
* '''No averages, just copy'''. Files are copied and merged to the target file. Use this option for renaming conditions, merging files, removing unwanted averages (see below), changing the sampling rate and interval.
* '''Peaks and mean amplitudes'''. Specify time ranges for peaks, mean amplitudes, or integrals (areas).
* Note: When generating or copying averages (first three options), filters and baseline settings are turned off. For Peaks and mean amplitudes, filters and baseline settings are specified in the dialog.

'''Spatial Interpolation'''

* '''Interpolate to Standard 81 electrodes'''. The target file will contain only electrodes (other channels are omitted), using the Standard 81 configuration (as in other export functions within BESA Research). This cannot be selected if the source data contain less than 16 EEG channels.
* '''Interpolate Bad Channels'''. Bad electrode channels in the source file will be interpolated. If the above option is deselected and bad channels exist in one or more of the source files, this option is always on.

BESA Research can interpolate EEG, and MEG if the sensors are axial gradiometers or magnetometers. If other channels are marked as bad in one or more of the source files, these will be defined as bad in the target file. This applies to MEG planar gradiometers, to polygraphic data, and to ICR channels.

'''Temporal Interpolation'''

* '''Spline to New Sampling Rate and Interval'''. Data can be converted to a new sampling rate, and the interval can be changed.
** If the sampling rate is reduced, the data will be low-pass filtered at 1/3 sampling frequency before reduction.
** If the sampling interval is changed, the prestimulus and poststimulus intervals are limited by the smallest intervals in the conditions contributing to the averages. These limits are shown below the edit boxes.

'''Peaks and Mean Amplitudes'''

[[Image:Batch processing (31).gif]]

'''Peaks:'''

* Select the time range between which peaks are to be determined.
* Select the montage on which the peaks are to be determined.
* Define the filter settings.
* Define the baseline settings.
* Specify whether peaks are to be defined at one latency: if so, select the channel on which peaks are to be detected.
* Specify whether you want to find positive or negative peaks.

'''Mean amplitudes and areas:'''

* Select the time range over which the mean amplitudes or areas are to be determined.
* Select the montage on which the mean amplitudes or areas are to be determined.
* Define the filter settings.
* Note that when computing areas, data are first rectified (made positive) and then summed over the time range.

'''Output options of the analysis:'''

* A single ASCII file that contains the result of the analysis for all data sets, conditions, and channels including header and information lines.
* A sparse output suitable for import in SPSS. Each variable (e.g. a latency, a channel amplitude) constitutes one column of the output file.
* Direct transfer to MATLAB into a struct besa_peak. For more information on the data transfer from BESA Research to MATLAB, please refer to help chapter ''“The MATLAB interface”.''

'''Starting the Operation'''

* Press '''OK''' to start the operation. After the operation is completed, and the "Open target file in BESA" box is checked, BESA Research will open the target file.  "Open target file in BESA" cannot be checked if "Peaks and mean amplitudes" was selected - then the result of the operation will be an ASCII file or a MATLAB transfer.
* You will be asked for the name of the target file (unless a MATLAB transfer of peak data has been performed).

'''Restrictions'''

* Depending on source file configurations, not all options above are selectable. For instance, if two files contain different numbers of electrodes, and the "''Ignore Settings in this Tab''" checkbox is checked in the '''''Channel List''''' Tab, spatial interpolation to Standard 81 is enforced in the target. Similarly, if different sampling rates are used in different files, temporal interpolation is enforced.
* You are not allowed to add files to the file list if the channel configuration is different, and the data cannot be combined with Standard 81 interpolation. Since Standard 81 interpolation is only possible for EEG, multiple files without EEG can only be loaded if they have the same number of channels.

=== How to Create Grand Averages ===

* Open the files you want to average in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. To average across different conditions, click in the list boxes to obtain "+1" for each source condition to combine, and rename the target condition to define a meaningful name for the average.
* Click on the '''Run Scripts Tab'''.
* If you have more than one file, specify whether averages should be generated across files ('''Combine data from source files''') or within files ('''Generate separate averages for each source file''').
* Select other options if required (spatial or temporal resampling).
* Press '''OK'''.

=== How to Generate Differences Between Conditions ===

* Open the files you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. To create differences, click in the list boxes to obtain "+1" for one of the source conditions, and "-1" for the source condition to subtract, and rename the target condition to define a meaningful name for the difference.
* Click on the '''Run Scripts Tab'''.
* If you have more than one file, specify whether averages should be generated across files ('''Combine data from source files''') or within files ('''Generate separate averages for each source file''').
* Select other options if required (spatial or temporal resampling).
* Press '''OK'''. An average of the differences is generated. If only one example of each condition exists, e.g. in a grand average file, the result is the difference between conditions.

=== How to Merge Files ===

* Open the files you want to merge in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions''...).
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press '''OK'''.

'''Notes'''

* If the source files have different electrode configurations, use the Standard 81 configuration for the target.
* If the source files have different sampling rates or intervals, use Temporal Interpolation.

=== How to Remove Unwanted Averages ===

'''Removing one or more unwanted segments'''

* Normally, all conditions are read from a source file. To exclude one or more segments from operations in the Combine Conditions module, mark the segments as artifacts in the main program display. It is sufficient for the beginning or the end of an artifact interval to be within the segment for the segment to be excluded.
* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press''' OK'''.
* The target file contains the copied data without the conditions that were marked as averages.

'''Removing one or more unwanted conditions (by label)'''

* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Deselect the target conditions you want to omit (replace the "+1" by a blank).
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press''' OK'''.
* The target file contains the copied data without the conditions that were marked as artifacts.

=== How to Rename Conditions ===

* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions''...).
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. Click on column headings to rename the target conditions.
* Click on the''' Run Scripts Tab'''. Select "''No averages, just copy''".
* Press '''OK'''.
* The target file contains the copied data with the renamed conditions.

=== How to Change the Sampling Rate ===

* Open the file(s) you want to change in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...'').
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Select "''Spline to New Sampling Rate and Interval''" and type the new sampling rate into the edit box.
* Press '''OK'''.

=== Example: Create grand average and combinations of conditions ===

In this example, we will generate a grand average of the results of the Auditory Intensity Experiment. The experiment includes averages from five different stimulus intensities. We will create a grand average over each intensity, but also include means over the two lowest and the two highest intensities, and the difference between these two combinations.

'''A. File selection'''

# Start BESA Research and open files '''S1_av.fsg - S10_av.fsg''' in the ''Examples\ERP-Auditory-Intensity'' folder. The files contain the individual averaged data of the 10 subjects who participated in this study.
# Select ''ERP / Combine Conditions...'' The file list should display the two files, with feedback about the number of averages and conditions. 8 epochs are found. See the ''“Data averaging in the auditory intensity'' ''experiment”'' example for examples how to manipulate the file list.

[[Image:Batch processing (32).gif]]

'''B. Define conditions'''

1. Click on the '''Condition List Tab'''. The initial window defines target conditions with the same name as the source conditions. To generate the grand average over these conditions we could proceed without further changes to the '''Run Scripts Tab'''. However, we want to modify the condition list and create a condition that contains the grand averaged difference between the''' High''' and '''Low''' conditions.

[[Image:Batch processing (8).jpg]]

2. Click on the '''All '''column label. In the resulting window, rename condition '''All''' to''' Difference'''. Then press '''OK'''.

[[Image:Batch processing (33).gif]]

3. The last column is now labeled '''Difference.''' Left-click twice onto the ‘'''+1’''' entry that links this condition to the '''All '''input condition. This will remove the link and leave the field blank. To define the ‘Difference’ condition as the average of ‘High’ minus ‘Low’ over subjects, left-click once into the field linking input '''High''' with target '''Difference''' to generate an entry ‘'''+1’''' in this field. Left-click twice into the field linking input '''Low '''with target '''Difference''' to generate an entry '-'''1'''’.

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;">[[Image:Batch processing (35).gif]]</div>

4. Press '''Save Condition List''' and save the list to '''ERP-aud-ex1.clist'''. This condition combination can thus be loaded later using the '''Load Condition List''' button.

'''C. Run the script'''

# Click on the '''Run Script Tab'''.
# The default tab settings are ready for generating the grand average ('''Combine data from source file''' and '''Open target file in BESA''' should be checked). Just press '''OK'''. Enter '''All_Subjects_cc-test.fsg''' as file name and press''' Save'''.

The resulting file contains the 8 target conditions, 60db, 70dB, 80dB, 90dB, 100dB, Low, High, and Difference.

=== Example: Average files from different experiments ===

This example is intended to illustrate several features of the ''Combine Conditions'' Dialog, such as electrode interpolation and resampling. We will combine an average from the Auditory Intensity experiment with one from the P300 auditory experiment. In this particular case, it is not a very meaningful thing to do, but it shows what is possible. For instance, the same experiment may have been performed using different sampling rates or electrode combinations. This example shows how such data may be combined.

'''A. File selection'''

# Start BESA Research and open the file '''All_Subjects_GA.fsg''' in the ''Examples\ERP-Auditory-Intensity'' folder. The file contains the grand average data from the auditory intensity experiment.
# Open the file '''RareFrequentResponseLeft.fsg''' in the ''Examples\ERP-P300-Auditory'' folder. This file contains averages from the P300 auditory experiment.
# Select ''ERP / Combine Conditions... ''Note that the files have different sampling rates and different numbers of electrodes.

[[Image:Batch processing (36).gif]]

'''B. Define conditions'''

1. Click on the '''Condition List Tab'''. Note that the feedback text at the bottom of the window displays the text "Standard 81 interpolation required to generate average; Across files: resampling or change in time range required to generate average". The condition labels show all the names from both files.

[[Image:Batch processing (37).gif]]

2. We will exclude most conditions, and just combine the most similar conditions from the two experiments: the "Standard" and the "80dB" conditions. Click on the title of the first column,''' Blink'''. Select “''Delete all conditions to the right of this column”'', and press '''OK'''.

[[Image:Batch processing (38).gif]]

3. Click on the title again, and rename the target condition to "Standard".

[[Image:Batch processing (39).gif]]

4. Click twice in the first line to remove the "+1" entry there. Click once in the third row ("Frequent"), and in the 7th row ("80dB"), to display "+1" at each entry. Thus, just two of the conditions will be combined into one target condition.

[[Image:Batch processing (40).gif]]

'''C. Run the script'''

1. Click on the '''Run Script Tab'''.

[[Image:Batch processing (41).gif]]

2. Note that '''Interpolate to Standard 81 electrodes''' is checked and grayed: since two different electrode sets are to be combined, we can only do this by interpolating electrodes. Also, both '''Spline to new sampling rate''' and '''Clip interval '''are checked and grayed. Again, these settings are required in order to be able to average the two data files together. The sampling rate is set to the higher of the two selections. The time range is set to the largest possible range that can be clipped from the two data sets. For now, leave these settings as they are, and press '''OK'''. Save the target to '''TestCombineExpts_CC-std81.fsg'''.

{{BESAManualNav}}

BESA Research Batch Processing

2021-05-05T13:19:05Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = BESA Research 6.0 or higher
}}



== Combine Conditions and Batch Module: Introduction ==

Functions of this module are started by selecting the menu operations "'''ERP / Combine Conditions...'''" and "'''Process / Batch Scripts...'''".

* '''Combine Condition Scripts''' provides various operations on BESA averages.
* '''Batch Scripts''' provides batch operations on all data files.
* Note that a batch script can also be performed on the current file by selecting "'''Process / Run Batch...'''" or by typing the shortcut key "'''R'''".

== File List Tab ==

Define a list of files on which the operations will be performed. The tab is the same for Combine Conditions Scripts and for Batch Scripts. Combine Conditions Scripts only allows you to open BESA average files (e.g. '''<nowiki>*.fsg</nowiki>''' and '''<nowiki>*.avr</nowiki>''', but also '''.mul''', '''.raw''', '''.swf''', and '''.foc''' if the files have a defined pre-stimulus interval), whereas Batch Scripts allows you to open any data file whose format is known to BESA Research.

When the Combine-Conditions or the Batch module is started, all currently opened (Combine-Conditions: averages only) files are displayed in the list.

To the right of each file name, the number of electrodes, total number of channels, and the sampling rate used in the file are displayed. In the Combine-Conditions module, the number of Epochs (segments) and the number of differently-named conditions are also shown.

'''Add files to the list'''

* Press the '''Add File ''' button.
* Drag one or more files from Windows Explorer onto the window.

'''Remove files from the list'''

* Right click on the file name and confirm the delete operation in the resulting dialog.
* Mark one or more file names in the list (e.g. hold down the''' Ctrl''' key to mark multiple files). Right click to obtain the context menu and select "'''Delete'''", or just press the '''Del '''key.

'''Reorder files within the current file list'''

* Right click on the file name and select "'''''Move Up'''''" or "'''''Move Down'''''".
* Mark one or more file names in the list (e.g. hold down the '''Ctr'''l key to mark multiple files). Right click to obtain the context menu and select "'''''Move Up'''''" or "'''''Move Down'''''", or hold down the''' Ctrl''' key '''and '''press the '''Up''' and '''Down arrows'''.

'''Sort the current file list alphabetically'''

* Click on the File bar above the list

'''Save the current file list'''

* Press the '''Save File List''' button.

'''Load a file list'''

* Press the '''Load File List''' button, or the '''Load Previous''' button to load the most recently used file list.

'''Which conditions are read from a source file? (Combine-Conditions module only)'''

* Normally, all conditions are read from a source file. To exclude one or more segments from operations in the Combine Conditions module, mark the segments as artifacts in the main program display. It is sufficient for the beginning or the end of an artifact interval to be within the segment for the segment to be excluded.

'''File list from Combine Conditions:'''

[[Image:Batch processing (1).png]]

'''Don't try to open here... (Batch only)'''

By default, this checkbox is unchecked.

In the checked state, BESA Research doesn't check if it can open the file. Use this function '''only''' if the file is ASCII and you want to use the '''ImportASCII '''batch command.

'''File List from Batch Scripts''':

[[Image:Batch processing (2).png]]

== Batch Processing ==

=== Batch Processing Scripts ===

With Batch Scripts, you can define a set of operations (e.g. Artifact Scan, Average, etc.) and apply these to several data files.

These operations include

* Load Paradigm
* Artifact Scan
* Average
* Export (and Merge)
* File Open (switch to another data file)
* Set filters
* Specify a montage (used, for example, for export to current montage)
* Run automatic eye and EKG artifact correction
* Define artifact topographies
* Turn artifact correction and view on and off
* Read and write events
* Edit default block epoch (for export around triggers)
* Edit triggers (for export around triggers)
* Mark a block for export, or send the block to Source Analysis or Top View
* Convert patterns to triggers
* Attach auxiliary files (e.g. elp, sfp) to the data file
* Send to MATLAB
* Specify display configurations for the BESA Research Main, SA, and Top View windows
* and more - see the full list of [[#Batch Commands|Batch Commands]]

An additional set of commands are available for operations in the '''Source Analysis Module''', allowing to load, create and fit dipole models, and save the results.

A further set of commands apply to '''Time-Frequency Analysis''', allowing to start TFC, change the display, save results, and run the beamformer or DICS analyses on a selected time-frequency range.

[[Image:Batch commands1.png]]

These operations will be extended in future program releases.

The module includes two tabbed windows:

* '''File List''': Define a list of files on which the operations will be performed.
* '''Batch''': Define or load '''batch commands'''. Run the batch.

=== Batch Tab ===

Load or define batch commands, and then apply them to the files in the File List.

[[Image:Batch processing (4).png]]

'''Add Command'''

* Press '''Add Command''' to add a new command to the batch. The following dialog is opened, showing the available commands:

[[Image:Batch commands1.png]]

* Select the desired command and press '''OK''' or double-click on the command. A dialog box is opened, allowing to specify individual command parameters.
* If you click on "Apply at beginning of batch" or "Apply at end of batch", the command will only be run at the beginning or the end of a batch. You can use this, for example, at the end of a batch to start a MATLAB script to perform statistics on the results of the batch.

'''Load and Save Batch'''

* Press '''Load Batch''' to load a previously defined batch or '''Save Batch''' to save the current batch to a file ('''<nowiki>*.bbat</nowiki>''').

'''Load Previous'''

* Press '''Load Previous''' to load the most recently used batch file. Whenever a batch is run, the current set of commands is written to the file '''Previous.bbat in''' the '''Scripts/Batch''' subdirectory. This file is loaded when you press '''Load Previous'''.

'''Clear All'''

* Clears all commands from the window.

'''View Log File'''

* Each time a batch is run, BESA Research adds information about the batch to a log file, with headings showing the date and time the batch was started. The file is opened automatically in Internet Explorer if errors occurred during processing. Otherwise you may open the file by pressing the '''View Log File''' button here or in the dialog that is displayed at the end of batch processing. 
* The log file is saved in xml format, and a JavaScript is used to format the display in web browsers. JavaScript should be enabled in the browser to obtain an optimal display of the results. If JavaScript is enabled, the log file is displayed as a list of headings for each batch. Click on a heading to display the results of the corresponding batch.
* To open the log file in the Notepad, hold the''' Shift '''key down when pressing the '''View Log File''' button.

'''Batch Command List'''

* Double-click on a command to edit it. See [[#Batch Commands|Batch Commands]] for descriptions of the dialogs that are opened to edit each command.
* Right click on a command to open a context menu allowing more options.

[[Image:Batch processing (5).png]]

* '''Delete''', '''Move Up''', '''and Move Down''' can also be applied to multiple selections.
* If you have made a multiple selection, the '''Del '''button will delete all the marked commands. '''Ctrl '''plus '''Up''' or '''Down''' '''cursor keys''' will move the marked commands up or down.
* '''Toggle Comment''' will add or remove a semicolon (;) in front of the command, to deactivate or reactivate the command.
* '''Toggle Command Only at Start/End''' will add or remove the text "Start_" or "End_" in front of the command. With these prefixes, the command will only be performed when the first file ("Start_") or the last file ("End_") in the file list is being processed.

'''Single Step Mode'''

* Check this item to step through the batch, one command at a time. A dialog is opened after each command, allowing to run the next command, continue the batch without single steps, or stop running the batch. See the'' “Pause''” command for further details.
* During a batch, press and hold down the '''Pause''' or '''Delete''' key to interrupt the batch and enter Single Step Mode. Press and hold down the '''Esc''' key to cancel the batch.

'''Changes in batch written to database'''

* Checked by default. If this item is unchecked, file display settings, such as Montage setting and Artifact correction display, are not written to the database. When the file is next opened in BESA Research, the settings made in the batch are not retained.

'''Leave files in the file list open after running the batch'''

* If this item is checked, files in the file list will remain open after the batch. This is useful, for instance, if you want to open a set of files, specifying the same montage and/or filter settings for each file.

Press '''OK''' to start running the batch. Each command is then applied in succession to each file in the File List.

Note that, while a batch is running press and hold down the''' Pause''' or '''Delete''' key to interrupt the batch and enter Single Step Mode. Press and hold down the '''Esc''' key to cancel the batch.

=== The log file ===

A protocol of each batch is written to the log file '''Scripts/Log/Batch.xml.'''

When you press the '''View Log File '''button, the file is opened in your default browser for xml files. The file will be opened automatically if there was an error during batch processing unless you have used the ''BatchError'' batch command to suppress this behaviour.

'''DHTML formatting of the log file'''

The xml file is formatted using JavaScript (Dynamic HTML). If JavaScript is enabled in your browser, you will first see a list of batch protocol titles, labelled by the date and time at which the batch was started. The most recent batch is at the top of the list.:

[[Image:Batch processing (6).png|200px]]

Click on the title to view the protocol for the corresponding batch:

[[Image:Batch processing (7).png|600px]]

'''JavaScript and XP Service Pack 2'''

By default, if the log file is opened in Internet Explorer after XP Service Pack 2 has been installed, IE will warn you with the message: "''To help protect your security, Internet Explorer has restricted this file from'' ''showing active content that could access your computer".'' All the protocols in the log file are displayed. You may safely click on the options to allow active content in the log file, if you want to display the file as described above.

'''Backup of the log file'''

When the log file is written, a backup of the previous version is written to '''batch.xml.bak'''.

If the size of the log file exceeds 200 KB, it is renamed to '''batch.xml_date_time''' (e.g. '''Batch.xml_2004-10-08_10-53-32'''), and a new version of '''batch.xml''' is created.

=== Placeholders ===

A powerful feature of the batch commands is the ability to define file names and specify standard paths using placeholders. These are text strings enclosed by percentage (%) signs. They can be used in all batch commands where file names are specified.

'''Basename'''

{| class="wikitable"
! Placeholder !! Description !! Example
|-
|style="text-align:center;" width="10%"|'''%basename%'''
|width="40%"|replaced by the basename of the currently opened file.
|width="40%"|If the data file is named "f-spike.fsg", "%basename%-export.fsg" will be interpreted as "f-spike-export.fsg".
|-
|style="text-align:center;"|'''%basename-n%'''
|replaced by the basename of the currently opened file, but removing the last "n" characters from the name.
|If the data file is named "dongle-BB.fsg", "%basename-3%" will be replaced by "dongle", because the last 3 characters of the basename have been removed.
|-
|style="text-align:center;"|'''%-nbasename%'''
|replaced by the basename of the currently opened file, but removing the first "n" characters from the name.
|If the data file is named "BB-dongle.fsg", "%-3basename%" will be replaced by "dongle", because the first 3 characters of the basename have been removed.
|-
|style="text-align:center;"|'''%orgbasename%'''
|replace by basename of the current file in the file list (it has the same meaning as %basename% if no MAINFileOpen batch command was used in command list)
|
|-
|style="text-align:center;"|'''%base%'''
|replace by basename of the current file without the path
|
|-
|style="text-align:center;"|'''%orgbase%'''
|replace by basename of the current file in the file list without the path
|-
|style="text-align:center;"|'''%ext%'''
|replace by extension of the current file
|
|-
|style="text-align:center;"|'''%orgext%'''
|replace by extension of the current file in the file list
|
|-
|style="text-align:center;"|'''%basefolder%'''
|replace by folder of the current file
|
|-
|style="text-align:center;"|'''%orgbasefolder%'''
|replace by folder of the current file in the file list
|
|-
|style="text-align:center;"|'''%t%'''
|Log batch command only: time since start of batch on current file
|
|-
|style="text-align:center;"|'''%T%'''
|Log batch command only: current date and time
|
|-
|style="text-align:center;"|'''%label%'''
|Replace label of the most recent marked block by the block label, not including no. of averages
|
|-
|style="text-align:center;"|'''%LABEL%'''
| Replace label of the most recent marked block by the block label, including no. of averages

|
|-
|style="text-align:center;"|'''%scripts%'''
|replaced by the path to the Scripts folder.
|"%scripts%Batch" is where batches are saved by default; "%scripts%MATLAB" is the location of the standard MATLAB scripts used by BESA Research.
|-
|style="text-align:center;"|'''%montages%'''
|replaced by the path to the Montages folder.
|
|-
|style="text-align:center;"|'''%examples%'''
|replaced by the path to the Examples folder.
|
|}



'''Placeholders for folders'''

The following placeholders are the same as those used in the [Folders] section of '''Besa.ini''':

The strings enclosed by percent signs (%) are placeholders for the following folders in English-language versions of Windows. Folder names are different for the system and for other language settings. BESA Research will substitute the placeholders by the appropriate folder name for the Windows system and the system language:

* '''Windows 10 (English)'''

<div style="margin-left:1.27cm;margin-right:0cm;"> '''%localapp%''' = ""C:\Users[user]\AppData\Local\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Desktop as ""Desktop[user]\AppData\Local\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;"> '''%publicprog%''' = "Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = ""C:\Users\[user]\Documents\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as "Desktop\[User]\Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as''' %progdir%'''</div>

* '''Windows 7 (English):'''

<div style="margin-left:1.27cm;margin-right:0cm;">'''%localapp%''' = "C:\Users\[user]\AppData\Local\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Desktop as "Desktop\[user]\AppData\Local\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%publicprog%''' = "C:\Users\Public\Public Documents\BESA\Research_7_1". This folder is directly accessible from the Windows Explorer under "Libraries\Documents\Public Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = "C:\Users\[user]\Documents\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as ""Libraries\Documents\My Documents\Research_7_1" or "Desktop\[User]\My Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as''' %progdir%  '''</div>

=== Batch Commands ===

Batch commands are selected when the "'''Add Command'''" button is pressed in the "Batch" Tab. The commands are subdivided into five categories: General commands, commands for the Main module, for the Source Analysis module, imaging commands in the Source Analysis module, and commands for Time-Frequency Analysis. The commands have prefixes,''' GEN''', '''MAIN''',''' SA''', '''SAIMAGE''', and''' TFC'''), which identify the category. For compatibility with older program versions, old batches without the prefixes are accepted.

Detailed descriptions of each batch command are available in the electronic help chapter “''Batch Processing and Combining Conditions / Batch Processing / Batch Commands”.''

'''General commands''' - prefixed with "'''GEN'''" (can be used anywhere):

{| cellspacing="8" style
| style="width: 180pt"| GENBatchError || used to change program behavior when errors occur
|-
| GENBatchWindowPosition || set the position of the batch window relative to the main window
|-
| GENComment || comment in the batch script: no batch functionality
|-
| GENMATLABcommand || send a command string to MATLAB
|-
| GENMATLABwaitForVariable || tells BESA to wait until Matlab has created a variable with the specified name.
|-
| GENPause || pause batch operations, allowing step-by-step operations
|-
| GENFor/GENEndFor|| a programming language-like FOR loop
|-
| GENRunProcess || runs a command-line process, e.g. an external program to perform part of the data analysis in the batch
|-
| GENsaveBitmap || save a screenshot of the Source Analysis or the 3D window
|-
| SetVariable || the value of the variable is inserted into subsequent batch commands where the text contains the name flanked by % signs
|-
| GENWindowPosition || set window size and positions to a selection of standard settings, e.g. for bitmap export
|}

'''Commands for the Main Module''' - prefixed with "'''MAIN'''":

{| cellspacing="8"
| style="width: 180pt"| MAINArtifactCorrect || run automatic artifact correction
|-
| MAINArtifactMethod || specify the method for artifact correction
|-
| MAINArtifactOn || turn artifact correction an artifact view on or off
|-
| MAINArtifact Scan || run an artifact scan as from the Paradigm Dialog
|-
| MAINAuxiliaryFiles || associate auxiliary files (e.g. *.''ela'', *.''sfp'') with the data file
|-
| MAINAverage || average the data
|-
| MAINBaseline || specify the parameters for baseline correction
|-
| MAINDefineArtifactTopography || define an artifact topography
|-
| MAINEditDefaultEpoch || edit the default block epoch
|-
| MAINEventRead || read events from an ASCII event file
|-
| MAINEventWrite || write events to an ASCII event file
|-
| MAINExport || export or append data in the selected target format
|-
| MAINExportToBESAConnectivity || export data segments to BESA Connectivity
|-
| MAINFFT || calculates the FFT spectrum of the marked data interval
|-
| MAINFFTmean || starts an averaging procedure that calculates the mean spectral properties in pre-defined regions
|-
| MAINFFTsave || saves FFT data (generated using the ''FFT Average option'' in the ''Average ''command) to disk (*.''fma)''
|-
| MAINFileOpen || close the current file and open a new file to which the remaining batch commands will be applied
|-
| MAINFileClose || close the currently open file in a batch, provided it is not the current file in the File List
|-
| MAINFilter || set filters
|-
| MAINfMRIArtifact || turns on the fMRI artifact removal
|-
| MAINGoTo || jumps with the cursor to the specified time point
|-
| MAINICA || starts ICA decomposition of data on the current screen
|-
| MAINICAsave || saves selected ICA components as topographies in a file
|-
| MAINICAselect || opens component selection dialog for managing ICA components
|-
| MAINImportASCII || import an ASCII file into a ''<nowiki>*.fsg</nowiki>'' file.
|-
| MAINMarkBlock || mark a data block (optionally send to Source Analysis)
|-
| MAINMarkChannels || mark one or more channels, as given by the list
|-
| MAINMaxInInterval || within the current marked block, search for the largest absolute value on the specified channel
|-
| MAINMontage || change the montage (used by the Export command when saving to current montage)
|-
| MAINParadigm || load a paradigm file
|-
| MAINPatternToTrigger || convert a tag into a trigger
|-
| MAINPolygraphicFilters || sets filters for polygraphic or added channels
|-
| MAINScale || set amplitude and time scales
|-
| MAINSearchAverageView || start search average view
|-
| MAINSendToMATLAB || send data to MATLAB
|-
| MAINSplineConstant || set the spline constant used in spherical spline maps and channel interpolation
|-
| MAINTriggerRecode || the command recodes a specified trigger number to a new number
|-
| MAINTriggerSelect || edit the trigger list (cf. ''Edit / Trigger Values''...)
|-
| MAINTriggerTagDelete || delete one or more triggers or tags
|-
| MAINViewAverageBuffer || turn on the Average Buffer View and place the specified buffer number to the left in the display
|-
| MAINViewChannelType || select the channel type to display, and select channel types for mapping, export, etc
|-
| MAINViewSelected || turns selected view on or off
|}

'''General commands for Source Analysis''' - prefixed with "'''SA'''" (but see also ''MarkBlock'', which is used to send a block of data to SA and open the SA window):

{| cellspacing="8"
| style="width: 180pt"| SAAddSource || add a dipole or regional source to a model
|-
| SAChannelTypeForFit || switch between EEG, magnetometers or axial gradiometers, and planar gradiometers
|-
| SAConvertSource || convert a source from dipole to regional source, or from regional source to dipole
|-
| SAcorticalClara || run Cortical CLARA
|-
| SAcorticalLoreta || run Cortical LORETA
|-
| SADelete || delete current solution or all solutions or remove current fit interval or cursor
|-
| SADICS || start DICS computation (if DICS has been precomputed in the time-frequency image command)
|-
| SADisplayMRI || switch MRI display on/off and select small or large window
|-
| SAElectrodeConfiguration || equivalent to pressing the Org or Std button in the Channel box of the Source analysis window
|-
| SAExit || close Source Module
|-
| SAFit || start fit
|-
| SAFitConstraint || set fit constraints, e.g. Residual Variance, Energy, Maximum Distance, Image Weighting, and their weights.
|-
| SAFitInterval || set fit or baseline interval
|-
| SAHeadModel || set the head model
|-
| SALabelSource || set the label of the specified source number
|-
| SAMinimumNorm || run a minimum norm analysis
|-
| SANewSolution || open a new solution
|-
| SAOpenSolution || open a solution from a file
|-
| SAPCA || toggle PCA display of data or residual, and transfer a selected number of components to the source model
|-
| SARegularization || set the regularization values both for discrete and distributed source images
|-
| SASaveBitmap || save a screenshot of the Source Analysis or the 3D window
|-
| SASaveLeadfields || save the leadfields of the current source model
|-
| SASaveModelWaveforms || save model waveforms
|-
| SASaveResidualWaveforms || save residual waveforms
|-
| SASaveRVandGFPWaveforms || save residual variance and global field power waveforms
|-
| SASaveSolution || save the current solution
|-
| SASaveSourceMontage || save a source montage
|-
| SASaveSourceWaveforms || save source waveforms
|-
| SASendToMATLAB || send data, model, source waveforms, images, etc. to Matlab
|-
| SASetCursor || set the cursor
|-
| SASetDefaultSourceType || set the default source type (dipole or regional source)
|-
| SASetOrActivateSource || Turn specified source on or off, or enable/disable source for fitting
|-
| SASetOrientation || set orientation (of regional source)
|-
| SASwitchCondition || switch to a specified condition
|}

'''Commands for Distributed 3D Volume Images'''

{| cellspacing="8"
| style="width: 180pt"| SAIMAGEBeamformer || switch between Single Source and Bilateral Beamformer image
|-
| SAIMAGEBeamformerTimeDomain || start beamformer computation in the time domain
|-
| SAimageBrainAtlas || turns on the Brain Atlas overlay on volumetric image
|-
| SAIMAGECLARA || generate CLARA image
|-
| SAIMAGEClip || clip image values under a threshold
|-
| SAIMAGEExport || save the results of minimum norm or 3D imaging method
|-
| SAIMAGEGotoMax || set the crosshair cursor at the nth maximum in the image
|-
| SAIMAGEImport || load a 3D volume image from file
|-
| SAimageImportFMRI || import fMRI image to Source Analysis Module
|-
| SAIMAGELAURA || create LAURA image
|-
| SAIMAGELORETA || create LORETA image
|-
| SAIMAGESLoreta || create sLORETA image
|-
| SAimageSESAME || start SESAME computation
|-
| SAIMAGESSLOFO || create SSLOFO image
|-
| SAIMAGEUser-Defined || create user-defined image
|-
| SAIMAGESaveLeadfields || save the leadfields of all the voxel sources in a 3D image
|-
| SAIMAGEClip || clip current 3D image
|-
| SAIMAGESmooth || smooth current 3D image
|-
| SAIMAGESetCrosshair || set the position of the crosshair in the 3D image
|}

'''Commands for Time-Frequency Analysis''' ('''TFC''')

{| cellspacing="8"
| style="width: 180pt"| TFCStartTFAnalysis ||(previously TFCgo) start TFC analysis using the current paradigm settings
|-
| TFCdisplay || change the TFC display (e.g. power/amplitude, coherence)
|-
| TFCsave || save numerical results to an ASCII file, or save a screenshot of the TFC window
|-
| TFCimage || start beamformer analysis on a selected time-frequency range
|-
| TFCSendToMATLAB || send TF results or single-trial data to MATLAB
|}

=== How to Average Your Data in a Batch ===

Using batch processing, several files from an experiment can be averaged at a time.

Here we summarize the steps required:

'''Before running the batch'''

* Create the paradigm, and save the paradigm file.
* Open each individual data file to check the data:
** Make sure auxiliary files are defined and loaded properly, and the data are displayed correctly.
** Eyeball the data.
** Define bad (and interpolated) channels.
** Mark artifact time ranges.
** If required, set up artifact correction for the file.
** The data file can be closed again after this step.

'''Preparing the batch'''

* Open at least one file and select ''Process / Batch Scripts''.... The file(s) should be displayed in the file list. Alternatively, just select ''Process / Batch Scripts...,'' and add the files by
** pressing the '''Add File''' button
** dragging the files from Windows Explorer
** Opening a previously saved list with ''Load File List''

* You can delete files from the list (press '''Del''') or edit the file sequence using the right click context menu.
* Select the ''Batch Tab''.
* Add commands to your script. For averaging, these would normally be
** '''Paradigm''' -- to load the paradigm file
** '''Artifact Scan''' -- to run the artifact scan
** '''Average''' -- to perform the average

* Save these commands (press '''Save Batch''').
* Test the commands on the files in the current file list: press '''OK'''
* Look at the log file (press '''View Log File''') to check the results of averaging.
* Look at the data averages to make sure they have been done correctly.
* Repeat these steps until averaging is working properly.

'''Running the batch'''

* Select ''Process / Batch Scripts''....
* Open the files you want to average in the batch in the file list:
** Any files that were open in BESA are included in the list
** Files can be added using the '''Add File''' button
** You may drag one or more files from Windows Explorer to the file list
** Alternatively, load a previously saved file list.

* Edit the file list, e.g. delete unwanted files (use the '''Del''' key or the right click context menu), or reorder the files (use '''Ctrl + cursor keys''' or context menu).
* Note that the order of files in the list specifies the order in which they will be processed in the batch script. This order will be important if all results are saved to the same target file. Otherwise the file sequence is not important.
* Optionally, save the file list (press '''Save Batch'''
* Select the ''Batch Tab'', and load the previously defined batch script with ''Load Batch''.
* Press '''OK''' to run the batch.

=== How to Merge and Compress raw data ===

Using the Export command in a batch, several data files can be merged into a single data file in BESA's data format ('''<nowiki>*.foc</nowiki>''').

This can be useful if data from one subject have been collected in several data blocks, and you want to analyze all data blocks together.

Optionally, to save space, data can be saved in compressed format.

'''Files can be merged:'''

* if they have identical channel configurations, or
* there are at least 16 EEG channels, and the export format is Standard 81 (i.e. EEG channels are interpolated to 81 standard locations).

'''How to merge files:'''

* Select '''Process / Batch Scripts...'''
* Add all the files that are to be merged to the file list:
** Any files that were open in BESA Research are included in the list
** Files can be added using the '''Add File''' button
** You may drag one or more files from Windows Explorer to the file list
** Alternatively, load a previously saved file list (''Load File List'').
* Rearrange the files in the file list to the sequence in which they should be merged.
* Select the ''Batch Tab ''and insert an "''Export"'' command, as described below.

The following dialog shows a possible configuration of the ''Export'' command:

[[Image:Batch processing (4).gif]]

* The parameters shown in the Information box are the settings chosen in the ''Export Dialog'' when the '''Select Options''' button has been pressed.
* '''Append if file already exists''' must be checked in order to merge the files.
* The '''target file name''' must be fixed, i.e. don't use the '''%basename%''' variable, because that will result in a different target file name for each source file.
* There are two variables that can be used for the segment label:
** '''%filename%''' will insert the basename of the source file into the segment label.
** '''%c%''' will insert the file number into the segment label. The number gives the position of the file in the file list. For instance, "File %c%" will generate the label "File 2" for the second file in the list.

=== Example: Data averaging in the auditory intensity experiment ===

In this example, two raw data files, '''s1.cnt''' and '''s2.cnt''', from the auditory intensity experiment will be batch averaged.

Please note that there are further tutorials covering this experiment. The first file is contaminated by many eyeblinks, and more epochs would be averaged if eye correction were used (see Viewlet demonstration on artifact correction on the BESA website). However, in this tutorial we will just use artifact rejection.

'''A. Various ways of creating a File List'''

1. '''Files that were open in BESA Research are automatically added to the File List.''' Start BESA Research and open the files '''s1.cnt '''and '''s2.cnt '''in the directory ''Examples\ERP-Auditory-Intensity''.

2. Select ''Process / Batch Scripts''.... You should see the file names in the '''''File List Tab''''' something like this:

[[Image:Batch processing (5).gif]]

3. You can resort the files in the file list alphabetically by clicking onto the '''''File List column header''''':

[[Image:Batch processing (6).gif]]

Alternatively, you can mark any file, hold down the '''Ctrl '''key and press the '''Up''' or '''Down arrow '''to move the file name up or down the list. This is the sequence in which files will be processed in the batch.

[[Image:Batch processing (7).gif]]

4. Press '''Save File List''' and save the list you have created to '''ERP-Aud-Ex1.flist'''.

5. Highlight both names and press the''' Del '''button to remove them from the list.

6. '''Files can be dragged from Windows Explorer'''. Start Windows Explorer and navigate to the ''ERP-Auditory-Intensity'' subdirectory of your BESA Research examples folder (located in the ''Public Documents'' folder of your computer). Click on '''s1.cnt''' and drag it with the mouse onto the '''''File List Tab'''''. Let go of the mouse. BESA Research opens the file, and displays the name in the File List. Repeat for '''s2.cnt.'''

7. Highlight both names and press the '''Del '''button to remove them from the list.

8. '''Files can be added using the ''Add File'' button'''. Press '''Add File''' and navigate to the ''Examples\ERP-Auditory-Intensity'' subdirectory. Select '''s1.cnt'''. Press '''Ctrl''' and select '''s2.cnt'''. Both names should then be displayed in the ''File Open'' dialog. Press '''OK''' to add the files to the file list.

9. Highlight both names and press the '''Del''' button to remove them from the list.

10. '''Files can be loaded from a previously saved file list'''. Press '''Load File List '''and select '''ERP-Aud-Ex1.flist''', the list you saved in step 6 above.

'''B. Setting up the batch'''

1. We will add three commands, '''Paradigm''', '''Artifact Scan''', and '''Average''', to create a batch that will be applied to the two files in the file list.

2. Click on the '''Batch Tab'''.

[[Image:Batch processing (8).gif]]

3. Press the '''Add Command''' button to obtain the ''Select Command'' window:

[[Image:Batch processing (9).gif]]

4. Click on '''Paradigm''' and then on '''OK''' (alternatively, double-click on '''Paradigm'''). Hit '''Browse''', navigate to the ''Auditory'' folder, and select '''AEP_Intensity.pdg''', the paradigm for the auditory intensity experiment.

[[Image:Batch processing (10).gif]]

5. Press '''OK''' to obtain the ''Load Paradigm Task'' window.

[[Image:Batch processing (11).gif]]

6. Press '''OK''', and the first task in the batch is ready, and listed in the Batch Command window. If you want to modify the command, double-click on it to open the above window, that allows to browse for a different paradigm file.

[[Image:Batch processing (12).gif]]

7. Next, we add the '''Artifact Scan''' command. Click on the '''Add Command''' button, and select ''Artifact Scan.''

[[Image:Batch processing (13).gif]]

8. Press '''OK''' to open the ''Artifact Scan Task'' window. We want to be able to view the results of the scan, and adjust thresholds and bad channels if necessary. Therefore, check the ''Wait after scan'' checkbox.

[[Image:Batch processing (14).gif]]

9. Press '''OK''' to close the ''Artifact Scan Task'' window. Our batch now contains two commands.

[[Image:Batch processing (15).gif]]

10. Finally, we will add an '''Average''' command. Press the '''Add Command''' button and select ''Average''. Press '''OK''' to open the ''Average Task ''window.

[[Image:Batch processing (16).gif]]

11. With the default settings, the average would be saved to the same directory as the data. The file name mask is set by default so that in this example the two averages would be saved to '''s1-av.fsg '''and '''s2-av.fsg'''. We will save the averaged files to subdirectory ''"Averages''" of the data directory. Uncheck the ''Use default target'' check box, change the File name mask to '''%basename%_av-test''' in order not to overwrite the predefined files.

[[Image:Batch processing (17).gif]]

12. Press '''OK '''to close the ''Average Task'' window. Our batch is now complete.

[[Image:Batch processing (18).gif]]

13. We will now save the batch so that it can be used again. Press the '''Save Batch''' button, and save to the file '''ERP-Aud-ex1.bbat'''. Note that an easy way to generate new averaging batches is to load a previously save batch and edit the commands -- it may only be necessary to edit the '''Paradigm''' command to select the relevant paradigm file, and maybe to adjust the target directory in the '''Average''' command.

14. Press '''OK''' in the ''Batch'' Window to start the batch running. As requested, the batch pauses after the artifact scan:.

[[Image:Batch processing (19).gif]]

You may now adjust the number of rejected trials, e.g. by moving the vertical red bar to the left, or exclude bad channels.

15. Press '''OK''' to continue with averaging.

[[Image:Batch processing (20).gif]]

16. Note that, in the background, the ''Batch Running'' window is providing feedback about the current file and current task.

[[Image:Batch processing (6).jpg|400px]]

17. The batch will stop again after the next artifact scan. Press '''OK''' to allow the batch to run to the end.

[[Image:Batch processing (21).gif|400px]]

18. Press '''View Log''' to view the batch protocol. If you are using Internet Explorer or Netscape family (Mozilla, Firefox) browsers, and JavaScript is enabled, you will first see just batch titles defined by the date and time the batch was started. The most recent title is at the top of the list. For other browsers, or if JavaScript was not enabled, all protocol texts are expanded as in 19 (below).

[[Image:Batch processing (22).gif|200px]]

19. Click on the first title to expand its protocol. Here, for example, the protocol gives feedback about the number of epochs that were averaged for each file.

[[Image:Batch processing (23).gif]]

20. Finally, press '''OK''' to return to the main BESA Research display. Open the averages in the ''Averages'' subdirectory to confirm that they were generated properly.

=== Example: Merging files using the Export Command ===

Here we will demonstrate the use of the '''Export '''command to merge two files. We will combine the two averages from the previous example (Data averaging in the auditory intensity experiment) into one target file.

'''A. Generate the file list'''

# Start BESA Research and load the two data files '''S1_av-test.fsg''' and '''S2_av-test.fsg''' that were saved in the previous example.
# Select ''Process / Batch Scripts....''The two file names should be displayed in the file list.
# In the file list, make sure that '''s1_av-test.fsg '''is the first file in the list. If it is not, highlight the file, and move it up using '''Ctrl+up''', or right click and select ''Move Up'' in the context menu.

'''B. Generate the batch'''

1. Press the '''Add Command''' button, and select the '''Export''' command.

2. Press '''OK''' to open the ''Export Task'' window.

[[Image:Batch processing (24).gif]]

3. Press the '''Select Options'''... button to open the ''Export Dialog''.

[[Image:Batch processing (25).gif]]

4. Since we are combining averages, select ''Hires (no compression)'' in the '''Target data format''' drop-down list (If we were merging raw data files, it is better to select compression. Press '''OK '''to close the dialog. Check'' Append if file already exists'', so that the files will be merged. Enter '''s1+s2''' in the target file name mask edit box. This ensures that both files will be saved to the same target: '''S1+S2.fsg'''.

[[Image:Batch processing (26).gif]]

5. Press '''OK '''to close the ''Export Task'' window. The '''Export '''command is displayed.  

[[Image:Batch processing (27).gif]]

6. Optionally, you may save the batch file by pressing '''Save Batch'''.

7. Press '''OK''' to run the batch, and '''OK''' in the ''Batch Completed'' window to return to the BESA main window.

8. Finally, open the file '''S1+S2.fsg''' to confirm that it contains the two merged files.

'''C. Merge raw data'''

# Repeat the above task to merge the two raw data files '''S1.cnt''' and '''S2.cnt''' into a single target file '''S1+S2.foc'''. In this case, select one of the compression options as the target data format. Note that you would not normally want to merge two files from different subjects. However, several data blocks from the same subject can conveniently be merged using this method.

Note that ''<nowiki>*.fsg</nowiki>'' files can also be merged using the ''Combine Conditions'' dialog. 

== Combine Conditions, Channels ==

=== Combine Condition Scripts ===

With the Combine-Conditions module you can do a variety of operations on BESA averages (files with the extension '''<nowiki>*.fsg</nowiki>''', and other segment files, such as '''<nowiki>*.mul</nowiki>''', '''<nowiki>*.avr</nowiki>''', '''<nowiki>*.swf</nowiki>'''):

* Create grand averages
* Combine averages (add, subtract, weighted/unweighted)
* Merge files
* Exclude unwanted averages
* Rename conditions
* Rename or resort channels
* Generate averages or differences over selected channels
* Transform the data: standard interpolated 81 electrodes, change sampling rate, change interval
* Determine peaks, mean amplitudes, or integrals on data averages
* These operations can be performed on one or more files simultaneously. Results of an operation are stored in a single target file.

The module includes four tabbed windows:

* File List: Define a list of files on which the operations will be performed.
* Condition List: List the condition names, define target condition names, and how input conditions are combined into target conditions.
* Channel List: List the channel names, define target channel names, and how input channels are combined into target channels.
* Run Scripts: Define global options for the output (e.g. spatial interpolation, resampling, copy/merge or average, peak analysis). Start the operation.
* Note that in all four tabs, configurations can be saved for future use, and the '''Load Previous''' button restores the most recently used configuration.

=== Condition List Tab ===

List the condition names, define target condition names, and how input conditions are combined into target conditions.

The first column of the list box shows a list of all the condition names found in the source files.

Rows of the list box define the source conditions. Columns define the target conditions.

'''Initial setting'''

When first selecting the tab, each column shows each condition name found in the source files (as in the example below). In the list box, there is a "+1" along the diagonal. The result of this selection is that target conditions will have the same name as source conditions. Right click on source condition labels to view properties (e.g. no. of samples, time range, sampling rate).

[[Image:Batch processing (28).gif]]

'''Editing the condition list'''

* Target condition names can be edited, inserted or deleted by clicking on the label at the top of each column.
* Click on a box within the list to toggle between "+1", "-1" and blank. These correspond to the operations:
** "+1" = add
** "-1" = subtract
** blank = do nothing
* Right click on a box for further operations: conditions can be weighted by a given factor other than 1.

'''Divide result by sum of PLUS factors'''

* Normally, when creating an average over conditions, the sum is divided by the number of conditions, or a weighted average is generated (see below).  If "''Divide the result by the sum of PLUS factors''" is unchecked, the conditions will be summed rather than averaged.
* Note that, when making differences between conditions, no such division is required. BESA Research will uncheck the checkbox automatically if subtraction ("-1") is specified somewhere in the condition list.

'''Weighting of averages'''

* Below the list, click on the ''Weighted Average'' row to toggle "YES" and "NO". "YES" means that averages will be weighted by the number of epochs contributing to the average. For instance, if average A contained 100 epochs and average B contained 200 epochs, the weighted average will be computed as

<div style="margin-left:1cm;margin-right:0cm;">(100 * A +  200 * B) / (100 + 200)</div>

<div style="margin-left:1cm;margin-right:0cm;">Select "NO" for an unweighted average. For the above example, the average is computed as</div>

<div style="margin-left:1cm;margin-right:0cm;">(A + B) / 2</div>

<div style="margin-left:1cm;margin-right:0cm;">Weighted averages are not permitted if one of the boxes contains a negative value.</div>

* Values other than +1 or -1 in the boxes apply a different kind of weighting. For instance, we want to compute the difference between the means of conditions A, B, C and D, E. Use a right-click to specify the fraction 1/3 for each of A, B, and C, and -1/2 for each of D and E (see example below).

[[Image:Batch processing (29).gif]]

'''Save the current condition list'''

* Press the '''Save Condition List''' button.

'''Load a condition list'''

* Press the '''Load Condition List''' button.

'''Load previous settings'''

* Press the '''Load Previous''' button

'''Feedback'''

* Conditions that have different numbers of electrodes (averaging across different files) can only be combined if channels are interpolated to a standard set of electrodes.
* Conditions that have different durations or sampling rates can only be combined if the sampling rate and durations are made the same.
* Feedback about the above situations is displayed by the presence of tick marks above the list box.

=== Channel List Tab ===

List the channel names, define target channel names, and how input channels are combined into target channels.

Note that this tab is very similar in usage to the '''Condition List Tab'''. Note also that some of the functions performed in this tab could also be done in the Montage Editor. It may be a matter of convenience whether you choose to perform these operations here or in the Montage Editor.

The first column of the list box shows a list of all the channel names found in the source files.

Rows of the list box define the ''source'' channel. Columns define the'' target'' channel.

'''Initial setting'''

When first selecting the tab, each column shows each channel name found in the source files (as in the example below). In the list box, there is a "+1" along the diagonal. The result of this selection is that target channel will have the same name as source channel.

'''Combining files'''

If files with different channel configurations are included in the File List, the rows and columns of the Channel List Tab will only contain the labels for the channels that are in common among the files.

If the files in the File List have a different sequence of channels, the sequence of the first file in the list will be adopted in the Channel List.

Thus, for the initial setting, unless the "''Ignore Settings in this Tab''" checkbox is checked, the target grand average or peak/amplitude analysis, etc. will be applied using only channels that are in common among the input files, and using the channel sequence of the first file in the File List. By changing the target channels or by changing the entries in the Channel List, new channels consisting of averages or differences can be generated.

'''What can the Channel List be used for?'''

Some examples:

* Reorder or relabel channels
* Create channel differences
* Create averages over channel groups, e.g. for peak analysis
* Extract a selection of channels for peak analysis or mean amplitudes
* Create grand averages across files with different channel configurations, just using channels in common among the files

[[Image:Batch processing (30).gif]]

'''Editing the channel list'''

* Target channel names can be edited, inserted or deleted by clicking on the label at the top of each column.
* Click on a box within the list to toggle between "+1", "-1" and blank. These correspond to the operations:
** "+1" = add
** "-1" = subtract
** blank = do nothing
* Right click on a box for further operations: channels can be weighted by a given factor other than 1.

'''Divide result by sum of PLUS factors'''

* Normally, when creating an average over channels, the sum is divided by the number of channels, or a weighted average is generated (see below).  If "Divide result by the sum of PLUS factors" is unchecked, the channels will be summed rather than averaged.
* Note that, when making differences between channels, no such division is required. BESA Research will uncheck the checkbox automatically if subtraction ("-1") is specified somewhere in the channel list.

'''Save the current channel list'''

* Press the '''Save Channel List''' button.

'''Load a channel list'''

* Press the '''Load Channel List '''button.

'''Load previous settings'''

* Press the '''Load Previous''' button

=== Run Scripts Tab ===

Define global options for the output (e.g. spatial interpolation, resampling, copy/merge or average, peak detection. Start the operation.

[[Image:Batch processing (7).jpg]]

'''Load or Save Settings'''

* You can save the current settings of this tab to a file (*.run) which can be loaded later.
* When you run the script, the current settings are saved automatically to a file "'''PreviousSettings.run'''".

'''Load Previous'''

* Press this button to load the previous settings (from "'''PreviousSettings.run'''").

'''Averages to Generate'''

* '''Generate separate averages for each source file'''. Averages are performed over conditions within the source file, and are then appended to the target file.
* '''Combine data from source files'''. Conditions are combined over all source files into a single target average.
* '''No averages, just copy'''. Files are copied and merged to the target file. Use this option for renaming conditions, merging files, removing unwanted averages (see below), changing the sampling rate and interval.
* '''Peaks and mean amplitudes'''. Specify time ranges for peaks, mean amplitudes, or integrals (areas).
* Note: When generating or copying averages (first three options), filters and baseline settings are turned off. For Peaks and mean amplitudes, filters and baseline settings are specified in the dialog.

'''Spatial Interpolation'''

* '''Interpolate to Standard 81 electrodes'''. The target file will contain only electrodes (other channels are omitted), using the Standard 81 configuration (as in other export functions within BESA Research). This cannot be selected if the source data contain less than 16 EEG channels.
* '''Interpolate Bad Channels'''. Bad electrode channels in the source file will be interpolated. If the above option is deselected and bad channels exist in one or more of the source files, this option is always on.

BESA Research can interpolate EEG, and MEG if the sensors are axial gradiometers or magnetometers. If other channels are marked as bad in one or more of the source files, these will be defined as bad in the target file. This applies to MEG planar gradiometers, to polygraphic data, and to ICR channels.

'''Temporal Interpolation'''

* '''Spline to New Sampling Rate and Interval'''. Data can be converted to a new sampling rate, and the interval can be changed.
** If the sampling rate is reduced, the data will be low-pass filtered at 1/3 sampling frequency before reduction.
** If the sampling interval is changed, the prestimulus and poststimulus intervals are limited by the smallest intervals in the conditions contributing to the averages. These limits are shown below the edit boxes.

'''Peaks and Mean Amplitudes'''

[[Image:Batch processing (31).gif]]

'''Peaks:'''

* Select the time range between which peaks are to be determined.
* Select the montage on which the peaks are to be determined.
* Define the filter settings.
* Define the baseline settings.
* Specify whether peaks are to be defined at one latency: if so, select the channel on which peaks are to be detected.
* Specify whether you want to find positive or negative peaks.

'''Mean amplitudes and areas:'''

* Select the time range over which the mean amplitudes or areas are to be determined.
* Select the montage on which the mean amplitudes or areas are to be determined.
* Define the filter settings.
* Note that when computing areas, data are first rectified (made positive) and then summed over the time range.

'''Output options of the analysis:'''

* A single ASCII file that contains the result of the analysis for all data sets, conditions, and channels including header and information lines.
* A sparse output suitable for import in SPSS. Each variable (e.g. a latency, a channel amplitude) constitutes one column of the output file.
* Direct transfer to MATLAB into a struct besa_peak. For more information on the data transfer from BESA Research to MATLAB, please refer to help chapter ''“The MATLAB interface”.''

'''Starting the Operation'''

* Press '''OK''' to start the operation. After the operation is completed, and the "Open target file in BESA" box is checked, BESA Research will open the target file.  "Open target file in BESA" cannot be checked if "Peaks and mean amplitudes" was selected - then the result of the operation will be an ASCII file or a MATLAB transfer.
* You will be asked for the name of the target file (unless a MATLAB transfer of peak data has been performed).

'''Restrictions'''

* Depending on source file configurations, not all options above are selectable. For instance, if two files contain different numbers of electrodes, and the "''Ignore Settings in this Tab''" checkbox is checked in the '''''Channel List''''' Tab, spatial interpolation to Standard 81 is enforced in the target. Similarly, if different sampling rates are used in different files, temporal interpolation is enforced.
* You are not allowed to add files to the file list if the channel configuration is different, and the data cannot be combined with Standard 81 interpolation. Since Standard 81 interpolation is only possible for EEG, multiple files without EEG can only be loaded if they have the same number of channels.

=== How to Create Grand Averages ===

* Open the files you want to average in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. To average across different conditions, click in the list boxes to obtain "+1" for each source condition to combine, and rename the target condition to define a meaningful name for the average.
* Click on the '''Run Scripts Tab'''.
* If you have more than one file, specify whether averages should be generated across files ('''Combine data from source files''') or within files ('''Generate separate averages for each source file''').
* Select other options if required (spatial or temporal resampling).
* Press '''OK'''.

=== How to Generate Differences Between Conditions ===

* Open the files you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. To create differences, click in the list boxes to obtain "+1" for one of the source conditions, and "-1" for the source condition to subtract, and rename the target condition to define a meaningful name for the difference.
* Click on the '''Run Scripts Tab'''.
* If you have more than one file, specify whether averages should be generated across files ('''Combine data from source files''') or within files ('''Generate separate averages for each source file''').
* Select other options if required (spatial or temporal resampling).
* Press '''OK'''. An average of the differences is generated. If only one example of each condition exists, e.g. in a grand average file, the result is the difference between conditions.

=== How to Merge Files ===

* Open the files you want to merge in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions''...).
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press '''OK'''.

'''Notes'''

* If the source files have different electrode configurations, use the Standard 81 configuration for the target.
* If the source files have different sampling rates or intervals, use Temporal Interpolation.

=== How to Remove Unwanted Averages ===

'''Removing one or more unwanted segments'''

* Normally, all conditions are read from a source file. To exclude one or more segments from operations in the Combine Conditions module, mark the segments as artifacts in the main program display. It is sufficient for the beginning or the end of an artifact interval to be within the segment for the segment to be excluded.
* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press''' OK'''.
* The target file contains the copied data without the conditions that were marked as averages.

'''Removing one or more unwanted conditions (by label)'''

* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Deselect the target conditions you want to omit (replace the "+1" by a blank).
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press''' OK'''.
* The target file contains the copied data without the conditions that were marked as artifacts.

=== How to Rename Conditions ===

* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions''...).
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. Click on column headings to rename the target conditions.
* Click on the''' Run Scripts Tab'''. Select "''No averages, just copy''".
* Press '''OK'''.
* The target file contains the copied data with the renamed conditions.

=== How to Change the Sampling Rate ===

* Open the file(s) you want to change in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...'').
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Select "''Spline to New Sampling Rate and Interval''" and type the new sampling rate into the edit box.
* Press '''OK'''.

=== Example: Create grand average and combinations of conditions ===

In this example, we will generate a grand average of the results of the Auditory Intensity Experiment. The experiment includes averages from five different stimulus intensities. We will create a grand average over each intensity, but also include means over the two lowest and the two highest intensities, and the difference between these two combinations.

'''A. File selection'''

# Start BESA Research and open files '''S1_av.fsg - S10_av.fsg''' in the ''Examples\ERP-Auditory-Intensity'' folder. The files contain the individual averaged data of the 10 subjects who participated in this study.
# Select ''ERP / Combine Conditions...'' The file list should display the two files, with feedback about the number of averages and conditions. 8 epochs are found. See the ''“Data averaging in the auditory intensity'' ''experiment”'' example for examples how to manipulate the file list.

[[Image:Batch processing (32).gif]]

'''B. Define conditions'''

1. Click on the '''Condition List Tab'''. The initial window defines target conditions with the same name as the source conditions. To generate the grand average over these conditions we could proceed without further changes to the '''Run Scripts Tab'''. However, we want to modify the condition list and create a condition that contains the grand averaged difference between the''' High''' and '''Low''' conditions.

[[Image:Batch processing (8).jpg]]

2. Click on the '''All '''column label. In the resulting window, rename condition '''All''' to''' Difference'''. Then press '''OK'''.

[[Image:Batch processing (33).gif]]

3. The last column is now labeled '''Difference.''' Left-click twice onto the ‘'''+1’''' entry that links this condition to the '''All '''input condition. This will remove the link and leave the field blank. To define the ‘Difference’ condition as the average of ‘High’ minus ‘Low’ over subjects, left-click once into the field linking input '''High''' with target '''Difference''' to generate an entry ‘'''+1’''' in this field. Left-click twice into the field linking input '''Low '''with target '''Difference''' to generate an entry '-'''1'''’.

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;">[[Image:Batch processing (35).gif]]</div>

4. Press '''Save Condition List''' and save the list to '''ERP-aud-ex1.clist'''. This condition combination can thus be loaded later using the '''Load Condition List''' button.

'''C. Run the script'''

# Click on the '''Run Script Tab'''.
# The default tab settings are ready for generating the grand average ('''Combine data from source file''' and '''Open target file in BESA''' should be checked). Just press '''OK'''. Enter '''All_Subjects_cc-test.fsg''' as file name and press''' Save'''.

The resulting file contains the 8 target conditions, 60db, 70dB, 80dB, 90dB, 100dB, Low, High, and Difference.

=== Example: Average files from different experiments ===

This example is intended to illustrate several features of the ''Combine Conditions'' Dialog, such as electrode interpolation and resampling. We will combine an average from the Auditory Intensity experiment with one from the P300 auditory experiment. In this particular case, it is not a very meaningful thing to do, but it shows what is possible. For instance, the same experiment may have been performed using different sampling rates or electrode combinations. This example shows how such data may be combined.

'''A. File selection'''

# Start BESA Research and open the file '''All_Subjects_GA.fsg''' in the ''Examples\ERP-Auditory-Intensity'' folder. The file contains the grand average data from the auditory intensity experiment.
# Open the file '''RareFrequentResponseLeft.fsg''' in the ''Examples\ERP-P300-Auditory'' folder. This file contains averages from the P300 auditory experiment.
# Select ''ERP / Combine Conditions... ''Note that the files have different sampling rates and different numbers of electrodes.

[[Image:Batch processing (36).gif]]

'''B. Define conditions'''

1. Click on the '''Condition List Tab'''. Note that the feedback text at the bottom of the window displays the text "Standard 81 interpolation required to generate average; Across files: resampling or change in time range required to generate average". The condition labels show all the names from both files.

[[Image:Batch processing (37).gif]]

2. We will exclude most conditions, and just combine the most similar conditions from the two experiments: the "Standard" and the "80dB" conditions. Click on the title of the first column,''' Blink'''. Select “''Delete all conditions to the right of this column”'', and press '''OK'''.

[[Image:Batch processing (38).gif]]

3. Click on the title again, and rename the target condition to "Standard".

[[Image:Batch processing (39).gif]]

4. Click twice in the first line to remove the "+1" entry there. Click once in the third row ("Frequent"), and in the 7th row ("80dB"), to display "+1" at each entry. Thus, just two of the conditions will be combined into one target condition.

[[Image:Batch processing (40).gif]]

'''C. Run the script'''

1. Click on the '''Run Script Tab'''.

[[Image:Batch processing (41).gif]]

2. Note that '''Interpolate to Standard 81 electrodes''' is checked and grayed: since two different electrode sets are to be combined, we can only do this by interpolating electrodes. Also, both '''Spline to new sampling rate''' and '''Clip interval '''are checked and grayed. Again, these settings are required in order to be able to average the two data files together. The sampling rate is set to the higher of the two selections. The time range is set to the largest possible range that can be clipped from the two data sets. For now, leave these settings as they are, and press '''OK'''. Save the target to '''TestCombineExpts_CC-std81.fsg'''.

{{BESAManualNav}}

BESA Research Batch Processing

2021-05-05T13:15:00Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = 6.1 or higher
}}



== Combine Conditions and Batch Module: Introduction ==

Functions of this module are started by selecting the menu operations "'''ERP / Combine Conditions...'''" and "'''Process / Batch Scripts...'''".

* '''Combine Condition Scripts''' provides various operations on BESA averages.
* '''Batch Scripts''' provides batch operations on all data files.
* Note that a batch script can also be performed on the current file by selecting "'''Process / Run Batch...'''" or by typing the shortcut key "'''R'''".

== File List Tab ==

Define a list of files on which the operations will be performed. The tab is the same for Combine Conditions Scripts and for Batch Scripts. Combine Conditions Scripts only allows you to open BESA average files (e.g. '''<nowiki>*.fsg</nowiki>''' and '''<nowiki>*.avr</nowiki>''', but also '''.mul''', '''.raw''', '''.swf''', and '''.foc''' if the files have a defined pre-stimulus interval), whereas Batch Scripts allows you to open any data file whose format is known to BESA Research.

When the Combine-Conditions or the Batch module is started, all currently opened (Combine-Conditions: averages only) files are displayed in the list.

To the right of each file name, the number of electrodes, total number of channels, and the sampling rate used in the file are displayed. In the Combine-Conditions module, the number of Epochs (segments) and the number of differently-named conditions are also shown.

'''Add files to the list'''

* Press the '''Add File ''' button.
* Drag one or more files from Windows Explorer onto the window.

'''Remove files from the list'''

* Right click on the file name and confirm the delete operation in the resulting dialog.
* Mark one or more file names in the list (e.g. hold down the''' Ctrl''' key to mark multiple files). Right click to obtain the context menu and select "'''Delete'''", or just press the '''Del '''key.

'''Reorder files within the current file list'''

* Right click on the file name and select "'''''Move Up'''''" or "'''''Move Down'''''".
* Mark one or more file names in the list (e.g. hold down the '''Ctr'''l key to mark multiple files). Right click to obtain the context menu and select "'''''Move Up'''''" or "'''''Move Down'''''", or hold down the''' Ctrl''' key '''and '''press the '''Up''' and '''Down arrows'''.

'''Sort the current file list alphabetically'''

* Click on the File bar above the list

'''Save the current file list'''

* Press the '''Save File List''' button.

'''Load a file list'''

* Press the '''Load File List''' button, or the '''Load Previous''' button to load the most recently used file list.

'''Which conditions are read from a source file? (Combine-Conditions module only)'''

* Normally, all conditions are read from a source file. To exclude one or more segments from operations in the Combine Conditions module, mark the segments as artifacts in the main program display. It is sufficient for the beginning or the end of an artifact interval to be within the segment for the segment to be excluded.

'''File list from Combine Conditions:'''

[[Image:Batch processing (1).png]]

'''Don't try to open here... (Batch only)'''

By default, this checkbox is unchecked.

In the checked state, BESA Research doesn't check if it can open the file. Use this function '''only''' if the file is ASCII and you want to use the '''ImportASCII '''batch command.

'''File List from Batch Scripts''':

[[Image:Batch processing (2).png]]

== Batch Processing ==

=== Batch Processing Scripts ===

With Batch Scripts, you can define a set of operations (e.g. Artifact Scan, Average, etc.) and apply these to several data files.

These operations include

* Load Paradigm
* Artifact Scan
* Average
* Export (and Merge)
* File Open (switch to another data file)
* Set filters
* Specify a montage (used, for example, for export to current montage)
* Run automatic eye and EKG artifact correction
* Define artifact topographies
* Turn artifact correction and view on and off
* Read and write events
* Edit default block epoch (for export around triggers)
* Edit triggers (for export around triggers)
* Mark a block for export, or send the block to Source Analysis or Top View
* Convert patterns to triggers
* Attach auxiliary files (e.g. elp, sfp) to the data file
* Send to MATLAB
* Specify display configurations for the BESA Research Main, SA, and Top View windows
* and more - see the full list of [[#Batch Commands|Batch Commands]]

An additional set of commands are available for operations in the '''Source Analysis Module''', allowing to load, create and fit dipole models, and save the results.

A further set of commands apply to '''Time-Frequency Analysis''', allowing to start TFC, change the display, save results, and run the beamformer or DICS analyses on a selected time-frequency range.

[[Image:Batch commands1.png]]

These operations will be extended in future program releases.

The module includes two tabbed windows:

* '''File List''': Define a list of files on which the operations will be performed.
* '''Batch''': Define or load '''batch commands'''. Run the batch.

=== Batch Tab ===

Load or define batch commands, and then apply them to the files in the File List.

[[Image:Batch processing (4).png]]

'''Add Command'''

* Press '''Add Command''' to add a new command to the batch. The following dialog is opened, showing the available commands:

[[Image:Batch commands1.png]]

* Select the desired command and press '''OK''' or double-click on the command. A dialog box is opened, allowing to specify individual command parameters.
* If you click on "Apply at beginning of batch" or "Apply at end of batch", the command will only be run at the beginning or the end of a batch. You can use this, for example, at the end of a batch to start a MATLAB script to perform statistics on the results of the batch.

'''Load and Save Batch'''

* Press '''Load Batch''' to load a previously defined batch or '''Save Batch''' to save the current batch to a file ('''<nowiki>*.bbat</nowiki>''').

'''Load Previous'''

* Press '''Load Previous''' to load the most recently used batch file. Whenever a batch is run, the current set of commands is written to the file '''Previous.bbat in''' the '''Scripts/Batch''' subdirectory. This file is loaded when you press '''Load Previous'''.

'''Clear All'''

* Clears all commands from the window.

'''View Log File'''

* Each time a batch is run, BESA Research adds information about the batch to a log file, with headings showing the date and time the batch was started. The file is opened automatically in Internet Explorer if errors occurred during processing. Otherwise you may open the file by pressing the '''View Log File''' button here or in the dialog that is displayed at the end of batch processing. 
* The log file is saved in xml format, and a JavaScript is used to format the display in web browsers. JavaScript should be enabled in the browser to obtain an optimal display of the results. If JavaScript is enabled, the log file is displayed as a list of headings for each batch. Click on a heading to display the results of the corresponding batch.
* To open the log file in the Notepad, hold the''' Shift '''key down when pressing the '''View Log File''' button.

'''Batch Command List'''

* Double-click on a command to edit it. See [[#Batch Commands|Batch Commands]] for descriptions of the dialogs that are opened to edit each command.
* Right click on a command to open a context menu allowing more options.

[[Image:Batch processing (5).png]]

* '''Delete''', '''Move Up''', '''and Move Down''' can also be applied to multiple selections.
* If you have made a multiple selection, the '''Del '''button will delete all the marked commands. '''Ctrl '''plus '''Up''' or '''Down''' '''cursor keys''' will move the marked commands up or down.
* '''Toggle Comment''' will add or remove a semicolon (;) in front of the command, to deactivate or reactivate the command.
* '''Toggle Command Only at Start/End''' will add or remove the text "Start_" or "End_" in front of the command. With these prefixes, the command will only be performed when the first file ("Start_") or the last file ("End_") in the file list is being processed.

'''Single Step Mode'''

* Check this item to step through the batch, one command at a time. A dialog is opened after each command, allowing to run the next command, continue the batch without single steps, or stop running the batch. See the'' “Pause''” command for further details.
* During a batch, press and hold down the '''Pause''' or '''Delete''' key to interrupt the batch and enter Single Step Mode. Press and hold down the '''Esc''' key to cancel the batch.

'''Changes in batch written to database'''

* Checked by default. If this item is unchecked, file display settings, such as Montage setting and Artifact correction display, are not written to the database. When the file is next opened in BESA Research, the settings made in the batch are not retained.

'''Leave files in the file list open after running the batch'''

* If this item is checked, files in the file list will remain open after the batch. This is useful, for instance, if you want to open a set of files, specifying the same montage and/or filter settings for each file.

Press '''OK''' to start running the batch. Each command is then applied in succession to each file in the File List.

Note that, while a batch is running press and hold down the''' Pause''' or '''Delete''' key to interrupt the batch and enter Single Step Mode. Press and hold down the '''Esc''' key to cancel the batch.

=== The log file ===

A protocol of each batch is written to the log file '''Scripts/Log/Batch.xml.'''

When you press the '''View Log File '''button, the file is opened in your default browser for xml files. The file will be opened automatically if there was an error during batch processing unless you have used the ''BatchError'' batch command to suppress this behaviour.

'''DHTML formatting of the log file'''

The xml file is formatted using JavaScript (Dynamic HTML). If JavaScript is enabled in your browser, you will first see a list of batch protocol titles, labelled by the date and time at which the batch was started. The most recent batch is at the top of the list.:

[[Image:Batch processing (6).png|200px]]

Click on the title to view the protocol for the corresponding batch:

[[Image:Batch processing (7).png|600px]]

'''JavaScript and XP Service Pack 2'''

By default, if the log file is opened in Internet Explorer after XP Service Pack 2 has been installed, IE will warn you with the message: "''To help protect your security, Internet Explorer has restricted this file from'' ''showing active content that could access your computer".'' All the protocols in the log file are displayed. You may safely click on the options to allow active content in the log file, if you want to display the file as described above.

'''Backup of the log file'''

When the log file is written, a backup of the previous version is written to '''batch.xml.bak'''.

If the size of the log file exceeds 200 KB, it is renamed to '''batch.xml_date_time''' (e.g. '''Batch.xml_2004-10-08_10-53-32'''), and a new version of '''batch.xml''' is created.

=== Placeholders ===

A powerful feature of the batch commands is the ability to define file names and specify standard paths using placeholders. These are text strings enclosed by percentage (%) signs. They can be used in all batch commands where file names are specified.

'''Basename'''

{| class="wikitable"
! Placeholder !! Description !! Example
|-
|style="text-align:center;" width="10%"|'''%basename%'''
|width="40%"|replaced by the basename of the currently opened file.
|width="40%"|If the data file is named "f-spike.fsg", "%basename%-export.fsg" will be interpreted as "f-spike-export.fsg".
|-
|style="text-align:center;"|'''%basename-n%'''
|replaced by the basename of the currently opened file, but removing the last "n" characters from the name.
|If the data file is named "dongle-BB.fsg", "%basename-3%" will be replaced by "dongle", because the last 3 characters of the basename have been removed.
|-
|style="text-align:center;"|'''%-nbasename%'''
|replaced by the basename of the currently opened file, but removing the first "n" characters from the name.
|If the data file is named "BB-dongle.fsg", "%-3basename%" will be replaced by "dongle", because the first 3 characters of the basename have been removed.
|-
|style="text-align:center;"|'''%orgbasename%'''
|replace by basename of the current file in the file list (it has the same meaning as %basename% if no MAINFileOpen batch command was used in command list)
|
|-
|style="text-align:center;"|'''%base%'''
|replace by basename of the current file without the path
|
|-
|style="text-align:center;"|'''%orgbase%'''
|replace by basename of the current file in the file list without the path
|-
|style="text-align:center;"|'''%ext%'''
|replace by extension of the current file
|
|-
|style="text-align:center;"|'''%orgext%'''
|replace by extension of the current file in the file list
|
|-
|style="text-align:center;"|'''%basefolder%'''
|replace by folder of the current file
|
|-
|style="text-align:center;"|'''%orgbasefolder%'''
|replace by folder of the current file in the file list
|
|-
|style="text-align:center;"|'''%t%'''
|Log batch command only: time since start of batch on current file
|
|-
|style="text-align:center;"|'''%T%'''
|Log batch command only: current date and time
|
|-
|style="text-align:center;"|'''%label%'''
|Replace label of the most recent marked block by the block label, not including no. of averages
|
|-
|style="text-align:center;"|'''%LABEL%'''
| Replace label of the most recent marked block by the block label, including no. of averages

|
|-
|style="text-align:center;"|'''%scripts%'''
|replaced by the path to the Scripts folder.
|"%scripts%Batch" is where batches are saved by default; "%scripts%MATLAB" is the location of the standard MATLAB scripts used by BESA Research.
|-
|style="text-align:center;"|'''%montages%'''
|replaced by the path to the Montages folder.
|
|-
|style="text-align:center;"|'''%examples%'''
|replaced by the path to the Examples folder.
|
|}



'''Placeholders for folders'''

The following placeholders are the same as those used in the [Folders] section of '''Besa.ini''':

The strings enclosed by percent signs (%) are placeholders for the following folders in English-language versions of Windows. Folder names are different for the system and for other language settings. BESA Research will substitute the placeholders by the appropriate folder name for the Windows system and the system language:

* '''Windows 10 (English)'''

<div style="margin-left:1.27cm;margin-right:0cm;"> '''%localapp%''' = ""C:\Users[user]\AppData\Local\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Desktop as ""Desktop[user]\AppData\Local\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;"> '''%publicprog%''' = "Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = ""C:\Users\[user]\Documents\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as "Desktop\[User]\Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as''' %progdir%'''</div>

* '''Windows 7 (English):'''

<div style="margin-left:1.27cm;margin-right:0cm;">'''%localapp%''' = "C:\Users\[user]\AppData\Local\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Desktop as "Desktop\[user]\AppData\Local\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%publicprog%''' = "C:\Users\Public\Public Documents\BESA\Research_7_1". This folder is directly accessible from the Windows Explorer under "Libraries\Documents\Public Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = "C:\Users\[user]\Documents\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as ""Libraries\Documents\My Documents\Research_7_1" or "Desktop\[User]\My Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as''' %progdir%  '''</div>

=== Batch Commands ===

Batch commands are selected when the "'''Add Command'''" button is pressed in the "Batch" Tab. The commands are subdivided into five categories: General commands, commands for the Main module, for the Source Analysis module, imaging commands in the Source Analysis module, and commands for Time-Frequency Analysis. The commands have prefixes,''' GEN''', '''MAIN''',''' SA''', '''SAIMAGE''', and''' TFC'''), which identify the category. For compatibility with older program versions, old batches without the prefixes are accepted.

Detailed descriptions of each batch command are available in the electronic help chapter “''Batch Processing and Combining Conditions / Batch Processing / Batch Commands”.''

'''General commands''' - prefixed with "'''GEN'''" (can be used anywhere):

{| cellspacing="8" style
| style="width: 180pt"| GENBatchError || used to change program behavior when errors occur
|-
| GENBatchWindowPosition || set the position of the batch window relative to the main window
|-
| GENComment || comment in the batch script: no batch functionality
|-
| GENMATLABcommand || send a command string to MATLAB
|-
| GENMATLABwaitForVariable || tells BESA to wait until Matlab has created a variable with the specified name.
|-
| GENPause || pause batch operations, allowing step-by-step operations
|-
| GENFor/GENEndFor|| a programming language-like FOR loop
|-
| GENRunProcess || runs a command-line process, e.g. an external program to perform part of the data analysis in the batch
|-
| GENsaveBitmap || save a screenshot of the Source Analysis or the 3D window
|-
| SetVariable || the value of the variable is inserted into subsequent batch commands where the text contains the name flanked by % signs
|-
| GENWindowPosition || set window size and positions to a selection of standard settings, e.g. for bitmap export
|}

'''Commands for the Main Module''' - prefixed with "'''MAIN'''":

{| cellspacing="8"
| style="width: 180pt"| MAINArtifactCorrect || run automatic artifact correction
|-
| MAINArtifactMethod || specify the method for artifact correction
|-
| MAINArtifactOn || turn artifact correction an artifact view on or off
|-
| MAINArtifact Scan || run an artifact scan as from the Paradigm Dialog
|-
| MAINAuxiliaryFiles || associate auxiliary files (e.g. *.''ela'', *.''sfp'') with the data file
|-
| MAINAverage || average the data
|-
| MAINBaseline || specify the parameters for baseline correction
|-
| MAINDefineArtifactTopography || define an artifact topography
|-
| MAINEditDefaultEpoch || edit the default block epoch
|-
| MAINEventRead || read events from an ASCII event file
|-
| MAINEventWrite || write events to an ASCII event file
|-
| MAINExport || export or append data in the selected target format
|-
| MAINExportToBESAConnectivity || export data segments to BESA Connectivity
|-
| MAINFFT || calculates the FFT spectrum of the marked data interval
|-
| MAINFFTmean || starts an averaging procedure that calculates the mean spectral properties in pre-defined regions
|-
| MAINFFTsave || saves FFT data (generated using the ''FFT Average option'' in the ''Average ''command) to disk (*.''fma)''
|-
| MAINFileOpen || close the current file and open a new file to which the remaining batch commands will be applied
|-
| MAINFileClose || close the currently open file in a batch, provided it is not the current file in the File List
|-
| MAINFilter || set filters
|-
| MAINfMRIArtifact || turns on the fMRI artifact removal
|-
| MAINGoTo || jumps with the cursor to the specified time point
|-
| MAINICA || starts ICA decomposition of data on the current screen
|-
| MAINICAsave || saves selected ICA components as topographies in a file
|-
| MAINICAselect || opens component selection dialog for managing ICA components
|-
| MAINImportASCII || import an ASCII file into a ''<nowiki>*.fsg</nowiki>'' file.
|-
| MAINMarkBlock || mark a data block (optionally send to Source Analysis)
|-
| MAINMarkChannels || mark one or more channels, as given by the list
|-
| MAINMaxInInterval || within the current marked block, search for the largest absolute value on the specified channel
|-
| MAINMontage || change the montage (used by the Export command when saving to current montage)
|-
| MAINParadigm || load a paradigm file
|-
| MAINPatternToTrigger || convert a tag into a trigger
|-
| MAINPolygraphicFilters || sets filters for polygraphic or added channels
|-
| MAINScale || set amplitude and time scales
|-
| MAINSearchAverageView || start search average view
|-
| MAINSendToMATLAB || send data to MATLAB
|-
| MAINSplineConstant || set the spline constant used in spherical spline maps and channel interpolation
|-
| MAINTriggerRecode || the command recodes a specified trigger number to a new number
|-
| MAINTriggerSelect || edit the trigger list (cf. ''Edit / Trigger Values''...)
|-
| MAINTriggerTagDelete || delete one or more triggers or tags
|-
| MAINViewAverageBuffer || turn on the Average Buffer View and place the specified buffer number to the left in the display
|-
| MAINViewChannelType || select the channel type to display, and select channel types for mapping, export, etc
|-
| MAINViewSelected || turns selected view on or off
|}

'''General commands for Source Analysis''' - prefixed with "'''SA'''" (but see also ''MarkBlock'', which is used to send a block of data to SA and open the SA window):

{| cellspacing="8"
| style="width: 180pt"| SAAddSource || add a dipole or regional source to a model
|-
| SAChannelTypeForFit || switch between EEG, magnetometers or axial gradiometers, and planar gradiometers
|-
| SAConvertSource || convert a source from dipole to regional source, or from regional source to dipole
|-
| SAcorticalClara || run Cortical CLARA
|-
| SAcorticalLoreta || run Cortical LORETA
|-
| SADelete || delete current solution or all solutions or remove current fit interval or cursor
|-
| SADICS || start DICS computation (if DICS has been precomputed in the time-frequency image command)
|-
| SADisplayMRI || switch MRI display on/off and select small or large window
|-
| SAElectrodeConfiguration || equivalent to pressing the Org or Std button in the Channel box of the Source analysis window
|-
| SAExit || close Source Module
|-
| SAFit || start fit
|-
| SAFitConstraint || set fit constraints, e.g. Residual Variance, Energy, Maximum Distance, Image Weighting, and their weights.
|-
| SAFitInterval || set fit or baseline interval
|-
| SAHeadModel || set the head model
|-
| SALabelSource || set the label of the specified source number
|-
| SAMinimumNorm || run a minimum norm analysis
|-
| SANewSolution || open a new solution
|-
| SAOpenSolution || open a solution from a file
|-
| SAPCA || toggle PCA display of data or residual, and transfer a selected number of components to the source model
|-
| SARegularization || set the regularization values both for discrete and distributed source images
|-
| SASaveBitmap || save a screenshot of the Source Analysis or the 3D window
|-
| SASaveLeadfields || save the leadfields of the current source model
|-
| SASaveModelWaveforms || save model waveforms
|-
| SASaveResidualWaveforms || save residual waveforms
|-
| SASaveRVandGFPWaveforms || save residual variance and global field power waveforms
|-
| SASaveSolution || save the current solution
|-
| SASaveSourceMontage || save a source montage
|-
| SASaveSourceWaveforms || save source waveforms
|-
| SASendToMATLAB || send data, model, source waveforms, images, etc. to Matlab
|-
| SASetCursor || set the cursor
|-
| SASetDefaultSourceType || set the default source type (dipole or regional source)
|-
| SASetOrActivateSource || Turn specified source on or off, or enable/disable source for fitting
|-
| SASetOrientation || set orientation (of regional source)
|-
| SASwitchCondition || switch to a specified condition
|}

'''Commands for Distributed 3D Volume Images'''

{| cellspacing="8"
| style="width: 180pt"| SAIMAGEBeamformer || switch between Single Source and Bilateral Beamformer image
|-
| SAIMAGEBeamformerTimeDomain || start beamformer computation in the time domain
|-
| SAimageBrainAtlas || turns on the Brain Atlas overlay on volumetric image
|-
| SAIMAGECLARA || generate CLARA image
|-
| SAIMAGEClip || clip image values under a threshold
|-
| SAIMAGEExport || save the results of minimum norm or 3D imaging method
|-
| SAIMAGEGotoMax || set the crosshair cursor at the nth maximum in the image
|-
| SAIMAGEImport || load a 3D volume image from file
|-
| SAimageImportFMRI || import fMRI image to Source Analysis Module
|-
| SAIMAGELAURA || create LAURA image
|-
| SAIMAGELORETA || create LORETA image
|-
| SAIMAGESLoreta || create sLORETA image
|-
| SAimageSESAME || start SESAME computation
|-
| SAIMAGESSLOFO || create SSLOFO image
|-
| SAIMAGEUser-Defined || create user-defined image
|-
| SAIMAGESaveLeadfields || save the leadfields of all the voxel sources in a 3D image
|-
| SAIMAGEClip || clip current 3D image
|-
| SAIMAGESmooth || smooth current 3D image
|-
| SAIMAGESetCrosshair || set the position of the crosshair in the 3D image
|}

'''Commands for Time-Frequency Analysis''' ('''TFC''')

{| cellspacing="8"
| style="width: 180pt"| TFCStartTFAnalysis ||(previously TFCgo) start TFC analysis using the current paradigm settings
|-
| TFCdisplay || change the TFC display (e.g. power/amplitude, coherence)
|-
| TFCsave || save numerical results to an ASCII file, or save a screenshot of the TFC window
|-
| TFCimage || start beamformer analysis on a selected time-frequency range
|-
| TFCSendToMATLAB || send TF results or single-trial data to MATLAB
|}

=== How to Average Your Data in a Batch ===

Using batch processing, several files from an experiment can be averaged at a time.

Here we summarize the steps required:

'''Before running the batch'''

* Create the paradigm, and save the paradigm file.
* Open each individual data file to check the data:
** Make sure auxiliary files are defined and loaded properly, and the data are displayed correctly.
** Eyeball the data.
** Define bad (and interpolated) channels.
** Mark artifact time ranges.
** If required, set up artifact correction for the file.
** The data file can be closed again after this step.

'''Preparing the batch'''

* Open at least one file and select ''Process / Batch Scripts''.... The file(s) should be displayed in the file list. Alternatively, just select ''Process / Batch Scripts...,'' and add the files by
** pressing the '''Add File''' button
** dragging the files from Windows Explorer
** Opening a previously saved list with ''Load File List''

* You can delete files from the list (press '''Del''') or edit the file sequence using the right click context menu.
* Select the ''Batch Tab''.
* Add commands to your script. For averaging, these would normally be
** '''Paradigm''' -- to load the paradigm file
** '''Artifact Scan''' -- to run the artifact scan
** '''Average''' -- to perform the average

* Save these commands (press '''Save Batch''').
* Test the commands on the files in the current file list: press '''OK'''
* Look at the log file (press '''View Log File''') to check the results of averaging.
* Look at the data averages to make sure they have been done correctly.
* Repeat these steps until averaging is working properly.

'''Running the batch'''

* Select ''Process / Batch Scripts''....
* Open the files you want to average in the batch in the file list:
** Any files that were open in BESA are included in the list
** Files can be added using the '''Add File''' button
** You may drag one or more files from Windows Explorer to the file list
** Alternatively, load a previously saved file list.

* Edit the file list, e.g. delete unwanted files (use the '''Del''' key or the right click context menu), or reorder the files (use '''Ctrl + cursor keys''' or context menu).
* Note that the order of files in the list specifies the order in which they will be processed in the batch script. This order will be important if all results are saved to the same target file. Otherwise the file sequence is not important.
* Optionally, save the file list (press '''Save Batch'''
* Select the ''Batch Tab'', and load the previously defined batch script with ''Load Batch''.
* Press '''OK''' to run the batch.

=== How to Merge and Compress raw data ===

Using the Export command in a batch, several data files can be merged into a single data file in BESA's data format ('''<nowiki>*.foc</nowiki>''').

This can be useful if data from one subject have been collected in several data blocks, and you want to analyze all data blocks together.

Optionally, to save space, data can be saved in compressed format.

'''Files can be merged:'''

* if they have identical channel configurations, or
* there are at least 16 EEG channels, and the export format is Standard 81 (i.e. EEG channels are interpolated to 81 standard locations).

'''How to merge files:'''

* Select '''Process / Batch Scripts...'''
* Add all the files that are to be merged to the file list:
** Any files that were open in BESA Research are included in the list
** Files can be added using the '''Add File''' button
** You may drag one or more files from Windows Explorer to the file list
** Alternatively, load a previously saved file list (''Load File List'').
* Rearrange the files in the file list to the sequence in which they should be merged.
* Select the ''Batch Tab ''and insert an "''Export"'' command, as described below.

The following dialog shows a possible configuration of the ''Export'' command:

[[Image:Batch processing (4).gif]]

* The parameters shown in the Information box are the settings chosen in the ''Export Dialog'' when the '''Select Options''' button has been pressed.
* '''Append if file already exists''' must be checked in order to merge the files.
* The '''target file name''' must be fixed, i.e. don't use the '''%basename%''' variable, because that will result in a different target file name for each source file.
* There are two variables that can be used for the segment label:
** '''%filename%''' will insert the basename of the source file into the segment label.
** '''%c%''' will insert the file number into the segment label. The number gives the position of the file in the file list. For instance, "File %c%" will generate the label "File 2" for the second file in the list.

=== Example: Data averaging in the auditory intensity experiment ===

In this example, two raw data files, '''s1.cnt''' and '''s2.cnt''', from the auditory intensity experiment will be batch averaged.

Please note that there are further tutorials covering this experiment. The first file is contaminated by many eyeblinks, and more epochs would be averaged if eye correction were used (see Viewlet demonstration on artifact correction on the BESA website). However, in this tutorial we will just use artifact rejection.

'''A. Various ways of creating a File List'''

1. '''Files that were open in BESA Research are automatically added to the File List.''' Start BESA Research and open the files '''s1.cnt '''and '''s2.cnt '''in the directory ''Examples\ERP-Auditory-Intensity''.

2. Select ''Process / Batch Scripts''.... You should see the file names in the '''''File List Tab''''' something like this:

[[Image:Batch processing (5).gif]]

3. You can resort the files in the file list alphabetically by clicking onto the '''''File List column header''''':

[[Image:Batch processing (6).gif]]

Alternatively, you can mark any file, hold down the '''Ctrl '''key and press the '''Up''' or '''Down arrow '''to move the file name up or down the list. This is the sequence in which files will be processed in the batch.

[[Image:Batch processing (7).gif]]

4. Press '''Save File List''' and save the list you have created to '''ERP-Aud-Ex1.flist'''.

5. Highlight both names and press the''' Del '''button to remove them from the list.

6. '''Files can be dragged from Windows Explorer'''. Start Windows Explorer and navigate to the ''ERP-Auditory-Intensity'' subdirectory of your BESA Research examples folder (located in the ''Public Documents'' folder of your computer). Click on '''s1.cnt''' and drag it with the mouse onto the '''''File List Tab'''''. Let go of the mouse. BESA Research opens the file, and displays the name in the File List. Repeat for '''s2.cnt.'''

7. Highlight both names and press the '''Del '''button to remove them from the list.

8. '''Files can be added using the ''Add File'' button'''. Press '''Add File''' and navigate to the ''Examples\ERP-Auditory-Intensity'' subdirectory. Select '''s1.cnt'''. Press '''Ctrl''' and select '''s2.cnt'''. Both names should then be displayed in the ''File Open'' dialog. Press '''OK''' to add the files to the file list.

9. Highlight both names and press the '''Del''' button to remove them from the list.

10. '''Files can be loaded from a previously saved file list'''. Press '''Load File List '''and select '''ERP-Aud-Ex1.flist''', the list you saved in step 6 above.

'''B. Setting up the batch'''

1. We will add three commands, '''Paradigm''', '''Artifact Scan''', and '''Average''', to create a batch that will be applied to the two files in the file list.

2. Click on the '''Batch Tab'''.

[[Image:Batch processing (8).gif]]

3. Press the '''Add Command''' button to obtain the ''Select Command'' window:

[[Image:Batch processing (9).gif]]

4. Click on '''Paradigm''' and then on '''OK''' (alternatively, double-click on '''Paradigm'''). Hit '''Browse''', navigate to the ''Auditory'' folder, and select '''AEP_Intensity.pdg''', the paradigm for the auditory intensity experiment.

[[Image:Batch processing (10).gif]]

5. Press '''OK''' to obtain the ''Load Paradigm Task'' window.

[[Image:Batch processing (11).gif]]

6. Press '''OK''', and the first task in the batch is ready, and listed in the Batch Command window. If you want to modify the command, double-click on it to open the above window, that allows to browse for a different paradigm file.

[[Image:Batch processing (12).gif]]

7. Next, we add the '''Artifact Scan''' command. Click on the '''Add Command''' button, and select ''Artifact Scan.''

[[Image:Batch processing (13).gif]]

8. Press '''OK''' to open the ''Artifact Scan Task'' window. We want to be able to view the results of the scan, and adjust thresholds and bad channels if necessary. Therefore, check the ''Wait after scan'' checkbox.

[[Image:Batch processing (14).gif]]

9. Press '''OK''' to close the ''Artifact Scan Task'' window. Our batch now contains two commands.

[[Image:Batch processing (15).gif]]

10. Finally, we will add an '''Average''' command. Press the '''Add Command''' button and select ''Average''. Press '''OK''' to open the ''Average Task ''window.

[[Image:Batch processing (16).gif]]

11. With the default settings, the average would be saved to the same directory as the data. The file name mask is set by default so that in this example the two averages would be saved to '''s1-av.fsg '''and '''s2-av.fsg'''. We will save the averaged files to subdirectory ''"Averages''" of the data directory. Uncheck the ''Use default target'' check box, change the File name mask to '''%basename%_av-test''' in order not to overwrite the predefined files.

[[Image:Batch processing (17).gif]]

12. Press '''OK '''to close the ''Average Task'' window. Our batch is now complete.

[[Image:Batch processing (18).gif]]

13. We will now save the batch so that it can be used again. Press the '''Save Batch''' button, and save to the file '''ERP-Aud-ex1.bbat'''. Note that an easy way to generate new averaging batches is to load a previously save batch and edit the commands -- it may only be necessary to edit the '''Paradigm''' command to select the relevant paradigm file, and maybe to adjust the target directory in the '''Average''' command.

14. Press '''OK''' in the ''Batch'' Window to start the batch running. As requested, the batch pauses after the artifact scan:.

[[Image:Batch processing (19).gif]]

You may now adjust the number of rejected trials, e.g. by moving the vertical red bar to the left, or exclude bad channels.

15. Press '''OK''' to continue with averaging.

[[Image:Batch processing (20).gif]]

16. Note that, in the background, the ''Batch Running'' window is providing feedback about the current file and current task.

[[Image:Batch processing (6).jpg|400px]]

17. The batch will stop again after the next artifact scan. Press '''OK''' to allow the batch to run to the end.

[[Image:Batch processing (21).gif|400px]]

18. Press '''View Log''' to view the batch protocol. If you are using Internet Explorer or Netscape family (Mozilla, Firefox) browsers, and JavaScript is enabled, you will first see just batch titles defined by the date and time the batch was started. The most recent title is at the top of the list. For other browsers, or if JavaScript was not enabled, all protocol texts are expanded as in 19 (below).

[[Image:Batch processing (22).gif|200px]]

19. Click on the first title to expand its protocol. Here, for example, the protocol gives feedback about the number of epochs that were averaged for each file.

[[Image:Batch processing (23).gif]]

20. Finally, press '''OK''' to return to the main BESA Research display. Open the averages in the ''Averages'' subdirectory to confirm that they were generated properly.

=== Example: Merging files using the Export Command ===

Here we will demonstrate the use of the '''Export '''command to merge two files. We will combine the two averages from the previous example (Data averaging in the auditory intensity experiment) into one target file.

'''A. Generate the file list'''

# Start BESA Research and load the two data files '''S1_av-test.fsg''' and '''S2_av-test.fsg''' that were saved in the previous example.
# Select ''Process / Batch Scripts....''The two file names should be displayed in the file list.
# In the file list, make sure that '''s1_av-test.fsg '''is the first file in the list. If it is not, highlight the file, and move it up using '''Ctrl+up''', or right click and select ''Move Up'' in the context menu.

'''B. Generate the batch'''

1. Press the '''Add Command''' button, and select the '''Export''' command.

2. Press '''OK''' to open the ''Export Task'' window.

[[Image:Batch processing (24).gif]]

3. Press the '''Select Options'''... button to open the ''Export Dialog''.

[[Image:Batch processing (25).gif]]

4. Since we are combining averages, select ''Hires (no compression)'' in the '''Target data format''' drop-down list (If we were merging raw data files, it is better to select compression. Press '''OK '''to close the dialog. Check'' Append if file already exists'', so that the files will be merged. Enter '''s1+s2''' in the target file name mask edit box. This ensures that both files will be saved to the same target: '''S1+S2.fsg'''.

[[Image:Batch processing (26).gif]]

5. Press '''OK '''to close the ''Export Task'' window. The '''Export '''command is displayed.  

[[Image:Batch processing (27).gif]]

6. Optionally, you may save the batch file by pressing '''Save Batch'''.

7. Press '''OK''' to run the batch, and '''OK''' in the ''Batch Completed'' window to return to the BESA main window.

8. Finally, open the file '''S1+S2.fsg''' to confirm that it contains the two merged files.

'''C. Merge raw data'''

# Repeat the above task to merge the two raw data files '''S1.cnt''' and '''S2.cnt''' into a single target file '''S1+S2.foc'''. In this case, select one of the compression options as the target data format. Note that you would not normally want to merge two files from different subjects. However, several data blocks from the same subject can conveniently be merged using this method.

Note that ''<nowiki>*.fsg</nowiki>'' files can also be merged using the ''Combine Conditions'' dialog. 

== Combine Conditions, Channels ==

=== Combine Condition Scripts ===

With the Combine-Conditions module you can do a variety of operations on BESA averages (files with the extension '''<nowiki>*.fsg</nowiki>''', and other segment files, such as '''<nowiki>*.mul</nowiki>''', '''<nowiki>*.avr</nowiki>''', '''<nowiki>*.swf</nowiki>'''):

* Create grand averages
* Combine averages (add, subtract, weighted/unweighted)
* Merge files
* Exclude unwanted averages
* Rename conditions
* Rename or resort channels
* Generate averages or differences over selected channels
* Transform the data: standard interpolated 81 electrodes, change sampling rate, change interval
* Determine peaks, mean amplitudes, or integrals on data averages
* These operations can be performed on one or more files simultaneously. Results of an operation are stored in a single target file.

The module includes four tabbed windows:

* File List: Define a list of files on which the operations will be performed.
* Condition List: List the condition names, define target condition names, and how input conditions are combined into target conditions.
* Channel List: List the channel names, define target channel names, and how input channels are combined into target channels.
* Run Scripts: Define global options for the output (e.g. spatial interpolation, resampling, copy/merge or average, peak analysis). Start the operation.
* Note that in all four tabs, configurations can be saved for future use, and the '''Load Previous''' button restores the most recently used configuration.

=== Condition List Tab ===

List the condition names, define target condition names, and how input conditions are combined into target conditions.

The first column of the list box shows a list of all the condition names found in the source files.

Rows of the list box define the source conditions. Columns define the target conditions.

'''Initial setting'''

When first selecting the tab, each column shows each condition name found in the source files (as in the example below). In the list box, there is a "+1" along the diagonal. The result of this selection is that target conditions will have the same name as source conditions. Right click on source condition labels to view properties (e.g. no. of samples, time range, sampling rate).

[[Image:Batch processing (28).gif]]

'''Editing the condition list'''

* Target condition names can be edited, inserted or deleted by clicking on the label at the top of each column.
* Click on a box within the list to toggle between "+1", "-1" and blank. These correspond to the operations:
** "+1" = add
** "-1" = subtract
** blank = do nothing
* Right click on a box for further operations: conditions can be weighted by a given factor other than 1.

'''Divide result by sum of PLUS factors'''

* Normally, when creating an average over conditions, the sum is divided by the number of conditions, or a weighted average is generated (see below).  If "''Divide the result by the sum of PLUS factors''" is unchecked, the conditions will be summed rather than averaged.
* Note that, when making differences between conditions, no such division is required. BESA Research will uncheck the checkbox automatically if subtraction ("-1") is specified somewhere in the condition list.

'''Weighting of averages'''

* Below the list, click on the ''Weighted Average'' row to toggle "YES" and "NO". "YES" means that averages will be weighted by the number of epochs contributing to the average. For instance, if average A contained 100 epochs and average B contained 200 epochs, the weighted average will be computed as

<div style="margin-left:1cm;margin-right:0cm;">(100 * A +  200 * B) / (100 + 200)</div>

<div style="margin-left:1cm;margin-right:0cm;">Select "NO" for an unweighted average. For the above example, the average is computed as</div>

<div style="margin-left:1cm;margin-right:0cm;">(A + B) / 2</div>

<div style="margin-left:1cm;margin-right:0cm;">Weighted averages are not permitted if one of the boxes contains a negative value.</div>

* Values other than +1 or -1 in the boxes apply a different kind of weighting. For instance, we want to compute the difference between the means of conditions A, B, C and D, E. Use a right-click to specify the fraction 1/3 for each of A, B, and C, and -1/2 for each of D and E (see example below).

[[Image:Batch processing (29).gif]]

'''Save the current condition list'''

* Press the '''Save Condition List''' button.

'''Load a condition list'''

* Press the '''Load Condition List''' button.

'''Load previous settings'''

* Press the '''Load Previous''' button

'''Feedback'''

* Conditions that have different numbers of electrodes (averaging across different files) can only be combined if channels are interpolated to a standard set of electrodes.
* Conditions that have different durations or sampling rates can only be combined if the sampling rate and durations are made the same.
* Feedback about the above situations is displayed by the presence of tick marks above the list box.

=== Channel List Tab ===

List the channel names, define target channel names, and how input channels are combined into target channels.

Note that this tab is very similar in usage to the '''Condition List Tab'''. Note also that some of the functions performed in this tab could also be done in the Montage Editor. It may be a matter of convenience whether you choose to perform these operations here or in the Montage Editor.

The first column of the list box shows a list of all the channel names found in the source files.

Rows of the list box define the ''source'' channel. Columns define the'' target'' channel.

'''Initial setting'''

When first selecting the tab, each column shows each channel name found in the source files (as in the example below). In the list box, there is a "+1" along the diagonal. The result of this selection is that target channel will have the same name as source channel.

'''Combining files'''

If files with different channel configurations are included in the File List, the rows and columns of the Channel List Tab will only contain the labels for the channels that are in common among the files.

If the files in the File List have a different sequence of channels, the sequence of the first file in the list will be adopted in the Channel List.

Thus, for the initial setting, unless the "''Ignore Settings in this Tab''" checkbox is checked, the target grand average or peak/amplitude analysis, etc. will be applied using only channels that are in common among the input files, and using the channel sequence of the first file in the File List. By changing the target channels or by changing the entries in the Channel List, new channels consisting of averages or differences can be generated.

'''What can the Channel List be used for?'''

Some examples:

* Reorder or relabel channels
* Create channel differences
* Create averages over channel groups, e.g. for peak analysis
* Extract a selection of channels for peak analysis or mean amplitudes
* Create grand averages across files with different channel configurations, just using channels in common among the files

[[Image:Batch processing (30).gif]]

'''Editing the channel list'''

* Target channel names can be edited, inserted or deleted by clicking on the label at the top of each column.
* Click on a box within the list to toggle between "+1", "-1" and blank. These correspond to the operations:
** "+1" = add
** "-1" = subtract
** blank = do nothing
* Right click on a box for further operations: channels can be weighted by a given factor other than 1.

'''Divide result by sum of PLUS factors'''

* Normally, when creating an average over channels, the sum is divided by the number of channels, or a weighted average is generated (see below).  If "Divide result by the sum of PLUS factors" is unchecked, the channels will be summed rather than averaged.
* Note that, when making differences between channels, no such division is required. BESA Research will uncheck the checkbox automatically if subtraction ("-1") is specified somewhere in the channel list.

'''Save the current channel list'''

* Press the '''Save Channel List''' button.

'''Load a channel list'''

* Press the '''Load Channel List '''button.

'''Load previous settings'''

* Press the '''Load Previous''' button

=== Run Scripts Tab ===

Define global options for the output (e.g. spatial interpolation, resampling, copy/merge or average, peak detection. Start the operation.

[[Image:Batch processing (7).jpg]]

'''Load or Save Settings'''

* You can save the current settings of this tab to a file (*.run) which can be loaded later.
* When you run the script, the current settings are saved automatically to a file "'''PreviousSettings.run'''".

'''Load Previous'''

* Press this button to load the previous settings (from "'''PreviousSettings.run'''").

'''Averages to Generate'''

* '''Generate separate averages for each source file'''. Averages are performed over conditions within the source file, and are then appended to the target file.
* '''Combine data from source files'''. Conditions are combined over all source files into a single target average.
* '''No averages, just copy'''. Files are copied and merged to the target file. Use this option for renaming conditions, merging files, removing unwanted averages (see below), changing the sampling rate and interval.
* '''Peaks and mean amplitudes'''. Specify time ranges for peaks, mean amplitudes, or integrals (areas).
* Note: When generating or copying averages (first three options), filters and baseline settings are turned off. For Peaks and mean amplitudes, filters and baseline settings are specified in the dialog.

'''Spatial Interpolation'''

* '''Interpolate to Standard 81 electrodes'''. The target file will contain only electrodes (other channels are omitted), using the Standard 81 configuration (as in other export functions within BESA Research). This cannot be selected if the source data contain less than 16 EEG channels.
* '''Interpolate Bad Channels'''. Bad electrode channels in the source file will be interpolated. If the above option is deselected and bad channels exist in one or more of the source files, this option is always on.

BESA Research can interpolate EEG, and MEG if the sensors are axial gradiometers or magnetometers. If other channels are marked as bad in one or more of the source files, these will be defined as bad in the target file. This applies to MEG planar gradiometers, to polygraphic data, and to ICR channels.

'''Temporal Interpolation'''

* '''Spline to New Sampling Rate and Interval'''. Data can be converted to a new sampling rate, and the interval can be changed.
** If the sampling rate is reduced, the data will be low-pass filtered at 1/3 sampling frequency before reduction.
** If the sampling interval is changed, the prestimulus and poststimulus intervals are limited by the smallest intervals in the conditions contributing to the averages. These limits are shown below the edit boxes.

'''Peaks and Mean Amplitudes'''

[[Image:Batch processing (31).gif]]

'''Peaks:'''

* Select the time range between which peaks are to be determined.
* Select the montage on which the peaks are to be determined.
* Define the filter settings.
* Define the baseline settings.
* Specify whether peaks are to be defined at one latency: if so, select the channel on which peaks are to be detected.
* Specify whether you want to find positive or negative peaks.

'''Mean amplitudes and areas:'''

* Select the time range over which the mean amplitudes or areas are to be determined.
* Select the montage on which the mean amplitudes or areas are to be determined.
* Define the filter settings.
* Note that when computing areas, data are first rectified (made positive) and then summed over the time range.

'''Output options of the analysis:'''

* A single ASCII file that contains the result of the analysis for all data sets, conditions, and channels including header and information lines.
* A sparse output suitable for import in SPSS. Each variable (e.g. a latency, a channel amplitude) constitutes one column of the output file.
* Direct transfer to MATLAB into a struct besa_peak. For more information on the data transfer from BESA Research to MATLAB, please refer to help chapter ''“The MATLAB interface”.''

'''Starting the Operation'''

* Press '''OK''' to start the operation. After the operation is completed, and the "Open target file in BESA" box is checked, BESA Research will open the target file.  "Open target file in BESA" cannot be checked if "Peaks and mean amplitudes" was selected - then the result of the operation will be an ASCII file or a MATLAB transfer.
* You will be asked for the name of the target file (unless a MATLAB transfer of peak data has been performed).

'''Restrictions'''

* Depending on source file configurations, not all options above are selectable. For instance, if two files contain different numbers of electrodes, and the "''Ignore Settings in this Tab''" checkbox is checked in the '''''Channel List''''' Tab, spatial interpolation to Standard 81 is enforced in the target. Similarly, if different sampling rates are used in different files, temporal interpolation is enforced.
* You are not allowed to add files to the file list if the channel configuration is different, and the data cannot be combined with Standard 81 interpolation. Since Standard 81 interpolation is only possible for EEG, multiple files without EEG can only be loaded if they have the same number of channels.

=== How to Create Grand Averages ===

* Open the files you want to average in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. To average across different conditions, click in the list boxes to obtain "+1" for each source condition to combine, and rename the target condition to define a meaningful name for the average.
* Click on the '''Run Scripts Tab'''.
* If you have more than one file, specify whether averages should be generated across files ('''Combine data from source files''') or within files ('''Generate separate averages for each source file''').
* Select other options if required (spatial or temporal resampling).
* Press '''OK'''.

=== How to Generate Differences Between Conditions ===

* Open the files you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. To create differences, click in the list boxes to obtain "+1" for one of the source conditions, and "-1" for the source condition to subtract, and rename the target condition to define a meaningful name for the difference.
* Click on the '''Run Scripts Tab'''.
* If you have more than one file, specify whether averages should be generated across files ('''Combine data from source files''') or within files ('''Generate separate averages for each source file''').
* Select other options if required (spatial or temporal resampling).
* Press '''OK'''. An average of the differences is generated. If only one example of each condition exists, e.g. in a grand average file, the result is the difference between conditions.

=== How to Merge Files ===

* Open the files you want to merge in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions''...).
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press '''OK'''.

'''Notes'''

* If the source files have different electrode configurations, use the Standard 81 configuration for the target.
* If the source files have different sampling rates or intervals, use Temporal Interpolation.

=== How to Remove Unwanted Averages ===

'''Removing one or more unwanted segments'''

* Normally, all conditions are read from a source file. To exclude one or more segments from operations in the Combine Conditions module, mark the segments as artifacts in the main program display. It is sufficient for the beginning or the end of an artifact interval to be within the segment for the segment to be excluded.
* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press''' OK'''.
* The target file contains the copied data without the conditions that were marked as averages.

'''Removing one or more unwanted conditions (by label)'''

* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Deselect the target conditions you want to omit (replace the "+1" by a blank).
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press''' OK'''.
* The target file contains the copied data without the conditions that were marked as artifacts.

=== How to Rename Conditions ===

* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions''...).
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. Click on column headings to rename the target conditions.
* Click on the''' Run Scripts Tab'''. Select "''No averages, just copy''".
* Press '''OK'''.
* The target file contains the copied data with the renamed conditions.

=== How to Change the Sampling Rate ===

* Open the file(s) you want to change in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...'').
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Select "''Spline to New Sampling Rate and Interval''" and type the new sampling rate into the edit box.
* Press '''OK'''.

=== Example: Create grand average and combinations of conditions ===

In this example, we will generate a grand average of the results of the Auditory Intensity Experiment. The experiment includes averages from five different stimulus intensities. We will create a grand average over each intensity, but also include means over the two lowest and the two highest intensities, and the difference between these two combinations.

'''A. File selection'''

# Start BESA Research and open files '''S1_av.fsg - S10_av.fsg''' in the ''Examples\ERP-Auditory-Intensity'' folder. The files contain the individual averaged data of the 10 subjects who participated in this study.
# Select ''ERP / Combine Conditions...'' The file list should display the two files, with feedback about the number of averages and conditions. 8 epochs are found. See the ''“Data averaging in the auditory intensity'' ''experiment”'' example for examples how to manipulate the file list.

[[Image:Batch processing (32).gif]]

'''B. Define conditions'''

1. Click on the '''Condition List Tab'''. The initial window defines target conditions with the same name as the source conditions. To generate the grand average over these conditions we could proceed without further changes to the '''Run Scripts Tab'''. However, we want to modify the condition list and create a condition that contains the grand averaged difference between the''' High''' and '''Low''' conditions.

[[Image:Batch processing (8).jpg]]

2. Click on the '''All '''column label. In the resulting window, rename condition '''All''' to''' Difference'''. Then press '''OK'''.

[[Image:Batch processing (33).gif]]

3. The last column is now labeled '''Difference.''' Left-click twice onto the ‘'''+1’''' entry that links this condition to the '''All '''input condition. This will remove the link and leave the field blank. To define the ‘Difference’ condition as the average of ‘High’ minus ‘Low’ over subjects, left-click once into the field linking input '''High''' with target '''Difference''' to generate an entry ‘'''+1’''' in this field. Left-click twice into the field linking input '''Low '''with target '''Difference''' to generate an entry '-'''1'''’.

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;">[[Image:Batch processing (35).gif]]</div>

4. Press '''Save Condition List''' and save the list to '''ERP-aud-ex1.clist'''. This condition combination can thus be loaded later using the '''Load Condition List''' button.

'''C. Run the script'''

# Click on the '''Run Script Tab'''.
# The default tab settings are ready for generating the grand average ('''Combine data from source file''' and '''Open target file in BESA''' should be checked). Just press '''OK'''. Enter '''All_Subjects_cc-test.fsg''' as file name and press''' Save'''.

The resulting file contains the 8 target conditions, 60db, 70dB, 80dB, 90dB, 100dB, Low, High, and Difference.

=== Example: Average files from different experiments ===

This example is intended to illustrate several features of the ''Combine Conditions'' Dialog, such as electrode interpolation and resampling. We will combine an average from the Auditory Intensity experiment with one from the P300 auditory experiment. In this particular case, it is not a very meaningful thing to do, but it shows what is possible. For instance, the same experiment may have been performed using different sampling rates or electrode combinations. This example shows how such data may be combined.

'''A. File selection'''

# Start BESA Research and open the file '''All_Subjects_GA.fsg''' in the ''Examples\ERP-Auditory-Intensity'' folder. The file contains the grand average data from the auditory intensity experiment.
# Open the file '''RareFrequentResponseLeft.fsg''' in the ''Examples\ERP-P300-Auditory'' folder. This file contains averages from the P300 auditory experiment.
# Select ''ERP / Combine Conditions... ''Note that the files have different sampling rates and different numbers of electrodes.

[[Image:Batch processing (36).gif]]

'''B. Define conditions'''

1. Click on the '''Condition List Tab'''. Note that the feedback text at the bottom of the window displays the text "Standard 81 interpolation required to generate average; Across files: resampling or change in time range required to generate average". The condition labels show all the names from both files.

[[Image:Batch processing (37).gif]]

2. We will exclude most conditions, and just combine the most similar conditions from the two experiments: the "Standard" and the "80dB" conditions. Click on the title of the first column,''' Blink'''. Select “''Delete all conditions to the right of this column”'', and press '''OK'''.

[[Image:Batch processing (38).gif]]

3. Click on the title again, and rename the target condition to "Standard".

[[Image:Batch processing (39).gif]]

4. Click twice in the first line to remove the "+1" entry there. Click once in the third row ("Frequent"), and in the 7th row ("80dB"), to display "+1" at each entry. Thus, just two of the conditions will be combined into one target condition.

[[Image:Batch processing (40).gif]]

'''C. Run the script'''

1. Click on the '''Run Script Tab'''.

[[Image:Batch processing (41).gif]]

2. Note that '''Interpolate to Standard 81 electrodes''' is checked and grayed: since two different electrode sets are to be combined, we can only do this by interpolating electrodes. Also, both '''Spline to new sampling rate''' and '''Clip interval '''are checked and grayed. Again, these settings are required in order to be able to average the two data files together. The sampling rate is set to the higher of the two selections. The time range is set to the largest possible range that can be clipped from the two data sets. For now, leave these settings as they are, and press '''OK'''. Save the target to '''TestCombineExpts_CC-std81.fsg'''.

{{BESAManualNav}}

BESA Research Batch Processing

2021-05-05T07:45:10Z

Abinash: /* Batch Commands */

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = 6.1 or higher
}}



== Combine Conditions and Batch Module: Introduction ==

Functions of this module are started by selecting the menu operations "'''ERP / Combine Conditions...'''" and "'''Process / Batch Scripts...'''".

* '''Combine Condition Scripts''' provides various operations on BESA averages.
* '''Batch Scripts''' provides batch operations on all data files.
* Note that a batch script can also be performed on the current file by selecting "'''Process / Run Batch...'''" or by typing the shortcut key "'''R'''".

== File List Tab ==

Define a list of files on which the operations will be performed. The tab is the same for Combine Conditions Scripts and for Batch Scripts. Combine Conditions Scripts only allows you to open BESA average files (e.g. '''<nowiki>*.fsg</nowiki>''' and '''<nowiki>*.avr</nowiki>''', but also '''.mul''', '''.raw''', '''.swf''', and '''.foc''' if the files have a defined pre-stimulus interval), whereas Batch Scripts allows you to open any data file whose format is known to BESA Research.

When the Combine-Conditions or the Batch module is started, all currently opened (Combine-Conditions: averages only) files are displayed in the list.

To the right of each file name, the number of electrodes, total number of channels, and the sampling rate used in the file are displayed. In the Combine-Conditions module, the number of Epochs (segments) and the number of differently-named conditions are also shown.

'''Add files to the list'''

* Press the '''Add File ''' button.
* Drag one or more files from Windows Explorer onto the window.

'''Remove files from the list'''

* Right click on the file name and confirm the delete operation in the resulting dialog.
* Mark one or more file names in the list (e.g. hold down the''' Ctrl''' key to mark multiple files). Right click to obtain the context menu and select "'''Delete'''", or just press the '''Del '''key.

'''Reorder files within the current file list'''

* Right click on the file name and select "'''''Move Up'''''" or "'''''Move Down'''''".
* Mark one or more file names in the list (e.g. hold down the '''Ctr'''l key to mark multiple files). Right click to obtain the context menu and select "'''''Move Up'''''" or "'''''Move Down'''''", or hold down the''' Ctrl''' key '''and '''press the '''Up''' and '''Down arrows'''.

'''Sort the current file list alphabetically'''

* Click on the File bar above the list

'''Save the current file list'''

* Press the '''Save File List''' button.

'''Load a file list'''

* Press the '''Load File List''' button, or the '''Load Previous''' button to load the most recently used file list.

'''Which conditions are read from a source file? (Combine-Conditions module only)'''

* Normally, all conditions are read from a source file. To exclude one or more segments from operations in the Combine Conditions module, mark the segments as artifacts in the main program display. It is sufficient for the beginning or the end of an artifact interval to be within the segment for the segment to be excluded.

'''File list from Combine Conditions:'''

[[Image:Batch processing (1).png]]

'''Don't try to open here... (Batch only)'''

By default, this checkbox is unchecked.

In the checked state, BESA Research doesn't check if it can open the file. Use this function '''only''' if the file is ASCII and you want to use the '''ImportASCII '''batch command.

'''File List from Batch Scripts''':

[[Image:Batch processing (2).png]]

== Batch Processing ==

=== Batch Processing Scripts ===

With Batch Scripts, you can define a set of operations (e.g. Artifact Scan, Average, etc.) and apply these to several data files.

These operations include

* Load Paradigm
* Artifact Scan
* Average
* Export (and Merge)
* File Open (switch to another data file)
* Set filters
* Specify a montage (used, for example, for export to current montage)
* Run automatic eye and EKG artifact correction
* Define artifact topographies
* Turn artifact correction and view on and off
* Read and write events
* Edit default block epoch (for export around triggers)
* Edit triggers (for export around triggers)
* Mark a block for export, or send the block to Source Analysis or Top View
* Convert patterns to triggers
* Attach auxiliary files (e.g. elp, sfp) to the data file
* Send to MATLAB
* Specify display configurations for the BESA Research Main, SA, and Top View windows
* and more - see the full list of [[Batch Commands]]

An additional set of commands are available for operations in the '''Source Analysis Module''', allowing to load, create and fit dipole models, and save the results.

A further set of commands apply to '''Time-Frequency Analysis''', allowing to start TFC, change the display, save results, and run the beamformer or DICS analyses on a selected time-frequency range.

[[Image:Batch commands1.png]]

These operations will be extended in future program releases.

The module includes two tabbed windows:

* '''File List''': Define a list of files on which the operations will be performed.
* '''Batch''': Define or load '''batch commands'''. Run the batch.

=== Batch Tab ===

Load or define batch commands, and then apply them to the files in the File List.

[[Image:Batch processing (4).png]]

'''Add Command'''

* Press '''Add Command''' to add a new command to the batch. The following dialog is opened, showing the available commands:

[[Image:Batch commands1.png]]

* Select the desired command and press '''OK''' or double-click on the command. A dialog box is opened, allowing to specify individual command parameters.
* If you click on "Apply at beginning of batch" or "Apply at end of batch", the command will only be run at the beginning or the end of a batch. You can use this, for example, at the end of a batch to start a MATLAB script to perform statistics on the results of the batch.

'''Load and Save Batch'''

* Press '''Load Batch''' to load a previously defined batch or '''Save Batch''' to save the current batch to a file ('''<nowiki>*.bbat</nowiki>''').

'''Load Previous'''

* Press '''Load Previous''' to load the most recently used batch file. Whenever a batch is run, the current set of commands is written to the file '''Previous.bbat in''' the '''Scripts/Batch''' subdirectory. This file is loaded when you press '''Load Previous'''.

'''Clear All'''

* Clears all commands from the window.

'''View Log File'''

* Each time a batch is run, BESA Research adds information about the batch to a log file, with headings showing the date and time the batch was started. The file is opened automatically in Internet Explorer if errors occurred during processing. Otherwise you may open the file by pressing the '''View Log File''' button here or in the dialog that is displayed at the end of batch processing. 
* The log file is saved in xml format, and a JavaScript is used to format the display in web browsers. JavaScript should be enabled in the browser to obtain an optimal display of the results. If JavaScript is enabled, the log file is displayed as a list of headings for each batch. Click on a heading to display the results of the corresponding batch.
* To open the log file in the Notepad, hold the''' Shift '''key down when pressing the '''View Log File''' button.

'''Batch Command List'''

* Double-click on a command to edit it. See [[Batch Commands]] for descriptions of the dialogs that are opened to edit each command.
* Right click on a command to open a context menu allowing more options.

[[Image:Batch processing (5).png]]

* '''Delete''', '''Move Up''', '''and Move Down''' can also be applied to multiple selections.
* If you have made a multiple selection, the '''Del '''button will delete all the marked commands. '''Ctrl '''plus '''Up''' or '''Down''' '''cursor keys''' will move the marked commands up or down.
* '''Toggle Comment''' will add or remove a semicolon (;) in front of the command, to deactivate or reactivate the command.
* '''Toggle Command Only at Start/End''' will add or remove the text "Start_" or "End_" in front of the command. With these prefixes, the command will only be performed when the first file ("Start_") or the last file ("End_") in the file list is being processed.

'''Single Step Mode'''

* Check this item to step through the batch, one command at a time. A dialog is opened after each command, allowing to run the next command, continue the batch without single steps, or stop running the batch. See the'' “Pause''” command for further details.
* During a batch, press and hold down the '''Pause''' or '''Delete''' key to interrupt the batch and enter Single Step Mode. Press and hold down the '''Esc''' key to cancel the batch.

'''Changes in batch written to database'''

* Checked by default. If this item is unchecked, file display settings, such as Montage setting and Artifact correction display, are not written to the database. When the file is next opened in BESA Research, the settings made in the batch are not retained.

'''Leave files in the file list open after running the batch'''

* If this item is checked, files in the file list will remain open after the batch. This is useful, for instance, if you want to open a set of files, specifying the same montage and/or filter settings for each file.

Press '''OK''' to start running the batch. Each command is then applied in succession to each file in the File List.

Note that, while a batch is running press and hold down the''' Pause''' or '''Delete''' key to interrupt the batch and enter Single Step Mode. Press and hold down the '''Esc''' key to cancel the batch.

=== The log file ===

A protocol of each batch is written to the log file '''Scripts/Log/Batch.xml.'''

When you press the '''View Log File '''button, the file is opened in your default browser for xml files. The file will be opened automatically if there was an error during batch processing, unless you have used the ''BatchError'' batch command to suppress this behavior.

'''DHTML formatting of the log file'''

The xml file is formatted using JavaScript (Dynamic HTML). If JavaScript is enabled in your browser, you will first see a list of batch protocol titles, labeled by the date and time at which the batch was started. The most recent batch is at the top of the list.:

[[Image:Batch processing (6).png|200px]]

Click on the title to view the protocol for the corresponding batch:

[[Image:Batch processing (7).png|600px]]

'''JavaScript and XP Service Pack 2'''

By default, if the log file is opened in Internet Explorer after XP Service Pack 2 has been installed, IE will warn you with the message: "''To help protect your security, Internet Explorer has restricted this file from'' ''showing active content that could access your computer".'' All the protocols in the log file are displayed. You may safely click on the options to allow active content in the log file, if you want to display the file as described above.

'''Backup of the log file'''

When the log file is written, a backup of the previous version is written to '''batch.xml.bak'''.

If the size of the log file exceeds 200 KB, it is renamed to '''batch.xml_date_time''' (e.g. '''Batch.xml_2004-10-08_10-53-32'''), and a new version of '''batch.xml''' is created.

=== Placeholders ===

A powerful feature of the batch commands is the ability to define file names and specify standard paths using placeholders. These are text strings enclosed by percentage (%) signs. They can be used in all batch commands where file names are specified.

'''Basename'''

{| class="wikitable"
! Placeholder !! Description !! Example
|-
|style="text-align:center;" width="10%"|'''%basename%'''
|width="40%"|replaced by the basename of the currently opened file.
|width="40%"|If the data file is named "f-spike.fsg", "%basename%-export.fsg" will be interpreted as "f-spike-export.fsg".
|-
|style="text-align:center;"|'''%basename-n%'''
|replaced by the basename of the currently opened file, but removing the last "n" characters from the name.
|If the data file is named "dongle-BB.fsg", "%basename-3%" will be replaced by "dongle", because the last 3 characters of the basename have been removed.
|-
|style="text-align:center;"|'''%-nbasename%'''
|replaced by the basename of the currently opened file, but removing the first "n" characters from the name.
|If the data file is named "BB-dongle.fsg", "%-3basename%" will be replaced by "dongle", because the first 3 characters of the basename have been removed.
|-
|style="text-align:center;"|'''%orgbasename%'''
|replace by basename of the current file in the file list (it has the same meaning as %basename% if no MAINFileOpen batch command was used in command list)
|
|-
|style="text-align:center;"|'''%base%'''
|replace by basename of the current file without the path
|
|-
|style="text-align:center;"|'''%orgbase%'''
|replace by basename of the current file in the file list without the path
|-
|style="text-align:center;"|'''%ext%'''
|replace by extension of the current file
|
|-
|style="text-align:center;"|'''%orgext%'''
|replace by extension of the current file in the file list
|
|-
|style="text-align:center;"|'''%basefolder%'''
|replace by folder of the current file
|
|-
|style="text-align:center;"|'''%orgbasefolder%'''
|replace by folder of the current file in the file list
|
|-
|style="text-align:center;"|'''%t%'''
|Log batch command only: time since start of batch on current file
|
|-
|style="text-align:center;"|'''%T%'''
|Log batch command only: current date and time
|
|-
|style="text-align:center;"|'''%label%'''
|Replace label of the most recent marked block by the block label, not including no. of averages
|
|-
|style="text-align:center;"|'''%LABEL%'''
| Replace label of the most recent marked block by the block label, including no. of averages

|
|-
|style="text-align:center;"|'''%scripts%'''
|replaced by the path to the Scripts folder.
|"%scripts%Batch" is where batches are saved by default; "%scripts%MATLAB" is the location of the standard MATLAB scripts used by BESA Research.
|-
|style="text-align:center;"|'''%montages%'''
|replaced by the path to the Montages folder.
|
|-
|style="text-align:center;"|'''%examples%'''
|replaced by the path to the Examples folder.
|
|}



'''Placeholders for folders'''

The following placeholders are the same as those used in the [Folders] section of '''Besa.ini''':

The strings enclosed by percent signs (%) are placeholders for the following folders in English-language versions of Windows. Folder names are different for the system and for other language settings. BESA Research will substitute the placeholders by the appropriate folder name for the Windows system and the system language:

* '''Windows 10 (English)'''

<div style="margin-left:1.27cm;margin-right:0cm;"> '''%localapp%''' = ""C:\Users[user]\AppData\Local\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Desktop as ""Desktop[user]\AppData\Local\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;"> '''%publicprog%''' = "Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = ""C:\Users\[user]\Documents\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as "Desktop\[User]\Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as''' %progdir%'''</div>

* '''Windows 7 (English):'''

<div style="margin-left:1.27cm;margin-right:0cm;">'''%localapp%''' = "C:\Users\[user]\AppData\Local\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Desktop as "Desktop\[user]\AppData\Local\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%publicprog%''' = "C:\Users\Public\Public Documents\BESA\Research_7_1". This folder is directly accessible from the Windows Explorer under "Libraries\Documents\Public Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = "C:\Users\[user]\Documents\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as ""Libraries\Documents\My Documents\Research_7_1" or "Desktop\[User]\My Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as''' %progdir%  '''</div>

=== Batch Commands ===

Batch commands are selected when the "'''Add Command'''" button is pressed in the "Batch" Tab. The commands are subdivided into five categories: General commands, commands for the Main module, for the Source Analysis module, imaging commands in the Source Analysis module, and commands for Time-Frequency Analysis. The commands have prefixes,''' GEN''', '''MAIN''',''' SA''', '''SAIMAGE''', and''' TFC'''), which identify the category. For compatibility with older program versions, old batches without the prefixes are accepted.

Detailed descriptions of each batch command are available in the electronic help chapter “''Batch Processing and Combining Conditions / Batch Processing / Batch Commands”.''

'''General commands''' - prefixed with "'''GEN'''" (can be used anywhere):

{| cellspacing="8"
| GENBatchError || used to change program behavior when errors occur
|-
| GENBatchWindowPosition || set the position of the batch window relative to the main window
|-
| GENComment || comment in the batch script: no batch functionality
|-
| GENMATLABcommand || send a command string to MATLAB
|-
| GENMATLABwaitForVariable || tells BESA to wait until Matlab has created a variable with the specified name.
|-
| GENPause || pause batch operations, allowing step-by-step operations
|-
| GENFor/GENEndFor|| a programming language-like FOR loop
|-
| GENRunProcess || runs a command line process, e.g. an external program to perform part of the data analysis in the batch
|-
| GENsaveBitmap || save a screenshot of the Source Analysis or the 3D window
|-
| SetVariable || the value of the variable is inserted into subsequent batch commands where the text contains the name flanked by % signs
|-
| GENWindowPosition || set window size and positions to a selection of standard settings, e.g. for bitmap export
|}

'''Commands for the Main Module''' - prefixed with "'''MAIN'''":

{| cellspacing="8"
| MAINArtifactCorrect || run automatic artifact correction
|-
| MAINArtifactMethod || specify the method for artifact correction
|-
| MAINArtifactOn || turn artifact correction an artifact view on or off
|-
| MAINArtifact Scan || run an artifact scan as from the Paradigm Dialog
|-
| MAINAuxiliaryFiles || associate auxiliary files (e.g. *.''ela'', *.''sfp'') with the data file
|-
| MAINAverage || average the data
|-
| MAINBaseline || specify the parameters for baseline correction
|-
| MAINDefineArtifactTopography || define an artifact topography
|-
| MAINEditDefaultEpoch || edit the default block epoch
|-
| MAINEventRead || read events from an ASCII event file
|-
| MAINEventWrite || write events to an ASCII event file
|-
| MAINExport || export or append data in the selected target format
|-
| MAINExportToBESAConnectivity || export data segments to BESA Connectivity
|-
| MAINFFT || calculates the FFT spectrum of the marked data interval
|-
| MAINFFTmean || starts an averaging procedure which calculates the mean spectral properties in pre-defined regions
|-
| MAINFFTsave || saves FFT data (generated using the ''FFT Average option'' in the ''Average ''command) to disk (*.''fma)''
|-
| MAINFileOpen || close the current file and open a new file to which the remaining batch commands will be applied
|-
| MAINFileClose || close the currently open file in a batch, provided it is not the current file in the File List
|-
| MAINFilter || set filters
|-
| MAINfMRIArtifact || turns on the fMRI artifact removal
|-
| MAINGoTo || jumps with the cursor to the specified time point
|-
| MAINICA || starts ICA decomposition of data on the current screen
|-
| MAINICAsave || saves selected ICA components as topographies in a file
|-
| MAINICAselect || opens component selection dialog for managing ICA components
|-
| MAINImportASCII || import an ASCII file into a ''<nowiki>*.fsg</nowiki>'' file.
|-
| MAINMarkBlock || mark a data block (optionally send to Source Analysis)
|-
| MAINMarkChannels || mark one or more channels, as given by the list
|-
| MAINMaxInInterval || within the current marked block, search for the largest absolute value on the specified channel
|-
| MAINMontage || change the montage (used by the Export command when saving to current montage)
|-
| MAINParadigm || load a paradigm file
|-
| MAINPatternToTrigger || convert a tag into a trigger
|-
| MAINPolygraphicFilters || sets filters for polygraphic or added channels
|-
| MAINScale || set amplitude and time scales
|-
| MAINSearchAverageView || start search average view
|-
| MAINSendToMATLAB || send data to MATLAB
|-
| MAINSplineConstant || set the spline constant used in spherical spline maps and channel interpolation
|-
| MAINTriggerRecode || the command recodes a specified trigger number to a new number
|-
| MAINTriggerSelect || edit the trigger list (cf. ''Edit / Trigger Values''...)
|-
| MAINTriggerTagDelete || delete one or more triggers or tags
|-
| MAINViewAverageBuffer || turn on the Average Buffer View and place the specified buffer number to the left in the display
|-
| MAINViewChannelType || select the channel type to display, and select channel types for mapping, export, etc
|-
| MAINViewSelected || turns selected view on or off
|}

'''General commands for Source Analysis''' - prefixed with "'''SA'''" (but see also ''MarkBlock'', which is used to send a block of data to SA and open the SA window):

{| cellspacing="8"
| SAAddSource || add a dipole or regional source to a model
|-
| SAChannelTypeForFit || switch between EEG, magnetometers or axial gradiometers, and planar gradiometers
|-
| SAConvertSource || convert a source from dipole to regional source, or from regional source to dipole
|-
| SAcorticalClara || run Cortical CLARA
|-
| SAcorticalLoreta || run Cortical LORETA
|-
| SADelete || delete current solution or all solutions, or remove current fit interval or cursor
|-
| SADICS || start DICS computation (if DICS has been precomputed in the time-frequency image command)
|-
| SADisplayMRI || switch MRI display on/off and select small or large window
|-
| SAElectrodeConfiguration || equivalent to pressing the Org or Std button in the Channel box of the Source analysis window
|-
| SAExit || close Source Module
|-
| SAFit || start fit
|-
| SAFitConstraint || set fit constraints, e.g. Residual Variance, Energy, Maximum Distance, Image Weighting, and their weights.
|-
| SAFitInterval || set fit or baseline interval
|-
| SAHeadModel || set the head model
|-
| SALabelSource || set the label of the specified source number
|-
| SAMinimumNorm || run a minimum norm analysis
|-
| SANewSolution || open a new solution
|-
| SAOpenSolution || open a solution from a file
|-
| SAPCA || toggle PCA display of data or residual, and transfer a selected number of components to the source model
|-
| SARegularization || set the regularization values both for discrete and distributed source images
|-
| SASaveBitmap || save a screenshot of the Source Analysis or the 3D window
|-
| SASaveLeadfields || save the leadfields of the current source model
|-
| SASaveModelWaveforms || save model waveforms
|-
| SASaveResidualWaveforms || save residual waveforms
|-
| SASaveRVandGFPWaveforms || save residual variance and global field power waveforms
|-
| SASaveSolution || save the current solution
|-
| SASaveSourceMontage || save a source montage
|-
| SASaveSourceWaveforms || save source waveforms
|-
| SASendToMATLAB || send data, model, source waveforms, images, etc. to Matlab
|-
| SASetCursor || set the cursor
|-
| SASetDefaultSourceType || set the default source type (dipole or regional source)
|-
| SASetOrActivateSource || Turn specified source on or off, or enable/disable source for fitting
|-
| SASetOrientation || set orientation (of regional source)
|-
| SASwitchCondition || switch to a specified condition
|}

'''Commands for Distributed 3D Volume Images'''

{| cellspacing="8"
| SAIMAGEBeamformer || switch between Single Source and Bilateral Beamformer image
|-
| SAIMAGEBeamformerTimeDomain || start beamformer computation in the time domain
|-
| SAimageBrainAtlas || turns on the Brain Atlas overlay on volumetric image
|-
| SAIMAGECLARA || generate CLARA image
|-
| SAIMAGEClip || clip image values under a threshold
|-
| SAIMAGEExport || save the results of minimum norm or 3D imaging method
|-
| SAIMAGEGotoMax || set the crosshair cursor at the nth maximum in the image
|-
| SAIMAGEImport || load a 3D volume image from file
|-
| SAimageImportFMRI || import fMRI image to Source Analysis Module
|-
| SAIMAGELAURA || create LAURA image
|-
| SAIMAGELORETA || create LORETA image
|-
| SAIMAGESLoreta || create sLORETA image
|-
| SAimageSESAME || start SESAME computation
|-
| SAIMAGESSLOFO || create SSLOFO image
|-
| SAIMAGEUser-Defined || create user-defined image
|-
| SAIMAGESaveLeadfields || save the leadfields of all the voxel sources in a 3D image
|-
| SAIMAGEClip || clip current 3D image
|-
| SAIMAGESmooth || smooth current 3D image
|-
| SAIMAGESetCrosshair || set the position of the crosshair in the 3D image
|}

'''Commands for Time-Frequency Analysis''' ('''TFC''')

{| cellspacing="8"
| TFCStartTFAnalysis ||(previously TFCgo) start TFC analysis using the current paradigm settings
|-
| TFCdisplay || change the TFC display (e.g. power/amplitude, coherence)
|-
| TFCsave || save numerical results to an ASCII file, or save a screenshot of the TFC window
|-
| TFCimage || start beamformer analysis on a selected time-frequency range
|-
| TFCSendToMATLAB || send TF results or single-trial data to MATLAB
|}

=== How to Average Your Data in a Batch ===

Using batch processing, several files from an experiment can be averaged at a time.

Here we summarize the steps required:

'''Before running the batch'''

* Create the paradigm, and save the paradigm file.
* Open each individual data file to check the data:
** Make sure auxiliary files are defined and loaded properly, and the data are displayed correctly.
** Eyeball the data.
** Define bad (and interpolated) channels.
** Mark artifact time ranges.
** If required, set up artifact correction for the file.
** The data file can be closed again after this step.

'''Preparing the batch'''

* Open at least one file and select ''Process / Batch Scripts''.... The file(s) should be displayed in the file list. Alternatively, just select ''Process / Batch Scripts...,'' and add the files by
** pressing the '''Add File''' button
** dragging the files from Windows Explorer
** Opening a previously saved list with ''Load File List''

* You can delete files from the list (press '''Del''') or edit the file sequence using the right click context menu.
* Select the ''Batch Tab''.
* Add commands to your script. For averaging, these would normally be
** '''Paradigm''' -- to load the paradigm file
** '''Artifact Scan''' -- to run the artifact scan
** '''Average''' -- to perform the average

* Save these commands (press '''Save Batch''').
* Test the commands on the files in the current file list: press '''OK'''
* Look at the log file (press '''View Log File''') to check the results of averaging.
* Look at the data averages to make sure they have been done correctly.
* Repeat these steps until averaging is working properly.

'''Running the batch'''

* Select ''Process / Batch Scripts''....
* Open the files you want to average in the batch in the file list:
** Any files that were open in BESA are included in the list
** Files can be added using the '''Add File''' button
** You may drag one or more files from Windows Explorer to the file list
** Alternatively, load a previously saved file list.

* Edit the file list, e.g. delete unwanted files (use the '''Del''' key or the right click context menu), or reorder the files (use '''Ctrl + cursor keys''' or context menu).
* Note that the order of files in the list specifies the order in which they will be processed in the batch script. This order will be important if all results are saved to the same target file. Otherwise the file sequence is not important.
* Optionally, save the file list (press '''Save Batch'''
* Select the ''Batch Tab'', and load the previously defined batch script with ''Load Batch''.
* Press '''OK''' to run the batch.

=== How to Merge and Compress raw data ===

Using the Export command in a batch, several data files can be merged into a single data file in BESA's data format ('''<nowiki>*.foc</nowiki>''').

This can be useful if data from one subject have been collected in several data blocks, and you want to analyze all data blocks together.

Optionally, to save space, data can be saved in compressed format.

'''Files can be merged:'''

* if they have identical channel configurations, or
* there are at least 16 EEG channels, and the export format is Standard 81 (i.e. EEG channels are interpolated to 81 standard locations).

'''How to merge files:'''

* Select '''Process / Batch Scripts...'''
* Add all the files that are to be merged to the file list:
** Any files that were open in BESA Research are included in the list
** Files can be added using the '''Add File''' button
** You may drag one or more files from Windows Explorer to the file list
** Alternatively, load a previously saved file list (''Load File List'').
* Rearrange the files in the file list to the sequence in which they should be merged.
* Select the ''Batch Tab ''and insert an "''Export"'' command, as described below.

The following dialog shows a possible configuration of the ''Export'' command:

[[Image:Batch processing (4).gif]]

* The parameters shown in the Information box are the settings chosen in the ''Export Dialog'' when the '''Select Options''' button has been pressed.
* '''Append if file already exists''' must be checked in order to merge the files.
* The '''target file name''' must be fixed, i.e. don't use the '''%basename%''' variable, because that will result in a different target file name for each source file.
* There are two variables that can be used for the segment label:
** '''%filename%''' will insert the basename of the source file into the segment label.
** '''%c%''' will insert the file number into the segment label. The number gives the position of the file in the file list. For instance, "File %c%" will generate the label "File 2" for the second file in the list.

=== Example: Data averaging in the auditory intensity experiment ===

In this example, two raw data files, '''s1.cnt''' and '''s2.cnt''', from the auditory intensity experiment will be batch averaged.

Please note that there are further tutorials covering this experiment. The first file is contaminated by many eyeblinks, and more epochs would be averaged if eye correction were used (see Viewlet demonstration on artifact correction on the BESA website). However, in this tutorial we will just use artifact rejection.

'''A. Various ways of creating a File List'''

1. '''Files that were open in BESA Research are automatically added to the File List.''' Start BESA Research and open the files '''s1.cnt '''and '''s2.cnt '''in the directory ''Examples\ERP-Auditory-Intensity''.

2. Select ''Process / Batch Scripts''.... You should see the file names in the '''''File List Tab''''' something like this:

[[Image:Batch processing (5).gif]]

3. You can resort the files in the file list alphabetically by clicking onto the '''''File List column header''''':

[[Image:Batch processing (6).gif]]

Alternatively, you can mark any file, hold down the '''Ctrl '''key and press the '''Up''' or '''Down arrow '''to move the file name up or down the list. This is the sequence in which files will be processed in the batch.

[[Image:Batch processing (7).gif]]

4. Press '''Save File List''' and save the list you have created to '''ERP-Aud-Ex1.flist'''.

5. Highlight both names and press the''' Del '''button to remove them from the list.

6. '''Files can be dragged from Windows Explorer'''. Start Windows Explorer and navigate to the ''ERP-Auditory-Intensity'' subdirectory of your BESA Research examples folder (located in the ''Public Documents'' folder of your computer). Click on '''s1.cnt''' and drag it with the mouse onto the '''''File List Tab'''''. Let go of the mouse. BESA Research opens the file, and displays the name in the File List. Repeat for '''s2.cnt.'''

7. Highlight both names and press the '''Del '''button to remove them from the list.

8. '''Files can be added using the ''Add File'' button'''. Press '''Add File''' and navigate to the ''Examples\ERP-Auditory-Intensity'' subdirectory. Select '''s1.cnt'''. Press '''Ctrl''' and select '''s2.cnt'''. Both names should then be displayed in the ''File Open'' dialog. Press '''OK''' to add the files to the file list.

9. Highlight both names and press the '''Del''' button to remove them from the list.

10. '''Files can be loaded from a previously saved file list'''. Press '''Load File List '''and select '''ERP-Aud-Ex1.flist''', the list you saved in step 6 above.

'''B. Setting up the batch'''

1. We will add three commands, '''Paradigm''', '''Artifact Scan''', and '''Average''', to create a batch that will be applied to the two files in the file list.

2. Click on the '''Batch Tab'''.

[[Image:Batch processing (8).gif]]

3. Press the '''Add Command''' button to obtain the ''Select Command'' window:

[[Image:Batch processing (9).gif]]

4. Click on '''Paradigm''' and then on '''OK''' (alternatively, double-click on '''Paradigm'''). Hit '''Browse''', navigate to the ''Auditory'' folder, and select '''AEP_Intensity.pdg''', the paradigm for the auditory intensity experiment.

[[Image:Batch processing (10).gif]]

5. Press '''OK''' to obtain the ''Load Paradigm Task'' window.

[[Image:Batch processing (11).gif]]

6. Press '''OK''', and the first task in the batch is ready, and listed in the Batch Command window. If you want to modify the command, double-click on it to open the above window, that allows to browse for a different paradigm file.

[[Image:Batch processing (12).gif]]

7. Next, we add the '''Artifact Scan''' command. Click on the '''Add Command''' button, and select ''Artifact Scan.''

[[Image:Batch processing (13).gif]]

8. Press '''OK''' to open the ''Artifact Scan Task'' window. We want to be able to view the results of the scan, and adjust thresholds and bad channels if necessary. Therefore, check the ''Wait after scan'' checkbox.

[[Image:Batch processing (14).gif]]

9. Press '''OK''' to close the ''Artifact Scan Task'' window. Our batch now contains two commands.

[[Image:Batch processing (15).gif]]

10. Finally, we will add an '''Average''' command. Press the '''Add Command''' button and select ''Average''. Press '''OK''' to open the ''Average Task ''window.

[[Image:Batch processing (16).gif]]

11. With the default settings, the average would be saved to the same directory as the data. The file name mask is set by default so that in this example the two averages would be saved to '''s1-av.fsg '''and '''s2-av.fsg'''. We will save the averaged files to subdirectory ''"Averages''" of the data directory. Uncheck the ''Use default target'' check box, change the File name mask to '''%basename%_av-test''' in order not to overwrite the predefined files.

[[Image:Batch processing (17).gif]]

12. Press '''OK '''to close the ''Average Task'' window. Our batch is now complete.

[[Image:Batch processing (18).gif]]

13. We will now save the batch so that it can be used again. Press the '''Save Batch''' button, and save to the file '''ERP-Aud-ex1.bbat'''. Note that an easy way to generate new averaging batches is to load a previously save batch and edit the commands -- it may only be necessary to edit the '''Paradigm''' command to select the relevant paradigm file, and maybe to adjust the target directory in the '''Average''' command.

14. Press '''OK''' in the ''Batch'' Window to start the batch running. As requested, the batch pauses after the artifact scan:.

[[Image:Batch processing (19).gif]]

You may now adjust the number of rejected trials, e.g. by moving the vertical red bar to the left, or exclude bad channels.

15. Press '''OK''' to continue with averaging.

[[Image:Batch processing (20).gif]]

16. Note that, in the background, the ''Batch Running'' window is providing feedback about the current file and current task.

[[Image:Batch processing (6).jpg|400px]]

17. The batch will stop again after the next artifact scan. Press '''OK''' to allow the batch to run to the end.

[[Image:Batch processing (21).gif|400px]]

18. Press '''View Log''' to view the batch protocol. If you are using Internet Explorer or Netscape family (Mozilla, Firefox) browsers, and JavaScript is enabled, you will first see just batch titles defined by the date and time the batch was started. The most recent title is at the top of the list. For other browsers, or if JavaScript was not enabled, all protocol texts are expanded as in 19 (below).

[[Image:Batch processing (22).gif|200px]]

19. Click on the first title to expand its protocol. Here, for example, the protocol gives feedback about the number of epochs that were averaged for each file.

[[Image:Batch processing (23).gif]]

20. Finally, press '''OK''' to return to the main BESA Research display. Open the averages in the ''Averages'' subdirectory to confirm that they were generated properly.

=== Example: Merging files using the Export Command ===

Here we will demonstrate the use of the '''Export '''command to merge two files. We will combine the two averages from the previous example (Data averaging in the auditory intensity experiment) into one target file.

'''A. Generate the file list'''

# Start BESA Research and load the two data files '''S1_av-test.fsg''' and '''S2_av-test.fsg''' that were saved in the previous example.
# Select ''Process / Batch Scripts....''The two file names should be displayed in the file list.
# In the file list, make sure that '''s1_av-test.fsg '''is the first file in the list. If it is not, highlight the file, and move it up using '''Ctrl+up''', or right click and select ''Move Up'' in the context menu.

'''B. Generate the batch'''

1. Press the '''Add Command''' button, and select the '''Export''' command.

2. Press '''OK''' to open the ''Export Task'' window.

[[Image:Batch processing (24).gif]]

3. Press the '''Select Options'''... button to open the ''Export Dialog''.

[[Image:Batch processing (25).gif]]

4. Since we are combining averages, select ''Hires (no compression)'' in the '''Target data format''' drop-down list (If we were merging raw data files, it is better to select compression. Press '''OK '''to close the dialog. Check'' Append if file already exists'', so that the files will be merged. Enter '''s1+s2''' in the target file name mask edit box. This ensures that both files will be saved to the same target: '''S1+S2.fsg'''.

[[Image:Batch processing (26).gif]]

5. Press '''OK '''to close the ''Export Task'' window. The '''Export '''command is displayed.  

[[Image:Batch processing (27).gif]]

6. Optionally, you may save the batch file by pressing '''Save Batch'''.

7. Press '''OK''' to run the batch, and '''OK''' in the ''Batch Completed'' window to return to the BESA main window.

8. Finally, open the file '''S1+S2.fsg''' to confirm that it contains the two merged files.

'''C. Merge raw data'''

# Repeat the above task to merge the two raw data files '''S1.cnt''' and '''S2.cnt''' into a single target file '''S1+S2.foc'''. In this case, select one of the compression options as the target data format. Note that you would not normally want to merge two files from different subjects. However, several data blocks from the same subject can conveniently be merged using this method.

Note that ''<nowiki>*.fsg</nowiki>'' files can also be merged using the ''Combine Conditions'' dialog. 

== Combine Conditions, Channels ==

=== Combine Condition Scripts ===

With the Combine-Conditions module you can do a variety of operations on BESA averages (files with the extension '''<nowiki>*.fsg</nowiki>''', and other segment files, such as '''<nowiki>*.mul</nowiki>''', '''<nowiki>*.avr</nowiki>''', '''<nowiki>*.swf</nowiki>'''):

* Create grand averages
* Combine averages (add, subtract, weighted/unweighted)
* Merge files
* Exclude unwanted averages
* Rename conditions
* Rename or resort channels
* Generate averages or differences over selected channels
* Transform the data: standard interpolated 81 electrodes, change sampling rate, change interval
* Determine peaks, mean amplitudes, or integrals on data averages
* These operations can be performed on one or more files simultaneously. Results of an operation are stored in a single target file.

The module includes four tabbed windows:

* File List: Define a list of files on which the operations will be performed.
* Condition List: List the condition names, define target condition names, and how input conditions are combined into target conditions.
* Channel List: List the channel names, define target channel names, and how input channels are combined into target channels.
* Run Scripts: Define global options for the output (e.g. spatial interpolation, resampling, copy/merge or average, peak analysis). Start the operation.
* Note that in all four tabs, configurations can be saved for future use, and the '''Load Previous''' button restores the most recently used configuration.

=== Condition List Tab ===

List the condition names, define target condition names, and how input conditions are combined into target conditions.

The first column of the list box shows a list of all the condition names found in the source files.

Rows of the list box define the source conditions. Columns define the target conditions.

'''Initial setting'''

When first selecting the tab, each column shows each condition name found in the source files (as in the example below). In the list box, there is a "+1" along the diagonal. The result of this selection is that target conditions will have the same name as source conditions. Right click on source condition labels to view properties (e.g. no. of samples, time range, sampling rate).

[[Image:Batch processing (28).gif]]

'''Editing the condition list'''

* Target condition names can be edited, inserted or deleted by clicking on the label at the top of each column.
* Click on a box within the list to toggle between "+1", "-1" and blank. These correspond to the operations:
** "+1" = add
** "-1" = subtract
** blank = do nothing
* Right click on a box for further operations: conditions can be weighted by a given factor other than 1.

'''Divide result by sum of PLUS factors'''

* Normally, when creating an average over conditions, the sum is divided by the number of conditions, or a weighted average is generated (see below).  If "''Divide result by sum of PLUS factors''" is unchecked, the conditions will be summed rather than averaged.
* Note that, when making differences between conditions, no such division is required. BESA Research will uncheck the checkbox automatically if subtraction ("-1") is specified somewhere in the condition list.

'''Weighting of averages'''

* Below the list, click on the ''Weighted Average'' row to toggle "YES" and "NO". "YES" means that averages will be weighted by the number of epochs contributing to the average. For instance, if average A contained 100 epochs and average B contained 200 epochs, the weighted average will be computed as

<div style="margin-left:1cm;margin-right:0cm;">(100 * A +  200 * B) / (100 + 200)</div>

<div style="margin-left:1cm;margin-right:0cm;">Select "NO" for an unweighted average. For the above example, the average is computed as</div>

<div style="margin-left:1cm;margin-right:0cm;">(A + B) / 2</div>

<div style="margin-left:1cm;margin-right:0cm;">Weighted averages are not permitted if one of the boxes contains a negative value.</div>

* Values other than +1 or -1 in the boxes apply a different kind of weighting. For instance, we want to compute the difference between the means of conditions A, B, C and D, E. Use a right click to specify the fraction 1/3 for each of A, B, and C, and -1/2 for each of D and E (see example below).

[[Image:Batch processing (29).gif]]

'''Save the current condition list'''

* Press the '''Save Condition List''' button.

'''Load a condition list'''

* Press the '''Load Condition List''' button.

'''Load previous settings'''

* Press the '''Load Previous''' button

'''Feedback'''

* Conditions that have different numbers of electrodes (averaging across different files) can only be combined if channels are interpolated to a standard set of electrodes.
* Conditions that have different durations or sampling rates can only be combined if the sampling rate and durations are made the same.
* Feedback about the above situations is displayed by the presence of tick marks above the list box.

=== Channel List Tab ===

List the channel names, define target channel names, and how input channels are combined into target channels.

Note that this tab is very similar in usage to the '''Condition List Tab'''. Note also that some of the functions performed in this tab could also be done in the Montage Editor. It may be a matter of convenience whether you choose to perform these operations here or in the Montage Editor.

The first column of the list box shows a list of all the channel names found in the source files.

Rows of the list box define the ''source'' channel. Columns define the'' target'' channel.

'''Initial setting'''

When first selecting the tab, each column shows each channel name found in the source files (as in the example below). In the list box, there is a "+1" along the diagonal. The result of this selection is that target channel will have the same name as source channel.

'''Combining files'''

If files with different channel configurations are included in the File List, the rows and columns of the Channel List Tab will only contain the labels for the channels that are in common among the files.

If the files in the File List have a different sequence of channels, the sequence of the first file in the list will be adopted in the Channel List.

Thus, for the initial setting, unless the "''Ignore Settings in this Tab''" checkbox is checked, the target grand average or peak/amplitude analysis, etc. will be applied using only channels that are in common among the input files, and using the channel sequence of the first file in the File List. By changing the target channels or by changing the entries in the Channel List, new channels consisting of averages or differences can be generated.

'''What can the Channel List be used for?'''

Some examples:

* Reorder or relabel channels
* Create channel differences
* Create averages over channel groups, e.g. for peak analysis
* Extract a selection of channels for peak analysis or mean amplitudes
* Create grand averages across files with different channel configurations, just using channels in common among the files

[[Image:Batch processing (30).gif]]

'''Editing the channel list'''

* Target channel names can be edited, inserted or deleted by clicking on the label at the top of each column.
* Click on a box within the list to toggle between "+1", "-1" and blank. These correspond to the operations:
** "+1" = add
** "-1" = subtract
** blank = do nothing
* Right click on a box for further operations: channels can be weighted by a given factor other than 1.

'''Divide result by sum of PLUS factors'''

* Normally, when creating an average over channels, the sum is divided by the number of channels, or a weighted average is generated (see below).  If "Divide result by sum of PLUS factors" is unchecked, the channels will be summed rather than averaged.
* Note that, when making differences between channels, no such division is required. BESA Research will uncheck the checkbox automatically if subtraction ("-1") is specified somewhere in the channel list.

'''Save the current channel list'''

* Press the '''Save Channel List''' button.

'''Load a channel list'''

* Press the '''Load Channel List '''button.

'''Load previous settings'''

* Press the '''Load Previous''' button

=== Run Scripts Tab ===

Define global options for the output (e.g. spatial interpolation, resampling, copy/merge or average, peak detection. Start the operation.

[[Image:Batch processing (7).jpg]]

'''Load or Save Settings'''

* You can save the current settings of this tab to a file (*.run) which can be loaded later.
* When you run the script, the current settings are saved automatically to a file "'''PreviousSettings.run'''".

'''Load Previous'''

* Press this button to load the previous settings (from "'''PreviousSettings.run'''").

'''Averages to Generate'''

* '''Generate separate averages for each source file'''. Averages are performed over conditions within the source file, and are then appended to the target file.
* '''Combine data from source files'''. Conditions are combined over all source files into a single target average.
* '''No averages, just copy'''. Files are copied and merged to the target file. Use this option for renaming conditions, merging files, removing unwanted averages (see below), changing the sampling rate and interval.
* '''Peaks and mean amplitudes'''. Specify time ranges for peaks, mean amplitudes, or integrals (areas).
* Note: When generating or copying averages (first three options), filters and baseline settings are turned off. For Peaks and mean amplitudes, filters and baseline settings are specified in the dialog.

'''Spatial Interpolation'''

* '''Interpolate to Standard 81 electrodes'''. The target file will contain only electrodes (other channels are omitted), using the Standard 81 configuration (as in other export functions within BESA Research). This cannot be selected if the source data contain less than 16 EEG channels.
* '''Interpolate Bad Channels'''. Bad electrode channels in the source file will be interpolated. If the above option is deselected and bad channels exist in one or more of the source files, this option is always on.

BESA Research can interpolate EEG, and MEG if the sensors are axial gradiometers or magnetometers. If other channels are marked as bad in one or more of the source files, these will be defined as bad in the target file. This applies to MEG planar gradiometers, to polygraphic data, and to ICR channels.

'''Temporal Interpolation'''

* '''Spline to New Sampling Rate and Interval'''. Data can be converted to a new sampling rate, and the interval can be changed.
** If the sampling rate is reduced, the data will be low-pass filtered at 1/3 sampling frequency before reduction.
** If the sampling interval is changed, the prestimulus and poststimulus intervals are limited by the smallest intervals in the conditions contributing to the averages. These limits are shown below the edit boxes.

'''Peaks and Mean Amplitudes'''

[[Image:Batch processing (31).gif]]

'''Peaks:'''

* Select the time range between which peaks are to be determined.
* Select the montage on which the peaks are to be determined.
* Define the filter settings.
* Define the baseline settings.
* Specify whether peaks are to be defined at one latency: if so, select the channel on which peaks are to be detected.
* Specify whether you want to find positive or negative peaks.

'''Mean amplitudes and areas:'''

* Select the time range over which the mean amplitudes or areas are to be determined.
* Select the montage on which the mean amplitudes or areas are to be determined.
* Define the filter settings.
* Note that when computing areas, data are first rectified (made positive) and then summed over the time range.

'''Output options of the analysis:'''

* A single ASCII file that contains the result of the analysis for all data sets, conditions, and channels including header and information lines.
* A sparse output suitable for import in SPSS. Each variable (e.g. a latency, a channel amplitude) constitutes one column of the output file.
* Direct transfer to MATLAB into a struct besa_peak. For more information on the data transfer from BESA Research to MATLAB, please refer to help chapter ''“The MATLAB interface”.''

'''Starting the Operation'''

* Press '''OK''' to start the operation. After the operation is completed, and the "Open target file in BESA" box is checked, BESA Research will open the target file.  "Open target file in BESA" cannot be checked if "Peaks and mean amplitudes" was selected - then the result of the operation will be an ASCII file or a MATLAB transfer.
* You will be asked for the name of the target file (unless a MATLAB transfer of peak data has been performed).

'''Restrictions'''

* Depending on source file configurations, not all options above are selectable. For instance, if two files contain different numbers of electrodes, and the "''Ignore Settings in this Tab''" checkbox is checked in the '''''Channel List''''' Tab, spatial interpolation to Standard 81 is enforced in the target. Similarly, if different sampling rates are used in different files, temporal interpolation is enforced.
* You are not allowed to add files to the file list if the channel configuration is different, and the data cannot be combined with Standard 81 interpolation. Since Standard 81 interpolation is only possible for EEG, multiple files without EEG can only be loaded if they have the same number of channels.

=== How to Create Grand Averages ===

* Open the files you want to average in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. To average across different conditions, click in the list boxes to obtain "+1" for each source condition to combine, and rename the target condition to define a meaningful name for the average.
* Click on the '''Run Scripts Tab'''.
* If you have more than one file, specify whether averages should be generated across files ('''Combine data from source files''') or within files ('''Generate separate averages for each source file''').
* Select other options if required (spatial or temporal resampling).
* Press '''OK'''.

=== How to Generate Differences Between Conditions ===

* Open the files you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. To create differences, click in the list boxes to obtain "+1" for one of the source conditions, and "-1" for the source condition to subtract, and rename the target condition to define a meaningful name for the difference.
* Click on the '''Run Scripts Tab'''.
* If you have more than one file, specify whether averages should be generated across files ('''Combine data from source files''') or within files ('''Generate separate averages for each source file''').
* Select other options if required (spatial or temporal resampling).
* Press '''OK'''. An average of the differences is generated. If only one example of each condition exists, e.g. in a grand average file, the result is the difference between conditions.

=== How to Merge Files ===

* Open the files you want to merge in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions''...).
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press '''OK'''.

'''Notes'''

* If the source files have different electrode configurations, use the Standard 81 configuration for the target.
* If the source files have different sampling rates or intervals, use Temporal Interpolation.

=== How to Remove Unwanted Averages ===

'''Removing one or more unwanted segments'''

* Normally, all conditions are read from a source file. To exclude one or more segments from operations in the Combine Conditions module, mark the segments as artifacts in the main program display. It is sufficient for the beginning or the end of an artifact interval to be within the segment for the segment to be excluded.
* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press''' OK'''.
* The target file contains the copied data without the conditions that were marked as averages.

'''Removing one or more unwanted conditions (by label)'''

* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Deselect the target conditions you want to omit (replace the "+1" by a blank).
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press''' OK'''.
* The target file contains the copied data without the conditions that were marked as artifacts.

=== How to Rename Conditions ===

* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions''...).
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. Click on column headings to rename the target conditions.
* Click on the''' Run Scripts Tab'''. Select "''No averages, just copy''".
* Press '''OK'''.
* The target file contains the copied data with the renamed conditions.

=== How to Change the Sampling Rate ===

* Open the file(s) you want to change in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...'').
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Select "''Spline to New Sampling Rate and Interval''" and type the new sampling rate into the edit box.
* Press '''OK'''.

=== Example: Create grand average and combinations of conditions ===

In this example, we will generate a grand average of the results of the Auditory Intensity Experiment. The experiment includes averages from five different stimulus intensities. We will create a grand average over each intensity, but also include means over the two lowest and the two highest intensities, and the difference between these two combinations.

'''A. File selection'''

# Start BESA Research and open files '''S1_av.fsg - S10_av.fsg''' in the ''Examples\ERP-Auditory-Intensity'' folder. The files contain the individual averaged data of the 10 subjects who participated in this study.
# Select ''ERP / Combine Conditions...'' The file list should display the two files, with feedback about the number of averages and conditions. 8 epochs are found. See the ''“Data averaging in the auditory intensity'' ''experiment”'' example for examples how to manipulate the file list.

[[Image:Batch processing (32).gif]]

'''B. Define conditions'''

1. Click on the '''Condition List Tab'''. The initial window defines target conditions with the same name as the source conditions. To generate the grand average over these conditions we could proceed without further changes to the '''Run Scripts Tab'''. However, we want to modify the condition list and create a condition that contains the grand averaged difference between the''' High''' and '''Low''' conditions.

[[Image:Batch processing (8).jpg]]

2. Click on the '''All '''column label. In the resulting window, rename condition '''All''' to''' Difference'''. Then press '''OK'''.

[[Image:Batch processing (33).gif]]

3. The last column is now labeled '''Difference.''' Left-click twice onto the ‘'''+1’''' entry that links this condition to the '''All '''input condition. This will remove the link and leave the field blank. To define the ‘Difference’ condition as the average of ‘High’ minus ‘Low’ over subjects, left-click once into the field linking input '''High''' with target '''Difference''' to generate an entry ‘'''+1’''' in this field. Left-click twice into the field linking input '''Low '''with target '''Difference''' to generate an entry '-'''1'''’.

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;">[[Image:Batch processing (35).gif]]</div>

4. Press '''Save Condition List''' and save the list to '''ERP-aud-ex1.clist'''. This condition combination can thus be loaded later using the '''Load Condition List''' button.

'''C. Run the script'''

# Click on the '''Run Script Tab'''.
# The default tab settings are ready for generating the grand average ('''Combine data from source file''' and '''Open target file in BESA''' should be checked). Just press '''OK'''. Enter '''All_Subjects_cc-test.fsg''' as file name and press''' Save'''.

The resulting file contains the 8 target conditions, 60db, 70dB, 80dB, 90dB, 100dB, Low, High, and Difference.

=== Example: Average files from different experiments ===

This example is intended to illustrate several features of the ''Combine Conditions'' Dialog, such as electrode interpolation and resampling. We will combine an average from the Auditory Intensity experiment with one from the P300 auditory experiment. In this particular case, it is not a very meaningful thing to do, but it shows what is possible. For instance, the same experiment may have been performed using different sampling rates or electrode combinations. This example shows how such data may be combined.

'''A. File selection'''

# Start BESA Research and open the file '''All_Subjects_GA.fsg''' in the ''Examples\ERP-Auditory-Intensity'' folder. The file contains the grand average data from the auditory intensity experiment.
# Open the file '''RareFrequentResponseLeft.fsg''' in the ''Examples\ERP-P300-Auditory'' folder. This file contains averages from the P300 auditory experiment.
# Select ''ERP / Combine Conditions... ''Note that the files have different sampling rates and different numbers of electrodes.

[[Image:Batch processing (36).gif]]

'''B. Define conditions'''

1. Click on the '''Condition List Tab'''. Note that the feedback text at the bottom of the window displays the text "Standard 81 interpolation required to generate average; Across files: resampling or change in time range required to generate average". The condition labels show all the names from both files.

[[Image:Batch processing (37).gif]]

2. We will exclude most conditions, and just combine the most similar conditions from the two experiments: the "Standard" and the "80dB" conditions. Click on the title of the first column,''' Blink'''. Select “''Delete all conditions to the right of this column”'', and press '''OK'''.

[[Image:Batch processing (38).gif]]

3. Click on the title again, and rename the target condition to "Standard".

[[Image:Batch processing (39).gif]]

4. Click twice in the first line to remove the "+1" entry there. Click once in the third row ("Frequent"), and in the 7th row ("80dB"), to display "+1" at each entry. Thus, just two of the conditions will be combined into one target condition.

[[Image:Batch processing (40).gif]]

'''C. Run the script'''

1. Click on the '''Run Script Tab'''.

[[Image:Batch processing (41).gif]]

2. Note that '''Interpolate to Standard 81 electrodes''' is checked and grayed: since two different electrode sets are to be combined, we can only do this by interpolating electrodes. Also, both '''Spline to new sampling rate''' and '''Clip interval '''are checked and grayed. Again, these settings are required in order to be able to average the two data files together. The sampling rate is set to the higher of the two selections. The time range is set to the largest possible range that can be clipped from the two data sets. For now, leave these settings as they are, and press '''OK'''. Save the target to '''TestCombineExpts_CC-std81.fsg'''.

{{BESAManualNav}}

BESA Research Batch Processing

2021-05-05T07:44:31Z

Abinash: Reverted edits by Abinash (talk) to last revision by Mateusz

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = 6.1 or higher
}}



== Combine Conditions and Batch Module: Introduction ==

Functions of this module are started by selecting the menu operations "'''ERP / Combine Conditions...'''" and "'''Process / Batch Scripts...'''".

* '''Combine Condition Scripts''' provides various operations on BESA averages.
* '''Batch Scripts''' provides batch operations on all data files.
* Note that a batch script can also be performed on the current file by selecting "'''Process / Run Batch...'''" or by typing the shortcut key "'''R'''".

== File List Tab ==

Define a list of files on which the operations will be performed. The tab is the same for Combine Conditions Scripts and for Batch Scripts. Combine Conditions Scripts only allows you to open BESA average files (e.g. '''<nowiki>*.fsg</nowiki>''' and '''<nowiki>*.avr</nowiki>''', but also '''.mul''', '''.raw''', '''.swf''', and '''.foc''' if the files have a defined pre-stimulus interval), whereas Batch Scripts allows you to open any data file whose format is known to BESA Research.

When the Combine-Conditions or the Batch module is started, all currently opened (Combine-Conditions: averages only) files are displayed in the list.

To the right of each file name, the number of electrodes, total number of channels, and the sampling rate used in the file are displayed. In the Combine-Conditions module, the number of Epochs (segments) and the number of differently-named conditions are also shown.

'''Add files to the list'''

* Press the '''Add File ''' button.
* Drag one or more files from Windows Explorer onto the window.

'''Remove files from the list'''

* Right click on the file name and confirm the delete operation in the resulting dialog.
* Mark one or more file names in the list (e.g. hold down the''' Ctrl''' key to mark multiple files). Right click to obtain the context menu and select "'''Delete'''", or just press the '''Del '''key.

'''Reorder files within the current file list'''

* Right click on the file name and select "'''''Move Up'''''" or "'''''Move Down'''''".
* Mark one or more file names in the list (e.g. hold down the '''Ctr'''l key to mark multiple files). Right click to obtain the context menu and select "'''''Move Up'''''" or "'''''Move Down'''''", or hold down the''' Ctrl''' key '''and '''press the '''Up''' and '''Down arrows'''.

'''Sort the current file list alphabetically'''

* Click on the File bar above the list

'''Save the current file list'''

* Press the '''Save File List''' button.

'''Load a file list'''

* Press the '''Load File List''' button, or the '''Load Previous''' button to load the most recently used file list.

'''Which conditions are read from a source file? (Combine-Conditions module only)'''

* Normally, all conditions are read from a source file. To exclude one or more segments from operations in the Combine Conditions module, mark the segments as artifacts in the main program display. It is sufficient for the beginning or the end of an artifact interval to be within the segment for the segment to be excluded.

'''File list from Combine Conditions:'''

[[Image:Batch processing (1).png]]

'''Don't try to open here... (Batch only)'''

By default, this checkbox is unchecked.

In the checked state, BESA Research doesn't check if it can open the file. Use this function '''only''' if the file is ASCII and you want to use the '''ImportASCII '''batch command.

'''File List from Batch Scripts''':

[[Image:Batch processing (2).png]]

== Batch Processing ==

=== Batch Processing Scripts ===

With Batch Scripts, you can define a set of operations (e.g. Artifact Scan, Average, etc.) and apply these to several data files.

These operations include

* Load Paradigm
* Artifact Scan
* Average
* Export (and Merge)
* File Open (switch to another data file)
* Set filters
* Specify a montage (used, for example, for export to current montage)
* Run automatic eye and EKG artifact correction
* Define artifact topographies
* Turn artifact correction and view on and off
* Read and write events
* Edit default block epoch (for export around triggers)
* Edit triggers (for export around triggers)
* Mark a block for export, or send the block to Source Analysis or Top View
* Convert patterns to triggers
* Attach auxiliary files (e.g. elp, sfp) to the data file
* Send to MATLAB
* Specify display configurations for the BESA Research Main, SA, and Top View windows
* and more - see the full list of [[Batch Commands]]

An additional set of commands are available for operations in the '''Source Analysis Module''', allowing to load, create and fit dipole models, and save the results.

A further set of commands apply to '''Time-Frequency Analysis''', allowing to start TFC, change the display, save results, and run the beamformer or DICS analyses on a selected time-frequency range.

[[Image:Batch commands1.png]]

These operations will be extended in future program releases.

The module includes two tabbed windows:

* '''File List''': Define a list of files on which the operations will be performed.
* '''Batch''': Define or load '''batch commands'''. Run the batch.

=== Batch Tab ===

Load or define batch commands, and then apply them to the files in the File List.

[[Image:Batch processing (4).png]]

'''Add Command'''

* Press '''Add Command''' to add a new command to the batch. The following dialog is opened, showing the available commands:

[[Image:Batch commands1.png]]

* Select the desired command and press '''OK''' or double-click on the command. A dialog box is opened, allowing to specify individual command parameters.
* If you click on "Apply at beginning of batch" or "Apply at end of batch", the command will only be run at the beginning or the end of a batch. You can use this, for example, at the end of a batch to start a MATLAB script to perform statistics on the results of the batch.

'''Load and Save Batch'''

* Press '''Load Batch''' to load a previously defined batch or '''Save Batch''' to save the current batch to a file ('''<nowiki>*.bbat</nowiki>''').

'''Load Previous'''

* Press '''Load Previous''' to load the most recently used batch file. Whenever a batch is run, the current set of commands is written to the file '''Previous.bbat in''' the '''Scripts/Batch''' subdirectory. This file is loaded when you press '''Load Previous'''.

'''Clear All'''

* Clears all commands from the window.

'''View Log File'''

* Each time a batch is run, BESA Research adds information about the batch to a log file, with headings showing the date and time the batch was started. The file is opened automatically in Internet Explorer if errors occurred during processing. Otherwise you may open the file by pressing the '''View Log File''' button here or in the dialog that is displayed at the end of batch processing. 
* The log file is saved in xml format, and a JavaScript is used to format the display in web browsers. JavaScript should be enabled in the browser to obtain an optimal display of the results. If JavaScript is enabled, the log file is displayed as a list of headings for each batch. Click on a heading to display the results of the corresponding batch.
* To open the log file in the Notepad, hold the''' Shift '''key down when pressing the '''View Log File''' button.

'''Batch Command List'''

* Double-click on a command to edit it. See [[Batch Commands]] for descriptions of the dialogs that are opened to edit each command.
* Right click on a command to open a context menu allowing more options.

[[Image:Batch processing (5).png]]

* '''Delete''', '''Move Up''', '''and Move Down''' can also be applied to multiple selections.
* If you have made a multiple selection, the '''Del '''button will delete all the marked commands. '''Ctrl '''plus '''Up''' or '''Down''' '''cursor keys''' will move the marked commands up or down.
* '''Toggle Comment''' will add or remove a semicolon (;) in front of the command, to deactivate or reactivate the command.
* '''Toggle Command Only at Start/End''' will add or remove the text "Start_" or "End_" in front of the command. With these prefixes, the command will only be performed when the first file ("Start_") or the last file ("End_") in the file list is being processed.

'''Single Step Mode'''

* Check this item to step through the batch, one command at a time. A dialog is opened after each command, allowing to run the next command, continue the batch without single steps, or stop running the batch. See the'' “Pause''” command for further details.
* During a batch, press and hold down the '''Pause''' or '''Delete''' key to interrupt the batch and enter Single Step Mode. Press and hold down the '''Esc''' key to cancel the batch.

'''Changes in batch written to database'''

* Checked by default. If this item is unchecked, file display settings, such as Montage setting and Artifact correction display, are not written to the database. When the file is next opened in BESA Research, the settings made in the batch are not retained.

'''Leave files in the file list open after running the batch'''

* If this item is checked, files in the file list will remain open after the batch. This is useful, for instance, if you want to open a set of files, specifying the same montage and/or filter settings for each file.

Press '''OK''' to start running the batch. Each command is then applied in succession to each file in the File List.

Note that, while a batch is running press and hold down the''' Pause''' or '''Delete''' key to interrupt the batch and enter Single Step Mode. Press and hold down the '''Esc''' key to cancel the batch.

=== The log file ===

A protocol of each batch is written to the log file '''Scripts/Log/Batch.xml.'''

When you press the '''View Log File '''button, the file is opened in your default browser for xml files. The file will be opened automatically if there was an error during batch processing, unless you have used the ''BatchError'' batch command to suppress this behavior.

'''DHTML formatting of the log file'''

The xml file is formatted using JavaScript (Dynamic HTML). If JavaScript is enabled in your browser, you will first see a list of batch protocol titles, labeled by the date and time at which the batch was started. The most recent batch is at the top of the list.:

[[Image:Batch processing (6).png|200px]]

Click on the title to view the protocol for the corresponding batch:

[[Image:Batch processing (7).png|600px]]

'''JavaScript and XP Service Pack 2'''

By default, if the log file is opened in Internet Explorer after XP Service Pack 2 has been installed, IE will warn you with the message: "''To help protect your security, Internet Explorer has restricted this file from'' ''showing active content that could access your computer".'' All the protocols in the log file are displayed. You may safely click on the options to allow active content in the log file, if you want to display the file as described above.

'''Backup of the log file'''

When the log file is written, a backup of the previous version is written to '''batch.xml.bak'''.

If the size of the log file exceeds 200 KB, it is renamed to '''batch.xml_date_time''' (e.g. '''Batch.xml_2004-10-08_10-53-32'''), and a new version of '''batch.xml''' is created.

=== Placeholders ===

A powerful feature of the batch commands is the ability to define file names and specify standard paths using placeholders. These are text strings enclosed by percentage (%) signs. They can be used in all batch commands where file names are specified.

'''Basename'''

{| class="wikitable"
! Placeholder !! Description !! Example
|-
|style="text-align:center;" width="10%"|'''%basename%'''
|width="40%"|replaced by the basename of the currently opened file.
|width="40%"|If the data file is named "f-spike.fsg", "%basename%-export.fsg" will be interpreted as "f-spike-export.fsg".
|-
|style="text-align:center;"|'''%basename-n%'''
|replaced by the basename of the currently opened file, but removing the last "n" characters from the name.
|If the data file is named "dongle-BB.fsg", "%basename-3%" will be replaced by "dongle", because the last 3 characters of the basename have been removed.
|-
|style="text-align:center;"|'''%-nbasename%'''
|replaced by the basename of the currently opened file, but removing the first "n" characters from the name.
|If the data file is named "BB-dongle.fsg", "%-3basename%" will be replaced by "dongle", because the first 3 characters of the basename have been removed.
|-
|style="text-align:center;"|'''%orgbasename%'''
|replace by basename of the current file in the file list (it has the same meaning as %basename% if no MAINFileOpen batch command was used in command list)
|
|-
|style="text-align:center;"|'''%base%'''
|replace by basename of the current file without the path
|
|-
|style="text-align:center;"|'''%orgbase%'''
|replace by basename of the current file in the file list without the path
|-
|style="text-align:center;"|'''%ext%'''
|replace by extension of the current file
|
|-
|style="text-align:center;"|'''%orgext%'''
|replace by extension of the current file in the file list
|
|-
|style="text-align:center;"|'''%basefolder%'''
|replace by folder of the current file
|
|-
|style="text-align:center;"|'''%orgbasefolder%'''
|replace by folder of the current file in the file list
|
|-
|style="text-align:center;"|'''%t%'''
|Log batch command only: time since start of batch on current file
|
|-
|style="text-align:center;"|'''%T%'''
|Log batch command only: current date and time
|
|-
|style="text-align:center;"|'''%label%'''
|Replace label of the most recent marked block by the block label, not including no. of averages
|
|-
|style="text-align:center;"|'''%LABEL%'''
| Replace label of the most recent marked block by the block label, including no. of averages

|
|-
|style="text-align:center;"|'''%scripts%'''
|replaced by the path to the Scripts folder.
|"%scripts%Batch" is where batches are saved by default; "%scripts%MATLAB" is the location of the standard MATLAB scripts used by BESA Research.
|-
|style="text-align:center;"|'''%montages%'''
|replaced by the path to the Montages folder.
|
|-
|style="text-align:center;"|'''%examples%'''
|replaced by the path to the Examples folder.
|
|}



'''Placeholders for folders'''

The following placeholders are the same as those used in the [Folders] section of '''Besa.ini''':

The strings enclosed by percent signs (%) are placeholders for the following folders in English-language versions of Windows. Folder names are different for the system and for other language settings. BESA Research will substitute the placeholders by the appropriate folder name for the Windows system and the system language:

* '''Windows 10 (English)'''

<div style="margin-left:1.27cm;margin-right:0cm;"> '''%localapp%''' = ""C:\Users[user]\AppData\Local\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Desktop as ""Desktop[user]\AppData\Local\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;"> '''%publicprog%''' = "Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = ""C:\Users\[user]\Documents\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as "Desktop\[User]\Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as''' %progdir%'''</div>

* '''Windows 7 (English):'''

<div style="margin-left:1.27cm;margin-right:0cm;">'''%localapp%''' = "C:\Users\[user]\AppData\Local\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Desktop as "Desktop\[user]\AppData\Local\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%publicprog%''' = "C:\Users\Public\Public Documents\BESA\Research_7_1". This folder is directly accessible from the Windows Explorer under "Libraries\Documents\Public Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = "C:\Users\[user]\Documents\BESA\Research_7_1", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as ""Libraries\Documents\My Documents\Research_7_1" or "Desktop\[User]\My Documents\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_7_1".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as''' %progdir%  '''</div>

=== Batch Commands ===

Batch commands are selected when the "'''Add Command'''" button is pressed in the "Batch" Tab. The commands are subdivided into five categories: General commands, commands for the Main module, for the Source Analysis module, imaging commands in the Source Analysis module, and commands for Time-Frequency Analysis. The commands have prefixes,''' GEN''', '''MAIN''',''' SA''', '''SAIMAGE''', and''' TFC'''), which identify the category. For compatibility with older program versions, old batches without the prefixes are accepted.

Detailed descriptions of each batch command are available in the electronic help chapter “''Batch Processing and Combining Conditions / Batch Processing / Batch Commands”.''

'''General commands''' - prefixed with "'''GEN'''" (can be used anywhere):

{| cellspacing="8"
| GENBatchError || used to change program behavior when errors occur
|-
| GENBatchWindowPosition || set the position of the batch window relative to the main window
|-
| GENComment || comment in the batch script: no batch functionality
|-
| GENMATLABcommand || send a command string to MATLAB
|-
| GENMATLABwaitForVariable || tells BESA to wait until Matlab has created a variable with the specified name.
|-
| GENPause || pause batch operations, allowing step-by-step operations
|-
| GENFor/GENEndFor|| a programming language-like FOR loop
|-
| GENRunProcess || runs a command line process, e.g. an external program to perform part of the data analysis in the batch
|-
| GENsaveBitmap || save a screenshot of the Source Analysis or the 3D window
|-
| SetVariable || the value of the variable is inserted into subsequent batch commands where the text contains the name flanked by % signs
|-
| GENWindowPosition || set window size and positions to a selection of standard settings, e.g. for bitmap export
|}

'''Commands for the Main Module''' - prefixed with "'''MAIN'''":

{| cellspacing="8"
| MAINArtifactCorrect || run automatic artifact correction
|-
| MAINArtifactMethod || specify the method for artifact correction
|-
| MAINArtifactOn || turn artifact correction an artifact view on or off
|-
| MAINArtifact Scan || run an artifact scan as from the Paradigm Dialog
|-
| MAINAuxiliaryFiles || associate auxiliary files (e.g. *.''ela'', *.''sfp'') with the data file
|-
| MAINAverage || average the data
|-
| MAINBaseline || specify the parameters for baseline correction
|-
| MAINDefineArtifactTopography || define an artifact topography
|-
| MAINEditDefaultEpoch || edit the default block epoch
|-
| MAINEventRead || read events from an ASCII event file
|-
| MAINEventWrite || write events to an ASCII event file
|-
| MAINExport || export or append data in the selected target format
|-
| MAINExportToBESAConnectivity || export data segments to BESA Connectivity
|-
| MAINFFT || calculates the FFT spectrum of the marked data interval
|-
| MAINFFTmean || starts an averaging procedure which calculates the mean spectral properties in pre-defined regions
|-
| MAINFFTsave || saves FFT data (generated using the ''FFT Average option'' in the ''Average ''command) to disk (*.''fma)''
|-
| MAINFileOpen || close the current file and open a new file to which the remaining batch commands will be applied
|-
| MAINFileClose || close the currently open file in a batch, provided it is not the current file in the File List
|-
| MAINFilter || set filters
|-
| MAINfMRIArtifact || turns on the fMRI artifact removal
|-
| MAINGoTo || jumps with the cursor to the specified time point
|-
| MAINICA || starts ICA decomposition of data on the current screen
|-
| MAINICAsave || saves selected ICA components as topographies in a file
|-
| MAINICAselect || opens component selection dialog for managing ICA components
|-
| MAINImportASCII || import an ASCII file into a ''<nowiki>*.fsg</nowiki>'' file.
|-
| MAINMarkBlock || mark a data block (optionally send to Source Analysis)
|-
| MAINMarkChannels || mark one or more channels, as given by the list
|-
| MAINMaxInInterval || within the current marked block, search for the largest absolute value on the specified channel
|-
| MAINMontage || change the montage (used by the Export command when saving to current montage)
|-
| MAINParadigm || load a paradigm file
|-
| MAINPatternToTrigger || convert a tag into a trigger
|-
| MAINPolygraphicFilters || sets filters for polygraphic or added channels
|-
| MAINScale || set amplitude and time scales
|-
| MAINSearchAverageView || start search average view
|-
| MAINSendToMATLAB || send data to MATLAB
|-
| MAINSplineConstant || set the spline constant used in spherical spline maps and channel interpolation
|-
| MAINTriggerRecode || the command recodes a specified trigger number to a new number
|-
| MAINTriggerSelect || edit the trigger list (cf. ''Edit / Trigger Values''...)
|-
| MAINTriggerTagDelete || delete one or more triggers or tags
|-
| MAINViewAverageBuffer || turn on the Average Buffer View and place the specified buffer number to the left in the display
|-
| MAINViewChannelType || select the channel type to display, and select channel types for mapping, export, etc
|-
| MAINViewSelected || turns selected view on or off
|}

'''General commands for Source Analysis''' - prefixed with "'''SA'''" (but see also ''MarkBlock'', which is used to send a block of data to SA and open the SA window):

{| cellspacing="8"
| SAAddSource || add a dipole or regional source to a model
|-
| SAChannelTypeForFit || switch between EEG, magnetometers or axial gradiometers, and planar gradiometers
|-
| SAConvertSource || convert a source from dipole to regional source, or from regional source to dipole
|-
| SAcorticalClara || run Cortical CLARA
|-
| SAcorticalLoreta || run Cortical LORETA
|-
| SADelete || delete current solution or all solutions, or remove current fit interval or cursor
|-
| SADICS || start DICS computation (if DICS has been precomputed in the time-frequency image command)
|-
| SADisplayMRI || switch MRI display on/off and select small or large window
|-
| SAElectrodeConfiguration</> || equivalent to pressing the Org or Std button in the Channel box of the Source analysis window
|-
| SAExit || close Source Module
|-
| SAFit || start fit
|-
| SAFitConstraint || set fit constraints, e.g. Residual Variance, Energy, Maximum Distance, Image Weighting, and their weights.
|-
| SAFitInterval || set fit or baseline interval
|-
| SAHeadModel || set the head model
|-
| SALabelSource || set the label of the specified source number
|-
| SAMinimumNorm || run a minimum norm analysis
|-
| SANewSolution || open a new solution
|-
| SAOpenSolution || open a solution from a file
|-
| SAPCA || toggle PCA display of data or residual, and transfer a selected number of components to the source model
|-
| SARegularization || set the regularization values both for discrete and distributed source images
|-
| SASaveBitmap || save a screenshot of the Source Analysis or the 3D window
|-
| SASaveLeadfields || save the leadfields of the current source model
|-
| SASaveModelWaveforms || save model waveforms
|-
| SASaveResidualWaveforms || save residual waveforms
|-
| SASaveRVandGFPWaveforms || save residual variance and global field power waveforms
|-
| SASaveSolution || save the current solution
|-
| SASaveSourceMontage || save a source montage
|-
| SASaveSourceWaveforms || save source waveforms
|-
| SASendToMATLAB || send data, model, source waveforms, images, etc. to Matlab
|-
| SASetCursor || set the cursor
|-
| SASetDefaultSourceType || set the default source type (dipole or regional source)
|-
| SASetOrActivateSource || Turn specified source on or off, or enable/disable source for fitting
|-
| SASetOrientation || set orientation (of regional source)
|-
| SASwitchCondition || switch to a specified condition
|}

'''Commands for Distributed 3D Volume Images'''

{| cellspacing="8"
| SAIMAGEBeamformer || switch between Single Source and Bilateral Beamformer image
|-
| SAIMAGEBeamformerTimeDomain || start beamformer computation in the time domain
|-
| SAimageBrainAtlas || turns on the Brain Atlas overlay on volumetric image
|-
| SAIMAGECLARA || generate CLARA image
|-
| SAIMAGEClip || clip image values under a threshold
|-
| SAIMAGEExport || save the results of minimum norm or 3D imaging method
|-
| SAIMAGEGotoMax || set the crosshair cursor at the nth maximum in the image
|-
| SAIMAGEImport || load a 3D volume image from file
|-
| SAimageImportFMRI || import fMRI image to Source Analysis Module
|-
| SAIMAGELAURA || create LAURA image
|-
| SAIMAGELORETA || create LORETA image
|-
| SAIMAGESLoreta || create sLORETA image
|-
| SAimageSESAME || start SESAME computation
|-
| SAIMAGESSLOFO || create SSLOFO image
|-
| SAIMAGEUser-Defined || create user-defined image
|-
| SAIMAGESaveLeadfields || save the leadfields of all the voxel sources in a 3D image
|-
| SAIMAGEClip || clip current 3D image
|-
| SAIMAGESmooth || smooth current 3D image
|-
| SAIMAGESetCrosshair || set the position of the crosshair in the 3D image
|}

'''Commands for Time-Frequency Analysis''' ('''TFC''')

{| cellspacing="8"
| TFCStartTFAnalysis ||(previously TFCgo) start TFC analysis using the current paradigm settings
|-
| TFCdisplay || change the TFC display (e.g. power/amplitude, coherence)
|-
| TFCsave || save numerical results to an ASCII file, or save a screenshot of the TFC window
|-
| TFCimage || start beamformer analysis on a selected time-frequency range
|-
| TFCSendToMATLAB || send TF results or single-trial data to MATLAB
|}

=== How to Average Your Data in a Batch ===

Using batch processing, several files from an experiment can be averaged at a time.

Here we summarize the steps required:

'''Before running the batch'''

* Create the paradigm, and save the paradigm file.
* Open each individual data file to check the data:
** Make sure auxiliary files are defined and loaded properly, and the data are displayed correctly.
** Eyeball the data.
** Define bad (and interpolated) channels.
** Mark artifact time ranges.
** If required, set up artifact correction for the file.
** The data file can be closed again after this step.

'''Preparing the batch'''

* Open at least one file and select ''Process / Batch Scripts''.... The file(s) should be displayed in the file list. Alternatively, just select ''Process / Batch Scripts...,'' and add the files by
** pressing the '''Add File''' button
** dragging the files from Windows Explorer
** Opening a previously saved list with ''Load File List''

* You can delete files from the list (press '''Del''') or edit the file sequence using the right click context menu.
* Select the ''Batch Tab''.
* Add commands to your script. For averaging, these would normally be
** '''Paradigm''' -- to load the paradigm file
** '''Artifact Scan''' -- to run the artifact scan
** '''Average''' -- to perform the average

* Save these commands (press '''Save Batch''').
* Test the commands on the files in the current file list: press '''OK'''
* Look at the log file (press '''View Log File''') to check the results of averaging.
* Look at the data averages to make sure they have been done correctly.
* Repeat these steps until averaging is working properly.

'''Running the batch'''

* Select ''Process / Batch Scripts''....
* Open the files you want to average in the batch in the file list:
** Any files that were open in BESA are included in the list
** Files can be added using the '''Add File''' button
** You may drag one or more files from Windows Explorer to the file list
** Alternatively, load a previously saved file list.

* Edit the file list, e.g. delete unwanted files (use the '''Del''' key or the right click context menu), or reorder the files (use '''Ctrl + cursor keys''' or context menu).
* Note that the order of files in the list specifies the order in which they will be processed in the batch script. This order will be important if all results are saved to the same target file. Otherwise the file sequence is not important.
* Optionally, save the file list (press '''Save Batch'''
* Select the ''Batch Tab'', and load the previously defined batch script with ''Load Batch''.
* Press '''OK''' to run the batch.

=== How to Merge and Compress raw data ===

Using the Export command in a batch, several data files can be merged into a single data file in BESA's data format ('''<nowiki>*.foc</nowiki>''').

This can be useful if data from one subject have been collected in several data blocks, and you want to analyze all data blocks together.

Optionally, to save space, data can be saved in compressed format.

'''Files can be merged:'''

* if they have identical channel configurations, or
* there are at least 16 EEG channels, and the export format is Standard 81 (i.e. EEG channels are interpolated to 81 standard locations).

'''How to merge files:'''

* Select '''Process / Batch Scripts...'''
* Add all the files that are to be merged to the file list:
** Any files that were open in BESA Research are included in the list
** Files can be added using the '''Add File''' button
** You may drag one or more files from Windows Explorer to the file list
** Alternatively, load a previously saved file list (''Load File List'').
* Rearrange the files in the file list to the sequence in which they should be merged.
* Select the ''Batch Tab ''and insert an "''Export"'' command, as described below.

The following dialog shows a possible configuration of the ''Export'' command:

[[Image:Batch processing (4).gif]]

* The parameters shown in the Information box are the settings chosen in the ''Export Dialog'' when the '''Select Options''' button has been pressed.
* '''Append if file already exists''' must be checked in order to merge the files.
* The '''target file name''' must be fixed, i.e. don't use the '''%basename%''' variable, because that will result in a different target file name for each source file.
* There are two variables that can be used for the segment label:
** '''%filename%''' will insert the basename of the source file into the segment label.
** '''%c%''' will insert the file number into the segment label. The number gives the position of the file in the file list. For instance, "File %c%" will generate the label "File 2" for the second file in the list.

=== Example: Data averaging in the auditory intensity experiment ===

In this example, two raw data files, '''s1.cnt''' and '''s2.cnt''', from the auditory intensity experiment will be batch averaged.

Please note that there are further tutorials covering this experiment. The first file is contaminated by many eyeblinks, and more epochs would be averaged if eye correction were used (see Viewlet demonstration on artifact correction on the BESA website). However, in this tutorial we will just use artifact rejection.

'''A. Various ways of creating a File List'''

1. '''Files that were open in BESA Research are automatically added to the File List.''' Start BESA Research and open the files '''s1.cnt '''and '''s2.cnt '''in the directory ''Examples\ERP-Auditory-Intensity''.

2. Select ''Process / Batch Scripts''.... You should see the file names in the '''''File List Tab''''' something like this:

[[Image:Batch processing (5).gif]]

3. You can resort the files in the file list alphabetically by clicking onto the '''''File List column header''''':

[[Image:Batch processing (6).gif]]

Alternatively, you can mark any file, hold down the '''Ctrl '''key and press the '''Up''' or '''Down arrow '''to move the file name up or down the list. This is the sequence in which files will be processed in the batch.

[[Image:Batch processing (7).gif]]

4. Press '''Save File List''' and save the list you have created to '''ERP-Aud-Ex1.flist'''.

5. Highlight both names and press the''' Del '''button to remove them from the list.

6. '''Files can be dragged from Windows Explorer'''. Start Windows Explorer and navigate to the ''ERP-Auditory-Intensity'' subdirectory of your BESA Research examples folder (located in the ''Public Documents'' folder of your computer). Click on '''s1.cnt''' and drag it with the mouse onto the '''''File List Tab'''''. Let go of the mouse. BESA Research opens the file, and displays the name in the File List. Repeat for '''s2.cnt.'''

7. Highlight both names and press the '''Del '''button to remove them from the list.

8. '''Files can be added using the ''Add File'' button'''. Press '''Add File''' and navigate to the ''Examples\ERP-Auditory-Intensity'' subdirectory. Select '''s1.cnt'''. Press '''Ctrl''' and select '''s2.cnt'''. Both names should then be displayed in the ''File Open'' dialog. Press '''OK''' to add the files to the file list.

9. Highlight both names and press the '''Del''' button to remove them from the list.

10. '''Files can be loaded from a previously saved file list'''. Press '''Load File List '''and select '''ERP-Aud-Ex1.flist''', the list you saved in step 6 above.

'''B. Setting up the batch'''

1. We will add three commands, '''Paradigm''', '''Artifact Scan''', and '''Average''', to create a batch that will be applied to the two files in the file list.

2. Click on the '''Batch Tab'''.

[[Image:Batch processing (8).gif]]

3. Press the '''Add Command''' button to obtain the ''Select Command'' window:

[[Image:Batch processing (9).gif]]

4. Click on '''Paradigm''' and then on '''OK''' (alternatively, double-click on '''Paradigm'''). Hit '''Browse''', navigate to the ''Auditory'' folder, and select '''AEP_Intensity.pdg''', the paradigm for the auditory intensity experiment.

[[Image:Batch processing (10).gif]]

5. Press '''OK''' to obtain the ''Load Paradigm Task'' window.

[[Image:Batch processing (11).gif]]

6. Press '''OK''', and the first task in the batch is ready, and listed in the Batch Command window. If you want to modify the command, double-click on it to open the above window, that allows to browse for a different paradigm file.

[[Image:Batch processing (12).gif]]

7. Next, we add the '''Artifact Scan''' command. Click on the '''Add Command''' button, and select ''Artifact Scan.''

[[Image:Batch processing (13).gif]]

8. Press '''OK''' to open the ''Artifact Scan Task'' window. We want to be able to view the results of the scan, and adjust thresholds and bad channels if necessary. Therefore, check the ''Wait after scan'' checkbox.

[[Image:Batch processing (14).gif]]

9. Press '''OK''' to close the ''Artifact Scan Task'' window. Our batch now contains two commands.

[[Image:Batch processing (15).gif]]

10. Finally, we will add an '''Average''' command. Press the '''Add Command''' button and select ''Average''. Press '''OK''' to open the ''Average Task ''window.

[[Image:Batch processing (16).gif]]

11. With the default settings, the average would be saved to the same directory as the data. The file name mask is set by default so that in this example the two averages would be saved to '''s1-av.fsg '''and '''s2-av.fsg'''. We will save the averaged files to subdirectory ''"Averages''" of the data directory. Uncheck the ''Use default target'' check box, change the File name mask to '''%basename%_av-test''' in order not to overwrite the predefined files.

[[Image:Batch processing (17).gif]]

12. Press '''OK '''to close the ''Average Task'' window. Our batch is now complete.

[[Image:Batch processing (18).gif]]

13. We will now save the batch so that it can be used again. Press the '''Save Batch''' button, and save to the file '''ERP-Aud-ex1.bbat'''. Note that an easy way to generate new averaging batches is to load a previously save batch and edit the commands -- it may only be necessary to edit the '''Paradigm''' command to select the relevant paradigm file, and maybe to adjust the target directory in the '''Average''' command.

14. Press '''OK''' in the ''Batch'' Window to start the batch running. As requested, the batch pauses after the artifact scan:.

[[Image:Batch processing (19).gif]]

You may now adjust the number of rejected trials, e.g. by moving the vertical red bar to the left, or exclude bad channels.

15. Press '''OK''' to continue with averaging.

[[Image:Batch processing (20).gif]]

16. Note that, in the background, the ''Batch Running'' window is providing feedback about the current file and current task.

[[Image:Batch processing (6).jpg|400px]]

17. The batch will stop again after the next artifact scan. Press '''OK''' to allow the batch to run to the end.

[[Image:Batch processing (21).gif|400px]]

18. Press '''View Log''' to view the batch protocol. If you are using Internet Explorer or Netscape family (Mozilla, Firefox) browsers, and JavaScript is enabled, you will first see just batch titles defined by the date and time the batch was started. The most recent title is at the top of the list. For other browsers, or if JavaScript was not enabled, all protocol texts are expanded as in 19 (below).

[[Image:Batch processing (22).gif|200px]]

19. Click on the first title to expand its protocol. Here, for example, the protocol gives feedback about the number of epochs that were averaged for each file.

[[Image:Batch processing (23).gif]]

20. Finally, press '''OK''' to return to the main BESA Research display. Open the averages in the ''Averages'' subdirectory to confirm that they were generated properly.

=== Example: Merging files using the Export Command ===

Here we will demonstrate the use of the '''Export '''command to merge two files. We will combine the two averages from the previous example (Data averaging in the auditory intensity experiment) into one target file.

'''A. Generate the file list'''

# Start BESA Research and load the two data files '''S1_av-test.fsg''' and '''S2_av-test.fsg''' that were saved in the previous example.
# Select ''Process / Batch Scripts....''The two file names should be displayed in the file list.
# In the file list, make sure that '''s1_av-test.fsg '''is the first file in the list. If it is not, highlight the file, and move it up using '''Ctrl+up''', or right click and select ''Move Up'' in the context menu.

'''B. Generate the batch'''

1. Press the '''Add Command''' button, and select the '''Export''' command.

2. Press '''OK''' to open the ''Export Task'' window.

[[Image:Batch processing (24).gif]]

3. Press the '''Select Options'''... button to open the ''Export Dialog''.

[[Image:Batch processing (25).gif]]

4. Since we are combining averages, select ''Hires (no compression)'' in the '''Target data format''' drop-down list (If we were merging raw data files, it is better to select compression. Press '''OK '''to close the dialog. Check'' Append if file already exists'', so that the files will be merged. Enter '''s1+s2''' in the target file name mask edit box. This ensures that both files will be saved to the same target: '''S1+S2.fsg'''.

[[Image:Batch processing (26).gif]]

5. Press '''OK '''to close the ''Export Task'' window. The '''Export '''command is displayed.  

[[Image:Batch processing (27).gif]]

6. Optionally, you may save the batch file by pressing '''Save Batch'''.

7. Press '''OK''' to run the batch, and '''OK''' in the ''Batch Completed'' window to return to the BESA main window.

8. Finally, open the file '''S1+S2.fsg''' to confirm that it contains the two merged files.

'''C. Merge raw data'''

# Repeat the above task to merge the two raw data files '''S1.cnt''' and '''S2.cnt''' into a single target file '''S1+S2.foc'''. In this case, select one of the compression options as the target data format. Note that you would not normally want to merge two files from different subjects. However, several data blocks from the same subject can conveniently be merged using this method.

Note that ''<nowiki>*.fsg</nowiki>'' files can also be merged using the ''Combine Conditions'' dialog. 

== Combine Conditions, Channels ==

=== Combine Condition Scripts ===

With the Combine-Conditions module you can do a variety of operations on BESA averages (files with the extension '''<nowiki>*.fsg</nowiki>''', and other segment files, such as '''<nowiki>*.mul</nowiki>''', '''<nowiki>*.avr</nowiki>''', '''<nowiki>*.swf</nowiki>'''):

* Create grand averages
* Combine averages (add, subtract, weighted/unweighted)
* Merge files
* Exclude unwanted averages
* Rename conditions
* Rename or resort channels
* Generate averages or differences over selected channels
* Transform the data: standard interpolated 81 electrodes, change sampling rate, change interval
* Determine peaks, mean amplitudes, or integrals on data averages
* These operations can be performed on one or more files simultaneously. Results of an operation are stored in a single target file.

The module includes four tabbed windows:

* File List: Define a list of files on which the operations will be performed.
* Condition List: List the condition names, define target condition names, and how input conditions are combined into target conditions.
* Channel List: List the channel names, define target channel names, and how input channels are combined into target channels.
* Run Scripts: Define global options for the output (e.g. spatial interpolation, resampling, copy/merge or average, peak analysis). Start the operation.
* Note that in all four tabs, configurations can be saved for future use, and the '''Load Previous''' button restores the most recently used configuration.

=== Condition List Tab ===

List the condition names, define target condition names, and how input conditions are combined into target conditions.

The first column of the list box shows a list of all the condition names found in the source files.

Rows of the list box define the source conditions. Columns define the target conditions.

'''Initial setting'''

When first selecting the tab, each column shows each condition name found in the source files (as in the example below). In the list box, there is a "+1" along the diagonal. The result of this selection is that target conditions will have the same name as source conditions. Right click on source condition labels to view properties (e.g. no. of samples, time range, sampling rate).

[[Image:Batch processing (28).gif]]

'''Editing the condition list'''

* Target condition names can be edited, inserted or deleted by clicking on the label at the top of each column.
* Click on a box within the list to toggle between "+1", "-1" and blank. These correspond to the operations:
** "+1" = add
** "-1" = subtract
** blank = do nothing
* Right click on a box for further operations: conditions can be weighted by a given factor other than 1.

'''Divide result by sum of PLUS factors'''

* Normally, when creating an average over conditions, the sum is divided by the number of conditions, or a weighted average is generated (see below).  If "''Divide result by sum of PLUS factors''" is unchecked, the conditions will be summed rather than averaged.
* Note that, when making differences between conditions, no such division is required. BESA Research will uncheck the checkbox automatically if subtraction ("-1") is specified somewhere in the condition list.

'''Weighting of averages'''

* Below the list, click on the ''Weighted Average'' row to toggle "YES" and "NO". "YES" means that averages will be weighted by the number of epochs contributing to the average. For instance, if average A contained 100 epochs and average B contained 200 epochs, the weighted average will be computed as

<div style="margin-left:1cm;margin-right:0cm;">(100 * A +  200 * B) / (100 + 200)</div>

<div style="margin-left:1cm;margin-right:0cm;">Select "NO" for an unweighted average. For the above example, the average is computed as</div>

<div style="margin-left:1cm;margin-right:0cm;">(A + B) / 2</div>

<div style="margin-left:1cm;margin-right:0cm;">Weighted averages are not permitted if one of the boxes contains a negative value.</div>

* Values other than +1 or -1 in the boxes apply a different kind of weighting. For instance, we want to compute the difference between the means of conditions A, B, C and D, E. Use a right click to specify the fraction 1/3 for each of A, B, and C, and -1/2 for each of D and E (see example below).

[[Image:Batch processing (29).gif]]

'''Save the current condition list'''

* Press the '''Save Condition List''' button.

'''Load a condition list'''

* Press the '''Load Condition List''' button.

'''Load previous settings'''

* Press the '''Load Previous''' button

'''Feedback'''

* Conditions that have different numbers of electrodes (averaging across different files) can only be combined if channels are interpolated to a standard set of electrodes.
* Conditions that have different durations or sampling rates can only be combined if the sampling rate and durations are made the same.
* Feedback about the above situations is displayed by the presence of tick marks above the list box.

=== Channel List Tab ===

List the channel names, define target channel names, and how input channels are combined into target channels.

Note that this tab is very similar in usage to the '''Condition List Tab'''. Note also that some of the functions performed in this tab could also be done in the Montage Editor. It may be a matter of convenience whether you choose to perform these operations here or in the Montage Editor.

The first column of the list box shows a list of all the channel names found in the source files.

Rows of the list box define the ''source'' channel. Columns define the'' target'' channel.

'''Initial setting'''

When first selecting the tab, each column shows each channel name found in the source files (as in the example below). In the list box, there is a "+1" along the diagonal. The result of this selection is that target channel will have the same name as source channel.

'''Combining files'''

If files with different channel configurations are included in the File List, the rows and columns of the Channel List Tab will only contain the labels for the channels that are in common among the files.

If the files in the File List have a different sequence of channels, the sequence of the first file in the list will be adopted in the Channel List.

Thus, for the initial setting, unless the "''Ignore Settings in this Tab''" checkbox is checked, the target grand average or peak/amplitude analysis, etc. will be applied using only channels that are in common among the input files, and using the channel sequence of the first file in the File List. By changing the target channels or by changing the entries in the Channel List, new channels consisting of averages or differences can be generated.

'''What can the Channel List be used for?'''

Some examples:

* Reorder or relabel channels
* Create channel differences
* Create averages over channel groups, e.g. for peak analysis
* Extract a selection of channels for peak analysis or mean amplitudes
* Create grand averages across files with different channel configurations, just using channels in common among the files

[[Image:Batch processing (30).gif]]

'''Editing the channel list'''

* Target channel names can be edited, inserted or deleted by clicking on the label at the top of each column.
* Click on a box within the list to toggle between "+1", "-1" and blank. These correspond to the operations:
** "+1" = add
** "-1" = subtract
** blank = do nothing
* Right click on a box for further operations: channels can be weighted by a given factor other than 1.

'''Divide result by sum of PLUS factors'''

* Normally, when creating an average over channels, the sum is divided by the number of channels, or a weighted average is generated (see below).  If "Divide result by sum of PLUS factors" is unchecked, the channels will be summed rather than averaged.
* Note that, when making differences between channels, no such division is required. BESA Research will uncheck the checkbox automatically if subtraction ("-1") is specified somewhere in the channel list.

'''Save the current channel list'''

* Press the '''Save Channel List''' button.

'''Load a channel list'''

* Press the '''Load Channel List '''button.

'''Load previous settings'''

* Press the '''Load Previous''' button

=== Run Scripts Tab ===

Define global options for the output (e.g. spatial interpolation, resampling, copy/merge or average, peak detection. Start the operation.

[[Image:Batch processing (7).jpg]]

'''Load or Save Settings'''

* You can save the current settings of this tab to a file (*.run) which can be loaded later.
* When you run the script, the current settings are saved automatically to a file "'''PreviousSettings.run'''".

'''Load Previous'''

* Press this button to load the previous settings (from "'''PreviousSettings.run'''").

'''Averages to Generate'''

* '''Generate separate averages for each source file'''. Averages are performed over conditions within the source file, and are then appended to the target file.
* '''Combine data from source files'''. Conditions are combined over all source files into a single target average.
* '''No averages, just copy'''. Files are copied and merged to the target file. Use this option for renaming conditions, merging files, removing unwanted averages (see below), changing the sampling rate and interval.
* '''Peaks and mean amplitudes'''. Specify time ranges for peaks, mean amplitudes, or integrals (areas).
* Note: When generating or copying averages (first three options), filters and baseline settings are turned off. For Peaks and mean amplitudes, filters and baseline settings are specified in the dialog.

'''Spatial Interpolation'''

* '''Interpolate to Standard 81 electrodes'''. The target file will contain only electrodes (other channels are omitted), using the Standard 81 configuration (as in other export functions within BESA Research). This cannot be selected if the source data contain less than 16 EEG channels.
* '''Interpolate Bad Channels'''. Bad electrode channels in the source file will be interpolated. If the above option is deselected and bad channels exist in one or more of the source files, this option is always on.

BESA Research can interpolate EEG, and MEG if the sensors are axial gradiometers or magnetometers. If other channels are marked as bad in one or more of the source files, these will be defined as bad in the target file. This applies to MEG planar gradiometers, to polygraphic data, and to ICR channels.

'''Temporal Interpolation'''

* '''Spline to New Sampling Rate and Interval'''. Data can be converted to a new sampling rate, and the interval can be changed.
** If the sampling rate is reduced, the data will be low-pass filtered at 1/3 sampling frequency before reduction.
** If the sampling interval is changed, the prestimulus and poststimulus intervals are limited by the smallest intervals in the conditions contributing to the averages. These limits are shown below the edit boxes.

'''Peaks and Mean Amplitudes'''

[[Image:Batch processing (31).gif]]

'''Peaks:'''

* Select the time range between which peaks are to be determined.
* Select the montage on which the peaks are to be determined.
* Define the filter settings.
* Define the baseline settings.
* Specify whether peaks are to be defined at one latency: if so, select the channel on which peaks are to be detected.
* Specify whether you want to find positive or negative peaks.

'''Mean amplitudes and areas:'''

* Select the time range over which the mean amplitudes or areas are to be determined.
* Select the montage on which the mean amplitudes or areas are to be determined.
* Define the filter settings.
* Note that when computing areas, data are first rectified (made positive) and then summed over the time range.

'''Output options of the analysis:'''

* A single ASCII file that contains the result of the analysis for all data sets, conditions, and channels including header and information lines.
* A sparse output suitable for import in SPSS. Each variable (e.g. a latency, a channel amplitude) constitutes one column of the output file.
* Direct transfer to MATLAB into a struct besa_peak. For more information on the data transfer from BESA Research to MATLAB, please refer to help chapter ''“The MATLAB interface”.''

'''Starting the Operation'''

* Press '''OK''' to start the operation. After the operation is completed, and the "Open target file in BESA" box is checked, BESA Research will open the target file.  "Open target file in BESA" cannot be checked if "Peaks and mean amplitudes" was selected - then the result of the operation will be an ASCII file or a MATLAB transfer.
* You will be asked for the name of the target file (unless a MATLAB transfer of peak data has been performed).

'''Restrictions'''

* Depending on source file configurations, not all options above are selectable. For instance, if two files contain different numbers of electrodes, and the "''Ignore Settings in this Tab''" checkbox is checked in the '''''Channel List''''' Tab, spatial interpolation to Standard 81 is enforced in the target. Similarly, if different sampling rates are used in different files, temporal interpolation is enforced.
* You are not allowed to add files to the file list if the channel configuration is different, and the data cannot be combined with Standard 81 interpolation. Since Standard 81 interpolation is only possible for EEG, multiple files without EEG can only be loaded if they have the same number of channels.

=== How to Create Grand Averages ===

* Open the files you want to average in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. To average across different conditions, click in the list boxes to obtain "+1" for each source condition to combine, and rename the target condition to define a meaningful name for the average.
* Click on the '''Run Scripts Tab'''.
* If you have more than one file, specify whether averages should be generated across files ('''Combine data from source files''') or within files ('''Generate separate averages for each source file''').
* Select other options if required (spatial or temporal resampling).
* Press '''OK'''.

=== How to Generate Differences Between Conditions ===

* Open the files you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. To create differences, click in the list boxes to obtain "+1" for one of the source conditions, and "-1" for the source condition to subtract, and rename the target condition to define a meaningful name for the difference.
* Click on the '''Run Scripts Tab'''.
* If you have more than one file, specify whether averages should be generated across files ('''Combine data from source files''') or within files ('''Generate separate averages for each source file''').
* Select other options if required (spatial or temporal resampling).
* Press '''OK'''. An average of the differences is generated. If only one example of each condition exists, e.g. in a grand average file, the result is the difference between conditions.

=== How to Merge Files ===

* Open the files you want to merge in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions''...).
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press '''OK'''.

'''Notes'''

* If the source files have different electrode configurations, use the Standard 81 configuration for the target.
* If the source files have different sampling rates or intervals, use Temporal Interpolation.

=== How to Remove Unwanted Averages ===

'''Removing one or more unwanted segments'''

* Normally, all conditions are read from a source file. To exclude one or more segments from operations in the Combine Conditions module, mark the segments as artifacts in the main program display. It is sufficient for the beginning or the end of an artifact interval to be within the segment for the segment to be excluded.
* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press''' OK'''.
* The target file contains the copied data without the conditions that were marked as averages.

'''Removing one or more unwanted conditions (by label)'''

* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Deselect the target conditions you want to omit (replace the "+1" by a blank).
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press''' OK'''.
* The target file contains the copied data without the conditions that were marked as artifacts.

=== How to Rename Conditions ===

* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions''...).
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. Click on column headings to rename the target conditions.
* Click on the''' Run Scripts Tab'''. Select "''No averages, just copy''".
* Press '''OK'''.
* The target file contains the copied data with the renamed conditions.

=== How to Change the Sampling Rate ===

* Open the file(s) you want to change in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...'').
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Select "''Spline to New Sampling Rate and Interval''" and type the new sampling rate into the edit box.
* Press '''OK'''.

=== Example: Create grand average and combinations of conditions ===

In this example, we will generate a grand average of the results of the Auditory Intensity Experiment. The experiment includes averages from five different stimulus intensities. We will create a grand average over each intensity, but also include means over the two lowest and the two highest intensities, and the difference between these two combinations.

'''A. File selection'''

# Start BESA Research and open files '''S1_av.fsg - S10_av.fsg''' in the ''Examples\ERP-Auditory-Intensity'' folder. The files contain the individual averaged data of the 10 subjects who participated in this study.
# Select ''ERP / Combine Conditions...'' The file list should display the two files, with feedback about the number of averages and conditions. 8 epochs are found. See the ''“Data averaging in the auditory intensity'' ''experiment”'' example for examples how to manipulate the file list.

[[Image:Batch processing (32).gif]]

'''B. Define conditions'''

1. Click on the '''Condition List Tab'''. The initial window defines target conditions with the same name as the source conditions. To generate the grand average over these conditions we could proceed without further changes to the '''Run Scripts Tab'''. However, we want to modify the condition list and create a condition that contains the grand averaged difference between the''' High''' and '''Low''' conditions.

[[Image:Batch processing (8).jpg]]

2. Click on the '''All '''column label. In the resulting window, rename condition '''All''' to''' Difference'''. Then press '''OK'''.

[[Image:Batch processing (33).gif]]

3. The last column is now labeled '''Difference.''' Left-click twice onto the ‘'''+1’''' entry that links this condition to the '''All '''input condition. This will remove the link and leave the field blank. To define the ‘Difference’ condition as the average of ‘High’ minus ‘Low’ over subjects, left-click once into the field linking input '''High''' with target '''Difference''' to generate an entry ‘'''+1’''' in this field. Left-click twice into the field linking input '''Low '''with target '''Difference''' to generate an entry '-'''1'''’.

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;">[[Image:Batch processing (35).gif]]</div>

4. Press '''Save Condition List''' and save the list to '''ERP-aud-ex1.clist'''. This condition combination can thus be loaded later using the '''Load Condition List''' button.

'''C. Run the script'''

# Click on the '''Run Script Tab'''.
# The default tab settings are ready for generating the grand average ('''Combine data from source file''' and '''Open target file in BESA''' should be checked). Just press '''OK'''. Enter '''All_Subjects_cc-test.fsg''' as file name and press''' Save'''.

The resulting file contains the 8 target conditions, 60db, 70dB, 80dB, 90dB, 100dB, Low, High, and Difference.

=== Example: Average files from different experiments ===

This example is intended to illustrate several features of the ''Combine Conditions'' Dialog, such as electrode interpolation and resampling. We will combine an average from the Auditory Intensity experiment with one from the P300 auditory experiment. In this particular case, it is not a very meaningful thing to do, but it shows what is possible. For instance, the same experiment may have been performed using different sampling rates or electrode combinations. This example shows how such data may be combined.

'''A. File selection'''

# Start BESA Research and open the file '''All_Subjects_GA.fsg''' in the ''Examples\ERP-Auditory-Intensity'' folder. The file contains the grand average data from the auditory intensity experiment.
# Open the file '''RareFrequentResponseLeft.fsg''' in the ''Examples\ERP-P300-Auditory'' folder. This file contains averages from the P300 auditory experiment.
# Select ''ERP / Combine Conditions... ''Note that the files have different sampling rates and different numbers of electrodes.

[[Image:Batch processing (36).gif]]

'''B. Define conditions'''

1. Click on the '''Condition List Tab'''. Note that the feedback text at the bottom of the window displays the text "Standard 81 interpolation required to generate average; Across files: resampling or change in time range required to generate average". The condition labels show all the names from both files.

[[Image:Batch processing (37).gif]]

2. We will exclude most conditions, and just combine the most similar conditions from the two experiments: the "Standard" and the "80dB" conditions. Click on the title of the first column,''' Blink'''. Select “''Delete all conditions to the right of this column”'', and press '''OK'''.

[[Image:Batch processing (38).gif]]

3. Click on the title again, and rename the target condition to "Standard".

[[Image:Batch processing (39).gif]]

4. Click twice in the first line to remove the "+1" entry there. Click once in the third row ("Frequent"), and in the 7th row ("80dB"), to display "+1" at each entry. Thus, just two of the conditions will be combined into one target condition.

[[Image:Batch processing (40).gif]]

'''C. Run the script'''

1. Click on the '''Run Script Tab'''.

[[Image:Batch processing (41).gif]]

2. Note that '''Interpolate to Standard 81 electrodes''' is checked and grayed: since two different electrode sets are to be combined, we can only do this by interpolating electrodes. Also, both '''Spline to new sampling rate''' and '''Clip interval '''are checked and grayed. Again, these settings are required in order to be able to average the two data files together. The sampling rate is set to the higher of the two selections. The time range is set to the largest possible range that can be clipped from the two data sets. For now, leave these settings as they are, and press '''OK'''. Save the target to '''TestCombineExpts_CC-std81.fsg'''.

{{BESAManualNav}}

BESA Research Batch Processing

2021-05-05T07:30:23Z

Abinash: Reverted edits by Mateusz (talk) to last revision by Jamie

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = 6.1 or higher
}}



== Combine Conditions and Batch Module: Introduction ==

Functions of this module are started by selecting the menu operations "'''ERP / Combine Conditions...'''" and "'''Process / Batch Scripts...'''".

* '''Combine Condition Scripts''' provides various operations on BESA averages.
* '''Batch Scripts''' provides batch operations on all data files.
* Note that a batch script can also be performed on the current file by selecting "'''Process / Run Batch...'''" or by typing the shortcut key "'''R'''".

== File List Tab ==

Define a list of files on which the operations will be performed. The tab is the same for Combine Conditions Scripts and for Batch Scripts. Combine Conditions Scripts only allows you to open BESA average files (e.g. '''<nowiki>*.fsg</nowiki>''' and '''<nowiki>*.avr</nowiki>''', but also '''.mul''', '''.raw''', '''.swf''', and '''.foc''' if the files have a defined pre-stimulus interval), whereas Batch Scripts allows you to open any data file whose format is known to BESA Research.

When the Combine-Conditions or the Batch module is started, all currently opened (Combine-Conditions: averages only) files are displayed in the list.

To the right of each file name, the number of electrodes, total number of channels, and the sampling rate used in the file are displayed. In the Combine-Conditions module, the number of Epochs (segments) and the number of differently-named conditions are also shown.

'''Add files to the list'''

* Press the '''Add File ''' button.
* Drag one or more files from Windows Explorer onto the window.

'''Remove files from the list'''

* Right click on the file name and confirm the delete operation in the resulting dialog.
* Mark one or more file names in the list (e.g. hold down the''' Ctrl''' key to mark multiple files). Right click to obtain the context menu and select "'''Delete'''", or just press the '''Del '''key.

'''Reorder files within the current file list'''

* Right click on the file name and select "'''''Move Up'''''" or "'''''Move Down'''''".
* Mark one or more file names in the list (e.g. hold down the '''Ctr'''l key to mark multiple files). Right click to obtain the context menu and select "'''''Move Up'''''" or "'''''Move Down'''''", or hold down the''' Ctrl''' key '''and '''press the '''Up''' and '''Down arrows'''.

'''Sort the current file list alphabetically'''

* Click on the File bar above the list

'''Save the current file list'''

* Press the '''Save File List''' button.

'''Load a file list'''

* Press the '''Load File List''' button, or the '''Load Previous''' button to load the most recently used file list.

'''Which conditions are read from a source file? (Combine-Conditions module only)'''

* Normally, all conditions are read from a source file. To exclude one or more segments from operations in the Combine Conditions module, mark the segments as artifacts in the main program display. It is sufficient for the beginning or the end of an artifact interval to be within the segment for the segment to be excluded.

'''File list from Combine Conditions:'''

[[Image:Batch processing (1).png]]

'''Don't try to open here... (Batch only)'''

By default, this checkbox is unchecked.

In the checked state, BESA Research doesn't check if it can open the file. Use this function '''only''' if the file is ASCII and you want to use the '''ImportASCII '''batch command.

'''File List from Batch Scripts''':

[[Image:Batch processing (2).png]]

== Batch Processing ==

=== Batch Processing Scripts ===

With Batch Scripts, you can define a set of operations (e.g. Artifact Scan, Average) and apply these to several data files.

These operations include

* Load Paradigm
* Artifact Scan
* Average
* Export (and Merge)
* File Open (switch to another data file)
* Set filters
* Specify a montage (used, for example, for export to current montage)
* Run automatic eye and EKG artifact correction
* Turn artifact correction and view on and off
* Read and write events
* Edit default block epoch (for export around triggers)
* Edit triggers (for export around triggers)
* Mark a block for export, or send the block to Source Analysis or Top View
* Convert patterns to triggers
* Attach auxiliary files (e.g. elp, sfp) to the data file
* Send to MATLAB
* Specify display configurations for the BESA Research Main, SA, and Top View windows

An additional set of commands are available for operations in the '''Source Analysis Module''', allowing to load, create and fit dipole models, and save the results.

A further set of commands apply to '''Time-Frequency Analysis''', allowing to start TFC, change the display, save results, and run the beamformer or DICS analyses on a selected time-frequency range.

[[Image:Batch processing (3).png]]

These operations will be extended in future program releases.

The module includes two tabbed windows:

* '''File List''': Define a list of files on which the operations will be performed.
* '''Batch''': Define or load '''batch commands'''. Run the batch.

=== Batch Tab ===

Load or define batch commands, and then apply them to the files in the File List.

[[Image:Batch processing (4).png]]

'''Add Command'''

* Press '''Add Command''' to add a new command to the batch. The following dialog is opened, showing the available commands:

[[Image:Batch processing (3).png]]

* Select the desired command and press '''OK''' or double-click on the command. A dialog box is opened, allowing to specify individual command parameters.
* If you click on "Apply at beginning of batch" or "Apply at end of batch", the command will only be run at the beginning or the end of a batch. You can use this, for example, at the end of a batch to start a Matlab script to perform statistics on the results of the batch.

'''Load and Save Batch'''

* Press '''Load Batch''' to load a previously defined batch or '''Save Batch''' to save the current batch to a file ('''<nowiki>*.bbat</nowiki>''').

'''Load Previous'''

* Press '''Load Previous''' to load the most recently used batch file. Whenever a batch is run, the current set of commands is written to the file '''Previous.bbat in''' the '''Scripts/Batch''' subdirectory. This file is loaded when you press '''Load Previous'''.

'''Clear All'''

* Clears all commands from the window.

'''View Log File'''

* Each time a batch is run, BESA Research adds information about the batch to a log file, with headings showing the date and time the batch was started. The file is opened automatically in Internet Explorer if errors occurred during processing. Otherwise you may open the file by pressing the '''View Log File''' button here or in the dialog that is displayed at the end of batch processing. 
* The log file is saved in xml format, and a JavaScript is used to format the display in Internet Explorer or Netscape family browsers. JavaScript should be enabled in the browser to obtain an optimal display of the results. If JavaScript is enabled, the log file is displayed as a list of headings for each batch. Click on a heading to display the results of the corresponding batch.
* To open the log file in NotePad, hold the''' Shift '''key down when pressing the '''View Log File''' button.

'''Batch Command List'''

* Double-click on a command to edit it. See chapter “''Batch Commands”'' for descriptions of the dialogs that are opened to edit each command.
* Right click on a command to open a context menu allowing more options.

[[Image:Batch processing (5).png]]

* '''Delete''', '''Move Up''', '''and Move Down''' can also be applied to multiple selections.
* If you have made a multiple selection, the '''Del '''button will delete all the marked commands. '''Ctrl '''plus '''Up''' or '''Down''' '''cursor keys''' will move the marked commands up or down.
* '''Toggle Comment''' will add or remove a semicolon (;) in front of the command, to deactivate or reactivate the command.
* '''Toggle Command Only at Start/End''' will add or remove the text "Start_" or "End_" in front of the command. With these prefixes, the command will only be performed when the first file ("Start_") or the last file ("End_") in the file list is being processed.

'''Single Step Mode'''

* Check this item to step through the batch, one command at a time. A dialog is opened after each command, allowing to run the next command, continue the batch without single steps, or stop running the batch. See the'' “Pause''” command for further details.
* During a batch, press and hold down the '''Pause''' or '''Delete''' key to interrupt the batch and enter Single Step Mode. Press and hold down the '''Esc''' key to cancel the batch.

'''Changes in batch written to database'''

* Checked by default. If this item is unchecked, file display settings, such as Montage setting and Artifact correction display, are not written to the database. When the file is next opened in BESA Research, the settings made in the batch are not retained.

'''Leave files in the file list open after running the batch'''

* If this item is checked, files in the file list will remain open after the batch. This is useful, for instance, if you want to open a set of files, specifying the same montage and/or filter settings for each file.

Press '''OK''' to start running the batch. Each command is then applied in succession to each file in the File List.

Note that, while a batch is running press and hold down the''' Pause''' or '''Delete''' key to interrupt the batch and enter Single Step Mode. Press and hold down the '''Esc''' key to cancel the batch.

=== The log file ===

A protocol of each batch is written to the log file '''Scripts/Log/Batch.xml.'''

When you press the '''View Log File '''button, the file is opened in your default browser for xml files. The file will be opened automatically if there was an error during batch processing, unless you have used the ''BatchError'' batch command to suppress this behavior.

'''DHTML formatting of the log file'''

The xml file is formatted using JavaScript (Dynamic HTML). If JavaScript is enabled in your browser, you will first see a list of batch protocol titles, labeled by the date and time at which the batch was started. The most recent batch is at the top of the list.:

[[Image:Batch processing (6).png|200px]]

Click on the title to view the protocol for the corresponding batch:

[[Image:Batch processing (7).png|600px]]

'''JavaScript and XP Service Pack 2'''

By default, if the log file is opened in Internet Explorer after XP Service Pack 2 has been installed, IE will warn you with the message: "''To help protect your security, Internet Explorer has restricted this file from'' ''showing active content that could access your computer".'' All the protocols in the log file are displayed. You may safely click on the options to allow active content in the log file, if you want to display the file as described above.

'''Backup of the log file'''

When the log file is written, a backup of the previous version is written to '''batch.xml.bak'''.

If the size of the log file exceeds 200 KB, it is renamed to '''batch.xml_date_time''' (e.g. '''Batch.xml_2004-10-08_10-53-32'''), and a new version of '''batch.xml''' is created.

=== Placeholders ===

A powerful feature of the batch commands is the ability to define file names and specify standard paths using placeholders. These are text strings enclosed by percentage (%) signs. They can be used in all batch commands where file names are specified.

'''Basename'''

{| class="wikitable"
! Placeholder !! Description !! Example
|-
|style="text-align:center;" width="10%"|'''%basename%'''
|width="40%"|replaced by the basename of the data file in the File List.
|width="40%"|If the data file is named "f-spike.fsg", "%basename%-export.fsg" will be interpreted as "f-spike-export.fsg".
|-
|style="text-align:center;"|'''%basename-n%'''
|replaced by the basename of the data file in the File List, but removing the last "n" characters from the name.
|If the data file is named "dongle-BB.fsg", "%basename-3%" will be replaced by "dongle", because the last 3 characters of the basename have been removed.
|-
|style="text-align:center;"|'''%-nbasename%'''
|replaced by the basename of the data file in the File List, but removing the first "n" characters from the name.
|If the data file is named "BB-dongle.fsg", "%-3basename%" will be replaced by "dongle", because the first 3 characters of the basename have been removed.
|-
|style="text-align:center;"|'''%scripts%'''
|replaced by the path to the Scripts folder.
|"%scripts%Batch" is where batches are saved by default; "%scripts%MATLAB" is the location of the standard Matlab scripts used by BESA Research.
|-
|style="text-align:center;"|'''%montages%'''
|replaced by the path to the Montages folder.
|
|-
|style="text-align:center;"|'''%examples%'''
|replaced by the path to the Examples folder.
|
|}



'''Placeholders for folders'''

The following placeholders are the same as those used in the [Folders] section of '''Besa.ini''':

The strings enclosed by percent signs (%) are placeholders for the following folders in English-language versions of Windows. Folder names are different for Vista and XP/2000 and for other language settings. BESA Research will substitute the placeholders by the appropriate folder name for the system (W2K, XP, Vista, or Win7) and the system language:

* '''Windows 7 (English)'''

<div style="margin-left:1.27cm;margin-right:0cm;"> '''%localapp%''' = "C:\Users\[user]\AppData\Local\BESA\Research_5_3", where [user] is the logon name of the current user. This folder is directly accessible from the Desktop as "Desktop\[user]\AppData\Local\BESA\Research_5_3".</div>

<div style="margin-left:1.27cm;margin-right:0cm;"> '''%publicprog%''' = "C:\Users\Public\Public Documents\BESA\Research_5_3". This folder is directly accessible from the Windows Explorer under "Libraries\Documents\Public Documents\BESA\Research_5_3".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = "C:\Users\[user]\Documents\BESA\Research_5_3", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as "Libraries\Documents\My Documents\Research_5_3" or "Desktop\[User]\My Documents\BESA\Research_5_3.</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_5_3".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as''' %progdir%'''</div>

* '''Windows Vista (English):'''

<div style="margin-left:1.27cm;margin-right:0cm;">'''%localapp%''' = "C:\Users\[user]\AppData\Local\BESA\Research_5_3", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as "Desktop\[user]\AppData\Local\BESA\Research_5_3".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%publicprog%''' = "C:\Users\Public\Public Documents\BESA\Research_5_3". This folder is directly accessible from the Windows Explorer under "Desktop\Public\Public Documents\BESA\Research_5_3".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = "C:\Users\[user]\Documents\BESA\Research_5_3", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as "Desktop\[user]\Documents\BESA\Research_5_3".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_5_3".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as''' %progdir%  '''</div>

* '''Windows XP (English):'''

<div style="margin-left:1.27cm;margin-right:0cm;">'''%localapp%''' = "C:\Documents and Settings\[user]\Local Settings\Application Data\BESA\Research_5_3", where [user] is the logon name of the current user.</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%publicprog%''' = "C:\Documents and Settings\All Users\Documents\BESA\Research_5_3". This folder is directly accessible from the Windows Explorer under "Desktop\Shared Documents\BESA\Research_5_3".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = "C:\Documents and Settings\[user]\My Documents\BESA\Research_5_3", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as "Desktop\My Documents\BESA\Research_5_3".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\Research_5_3".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as '''%progdir%'''  </div>

* '''Windows 2000 (English):'''

<div style="margin-left:1.27cm;margin-right:0cm;">'''%localapp%''' = "C:\Documents and Settings\[user]\Local Settings\Application Data\BESA\Research_5_3", where [user] is the logon name of the current user.</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%publicprog%''' = "C:\Documents and Settings\All Users\Documents\BESA\Research_5_3".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%privateprog%''' = "C:\Documents and Settings\[user]\My Documents\BESA\Research_5_3", where [user] is the logon name of the current user. This folder is directly accessible from the Windows Explorer as "Desktop\My Documents\BESA\Research_5_3".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%progdir%''' = the BESA Research root folder. In a default installation, this is "C:\Program Files\BESA\\Research_5_3".</div>

<div style="margin-left:1.27cm;margin-right:0cm;">'''%besaroot%''' is the same as '''%progdir%'''</div>

=== Batch Commands ===

Batch commands are selected when the "'''Add Command'''" button is pressed in the Batch Tab. The commands are subdivided into five categories: General commands, commands for the Main module, for the Source Analysis module, imaging commands in the Source Analysis module, and commands for Time-Frequency Analysis. The commands have prefixes,''' GEN''', '''MAIN''',''' SA''', '''SAIMAGE''', and''' TFC'''), which identify the category. For compatibility with older program versions, old batches without the prefixes are accepted.

Detailed descriptions of each batch command are available in the electronic help chapter “''Batch Processing and Combining Conditions / Batch Processing / Batch Commands”.''

'''General commands''' - prefixed with "'''GEN'''" (can be used anywhere):

{| cellspacing="8"
|GENBatchError || used to change program behavior when errors occur
|-
|GENComment || comment in the batch script: no batch functionality
|-
|GENMATLABcommand || send a command string to Matlab
|-
|GENMATLABwaitForVariable || tells BESA to wait until Matlab has created a variable with the specified name.
|-
|GENPause || pause batch operations, allowing step-by-step operations
|-
|GENFor/GENEndFor|| a programming language-like FOR loop
|-
|GENRunProcess || runs a command line process, e.g. an external program to perform part of the data analysis in the batch
|-
|GENWindowPosition || set window size and positions to a selection of standard settings, e.g. for bitmap export
|}

'''Commands for the Main Module''' - prefixed with "'''MAIN'''":

{| cellspacing="8"
| MAINArtifactCorrect || run automatic artifact correction
|-
| MAINArtifactMethod || specify the method for artifact correction
|-
| MAINArtifactOn || turn artifact correction an artifact view on or off
|-
| MAINArtifact Scan || run an artifact scan as from the Paradigm Dialog
|-
| MAINAuxiliaryFiles || associate auxiliary files (e.g. *.''ela'', *.''sfp'') with the data file
|-
| MAINAverage || average the data
|-
| MAINBaseline || specify the parameters for baseline correction
|-
| MAINEditDefaultEpoch || edit the default block epoch
|-
| MAINEventRead || read events from an ASCII event file
|-
| MAINEventWrite || write events to an ASCII event file
|-
| MAINExport || export or append data in the selected target format
|-
| MAINFFT || calculates the FFT spectrum of the marked data interval
|-
| MAINFFTmean || starts an averaging procedure which calculates the mean spectral properties in pre-defined regions
|-
| MAINFFTsave || saves FFT data (generated using the ''FFT Average option'' in the ''Average ''command) to disk (*.''fma)''
|-
| MAINFileOpen || close the current file and open a new file to which the remaining batch commands will be applied
|-
| MAINFilter || set filters
|-
| MAINfMRIArtifact || turns on the fMRI artifact removal
|-
| MAINGoTo || jumps with the cursor to the specified time point
|-
| MAINICA || starts ICA decomposition of data on the current screen
|-
| MAINICAsave || saves selected ICA components as topographies in a file
|-
| MAINICAselect || opens component selection dialog for managing ICA components
|-
| MAINImportASCII || import an ASCII file into a ''<nowiki>*.fsg</nowiki>'' file.
|-
| MAINMarkBlock || mark a data block (optionally send to Source Analysis)
|-
| MarkChannels || mark one or more channels, as given by the list
|-
| MAINMaxInInterval || within the current marked block, search for the largest absolute value on the specified channel
|-
| MAINMontage || change the montage (used by the Export command when saving to current montage)
|-
| MAINParadigm || load a paradigm file
|-
| MAINPatternToTrigger || convert a tag into a trigger
|-
| MAINPolygraphicFilters || sets filters for polygraphic or added channels
|-
| MAINScale || set amplitude and time scales
|-
| MAINSearchAverageView || start search average view
|-
| MAINSendToMATLAB || send data to MATLAB
|-
| MAINTriggerSelect || edit the trigger list (cf. ''Edit / Trigger Values''...)
|-
| MAINTriggerTagDelete || delete one or more triggers or tags
|-
| MainViewAverageBuffer || turn on the Average Buffer View and place the specified buffer number to the left in the display
|}

'''General commands for Source Analysis''' - prefixed with "'''SA'''" (but see also ''MarkBlock'', which is used to send a block of data to SA and open the SA window):

{| cellspacing="8"
| SAAddSource || add a dipole or regional source to a model
|-
| SAChannelTypeForFit || switch between EEG, magnetometers or axial gradiometers, and planar gradiometers
|-
| SAConvertSource || convert a source from dipole to regional source, or from regional source to dipole
|-
| SAcorticalClara || run Cortical CLARA
|-
| SAcorticalLoreta || run Cortical LORETA
|-
| SADelete || delete current solution or all solutions, or remove current fit interval or cursor
|-
| SADICS || start DICS computation (if DICS has been precomputed in the time-frequency image command)
|-
| SADisplayMRI || switch MRI display on/off and select small or large window
|-
| SAElectrodeConfiguration || equivalent to pressing the Org or Std button in the Channel box of the Source analysis window
|-
| SAExit || close Source Module
|-
| SAFit || start fit
|-
| SAFitConstraint || set fit constraints, e.g. Residual Variance, Energy, Maximum Distance, Image Weighting, and their weights.
|-
| SAFitInterval || set fit or baseline interval
|-
| SAMinimumNorm || run a minimum norm analysis
|-
| SANewSolution || open a new solution
|-
| SAOpenSolution || open a solution from a file
|-
| SAPCA || toggle PCA display of data or residual, and transfer a selected number of components to the source model
|-
| SARegularization || set the regularization values both for discrete and distributed source images
|-
| SASaveBitmap || save a screenshot of the Source Analysis or the 3D window
|-
| SASaveLeadfields || save the leadfields of the current source model
|-
| SASaveModelWaveforms || save model waveforms
|-
| SASaveResidualWaveforms || save residual waveforms
|-
| SASaveRVandGFPWaveforms || save residual variance and global field power waveforms
|-
| SASaveSolution || save the current solution
|-
| SASaveSourceMontage || save a source montage
|-
| SASaveSourceWaveforms || save source waveforms
|-
| SASendToMATLAB || send data, model, source waveforms, images, etc. to Matlab
|-
| SASetCursor || set the cursor
|-
| SASetDefaultSourceType || set the default source type (dipole or regional source)
|-
| SASetOrActivateSource || Turn specified source on or off, or enable/disable source for fitting
|-
| SASetOrientation || set orientation (of regional source)
|-
| SASwitchCondition || switch to a specified condition
|}

'''Commands for Distributed 3D Volume Images'''

{| cellspacing="8"
| SAIMAGEBeamformer || switch between Single Source and Bilateral Beamformer image
|-
| SAimageBrainAtlas || turns on the Brain Atlas overlay on volumetric image
|-
| SAIMAGECLARA || generate CLARA image
|-
| SAIMAGEExport || save the results of minimum norm or 3D imaging method
|-
| SAIMAGEGotoMax || set the crosshair cursor at the nth maximum in the image
|-
| SAIMAGEImport || load a 3D volume image from file
|-
| SAimageImportFMRI || import fMRI image to Source Analysis Module
|-
| SAIMAGELAURA || create LAURA image
|-
| SAIMAGELORETA || create LORETA image
|-
| SAIMAGESLoreta || create sLORETA image
|-
| SAimageSESAME || start SESAME computation
|-
| SAIMAGESSLOFO || create SSLOFO image
|-
| SAIMAGEUser-Defined || create user-defined image
|-
| SAIMAGESaveLeadfields || save the leadfields of all the voxel sources in a 3D image
|-
| SAIMAGEClip || clip current 3D image
|-
| SAIMAGESmooth || smooth current 3D image
|-
| SAIMAGESetCrosshair || set the position of the crosshair in the 3D image
|}

'''Commands for Time-Frequency Analysis''' ('''TFC''')

{| cellspacing="8"
| TFCStartTFAnalysis ||(previously TFCgo) start TFC analysis using the current paradigm settings
|-
| TFCdisplay || change the TFC display (e.g. power/amplitude, coherence)
|-
| TFCsave || save numerical results to an ASCII file, or save a screenshot of the TFC window
|-
| TFCimage || start beamformer analysis on a selected time-frequency range
|-
| TFCSendToMATLAB || send TF results or single-trial data to MATLAB
|}

=== How to Average Your Data in a Batch ===

Using batch processing, several files from an experiment can be averaged at a time.

Here we summarize the steps required:

'''Before running the batch'''

* Create the paradigm, and save the paradigm file.
* Open each individual data file to check the data:
** Make sure auxiliary files are defined and loaded properly, and the data are displayed correctly.
** Eyeball the data.
** Define bad (and interpolated) channels.
** Mark artifact time ranges.
** If required, set up artifact correction for the file.
** The data file can be closed again after this step.

'''Preparing the batch'''

* Open at least one file and select ''Process / Batch Scripts''.... The file(s) should be displayed in the file list. Alternatively, just select ''Process / Batch Scripts...,'' and add the files by
** pressing the '''Add File''' button
** dragging the files from Windows Explorer
** Opening a previously saved list with ''Load File List''

* You can delete files from the list (press '''Del''') or edit the file sequence using the right click context menu.
* Select the ''Batch Tab''.
* Add commands to your script. For averaging, these would normally be
** '''Paradigm''' -- to load the paradigm file
** '''Artifact Scan''' -- to run the artifact scan
** '''Average''' -- to perform the average

* Save these commands (press '''Save Batch''').
* Test the commands on the files in the current file list: press '''OK'''
* Look at the log file (press '''View Log File''') to check the results of averaging.
* Look at the data averages to make sure they have been done correctly.
* Repeat these steps until averaging is working properly.

'''Running the batch'''

* Select ''Process / Batch Scripts''....
* Open the files you want to average in the batch in the file list:
** Any files that were open in BESA are included in the list
** Files can be added using the '''Add File''' button
** You may drag one or more files from Windows Explorer to the file list
** Alternatively, load a previously saved file list.

* Edit the file list, e.g. delete unwanted files (use the '''Del''' key or the right click context menu), or reorder the files (use '''Ctrl + cursor keys''' or context menu).
* Note that the order of files in the list specifies the order in which they will be processed in the batch script. This order will be important if all results are saved to the same target file. Otherwise the file sequence is not important.
* Optionally, save the file list (press '''Save Batch'''
* Select the ''Batch Tab'', and load the previously defined batch script with ''Load Batch''.
* Press '''OK''' to run the batch.

=== How to Merge and Compress raw data ===

Using the Export command in a batch, several data files can be merged into a single data file in BESA's data format ('''<nowiki>*.foc</nowiki>''').

This can be useful if data from one subject have been collected in several data blocks, and you want to analyze all data blocks together.

Optionally, to save space, data can be saved in compressed format.

'''Files can be merged:'''

* if they have identical channel configurations, or
* there are at least 16 EEG channels, and the export format is Standard 81 (i.e. EEG channels are interpolated to 81 standard locations).

'''How to merge files:'''

* Select '''Process / Batch Scripts...'''
* Add all the files that are to be merged to the file list:
** Any files that were open in BESA Research are included in the list
** Files can be added using the '''Add File''' button
** You may drag one or more files from Windows Explorer to the file list
** Alternatively, load a previously saved file list (''Load File List'').
* Rearrange the files in the file list to the sequence in which they should be merged.
* Select the ''Batch Tab ''and insert an "''Export"'' command, as described below.

The following dialog shows a possible configuration of the ''Export'' command:

[[Image:Batch processing (4).gif]]

* The parameters shown in the Information box are the settings chosen in the ''Export Dialog'' when the '''Select Options''' button has been pressed.
* '''Append if file already exists''' must be checked in order to merge the files.
* The '''target file name''' must be fixed, i.e. don't use the '''%basename%''' variable, because that will result in a different target file name for each source file.
* There are two variables that can be used for the segment label:
** '''%filename%''' will insert the basename of the source file into the segment label.
** '''%c%''' will insert the file number into the segment label. The number gives the position of the file in the file list. For instance, "File %c%" will generate the label "File 2" for the second file in the list.

=== Example: Data averaging in the auditory intensity experiment ===

In this example, two raw data files, '''s1.cnt''' and '''s2.cnt''', from the auditory intensity experiment will be batch averaged.

Please note that there are further tutorials covering this experiment. The first file is contaminated by many eyeblinks, and more epochs would be averaged if eye correction were used (see Viewlet demonstration on artifact correction on the BESA website). However, in this tutorial we will just use artifact rejection.

'''A. Various ways of creating a File List'''

1. '''Files that were open in BESA Research are automatically added to the File List.''' Start BESA Research and open the files '''s1.cnt '''and '''s2.cnt '''in the directory ''Examples\ERP-Auditory-Intensity''.

2. Select ''Process / Batch Scripts''.... You should see the file names in the '''''File List Tab''''' something like this:

[[Image:Batch processing (5).gif]]

3. You can resort the files in the file list alphabetically by clicking onto the '''''File List column header''''':

[[Image:Batch processing (6).gif]]

Alternatively, you can mark any file, hold down the '''Ctrl '''key and press the '''Up''' or '''Down arrow '''to move the file name up or down the list. This is the sequence in which files will be processed in the batch.

[[Image:Batch processing (7).gif]]

4. Press '''Save File List''' and save the list you have created to '''ERP-Aud-Ex1.flist'''.

5. Highlight both names and press the''' Del '''button to remove them from the list.

6. '''Files can be dragged from Windows Explorer'''. Start Windows Explorer and navigate to the ''ERP-Auditory-Intensity'' subdirectory of your BESA Research examples folder (located in the ''Public Documents'' folder of your computer). Click on '''s1.cnt''' and drag it with the mouse onto the '''''File List Tab'''''. Let go of the mouse. BESA Research opens the file, and displays the name in the File List. Repeat for '''s2.cnt.'''

7. Highlight both names and press the '''Del '''button to remove them from the list.

8. '''Files can be added using the ''Add File'' button'''. Press '''Add File''' and navigate to the ''Examples\ERP-Auditory-Intensity'' subdirectory. Select '''s1.cnt'''. Press '''Ctrl''' and select '''s2.cnt'''. Both names should then be displayed in the ''File Open'' dialog. Press '''OK''' to add the files to the file list.

9. Highlight both names and press the '''Del''' button to remove them from the list.

10. '''Files can be loaded from a previously saved file list'''. Press '''Load File List '''and select '''ERP-Aud-Ex1.flist''', the list you saved in step 6 above.

'''B. Setting up the batch'''

1. We will add three commands, '''Paradigm''', '''Artifact Scan''', and '''Average''', to create a batch that will be applied to the two files in the file list.

2. Click on the '''Batch Tab'''.

[[Image:Batch processing (8).gif]]

3. Press the '''Add Command''' button to obtain the ''Select Command'' window:

[[Image:Batch processing (9).gif]]

4. Click on '''Paradigm''' and then on '''OK''' (alternatively, double-click on '''Paradigm'''). Hit '''Browse''', navigate to the ''Auditory'' folder, and select '''AEP_Intensity.pdg''', the paradigm for the auditory intensity experiment.

[[Image:Batch processing (10).gif]]

5. Press '''OK''' to obtain the ''Load Paradigm Task'' window.

[[Image:Batch processing (11).gif]]

6. Press '''OK''', and the first task in the batch is ready, and listed in the Batch Command window. If you want to modify the command, double-click on it to open the above window, that allows to browse for a different paradigm file.

[[Image:Batch processing (12).gif]]

7. Next, we add the '''Artifact Scan''' command. Click on the '''Add Command''' button, and select ''Artifact Scan.''

[[Image:Batch processing (13).gif]]

8. Press '''OK''' to open the ''Artifact Scan Task'' window. We want to be able to view the results of the scan, and adjust thresholds and bad channels if necessary. Therefore, check the ''Wait after scan'' checkbox.

[[Image:Batch processing (14).gif]]

9. Press '''OK''' to close the ''Artifact Scan Task'' window. Our batch now contains two commands.

[[Image:Batch processing (15).gif]]

10. Finally, we will add an '''Average''' command. Press the '''Add Command''' button and select ''Average''. Press '''OK''' to open the ''Average Task ''window.

[[Image:Batch processing (16).gif]]

11. With the default settings, the average would be saved to the same directory as the data. The file name mask is set by default so that in this example the two averages would be saved to '''s1-av.fsg '''and '''s2-av.fsg'''. We will save the averaged files to subdirectory ''"Averages''" of the data directory. Uncheck the ''Use default target'' check box, change the File name mask to '''%basename%_av-test''' in order not to overwrite the predefined files.

[[Image:Batch processing (17).gif]]

12. Press '''OK '''to close the ''Average Task'' window. Our batch is now complete.

[[Image:Batch processing (18).gif]]

13. We will now save the batch so that it can be used again. Press the '''Save Batch''' button, and save to the file '''ERP-Aud-ex1.bbat'''. Note that an easy way to generate new averaging batches is to load a previously save batch and edit the commands -- it may only be necessary to edit the '''Paradigm''' command to select the relevant paradigm file, and maybe to adjust the target directory in the '''Average''' command.

14. Press '''OK''' in the ''Batch'' Window to start the batch running. As requested, the batch pauses after the artifact scan:.

[[Image:Batch processing (19).gif]]

You may now adjust the number of rejected trials, e.g. by moving the vertical red bar to the left, or exclude bad channels.

15. Press '''OK''' to continue with averaging.

[[Image:Batch processing (20).gif]]

16. Note that, in the background, the ''Batch Running'' window is providing feedback about the current file and current task.

[[Image:Batch processing (6).jpg|400px]]

17. The batch will stop again after the next artifact scan. Press '''OK''' to allow the batch to run to the end.

[[Image:Batch processing (21).gif|400px]]

18. Press '''View Log''' to view the batch protocol. If you are using Internet Explorer or Netscape family (Mozilla, Firefox) browsers, and JavaScript is enabled, you will first see just batch titles defined by the date and time the batch was started. The most recent title is at the top of the list. For other browsers, or if JavaScript was not enabled, all protocol texts are expanded as in 19 (below).

[[Image:Batch processing (22).gif|200px]]

19. Click on the first title to expand its protocol. Here, for example, the protocol gives feedback about the number of epochs that were averaged for each file.

[[Image:Batch processing (23).gif]]

20. Finally, press '''OK''' to return to the main BESA Research display. Open the averages in the ''Averages'' subdirectory to confirm that they were generated properly.

=== Example: Merging files using the Export Command ===

Here we will demonstrate the use of the '''Export '''command to merge two files. We will combine the two averages from the previous example (Data averaging in the auditory intensity experiment) into one target file.

'''A. Generate the file list'''

# Start BESA Research and load the two data files '''S1_av-test.fsg''' and '''S2_av-test.fsg''' that were saved in the previous example.
# Select ''Process / Batch Scripts....''The two file names should be displayed in the file list.
# In the file list, make sure that '''s1_av-test.fsg '''is the first file in the list. If it is not, highlight the file, and move it up using '''Ctrl+up''', or right click and select ''Move Up'' in the context menu.

'''B. Generate the batch'''

1. Press the '''Add Command''' button, and select the '''Export''' command.

2. Press '''OK''' to open the ''Export Task'' window.

[[Image:Batch processing (24).gif]]

3. Press the '''Select Options'''... button to open the ''Export Dialog''.

[[Image:Batch processing (25).gif]]

4. Since we are combining averages, select ''Hires (no compression)'' in the '''Target data format''' drop-down list (If we were merging raw data files, it is better to select compression. Press '''OK '''to close the dialog. Check'' Append if file already exists'', so that the files will be merged. Enter '''s1+s2''' in the target file name mask edit box. This ensures that both files will be saved to the same target: '''S1+S2.fsg'''.

[[Image:Batch processing (26).gif]]

5. Press '''OK '''to close the ''Export Task'' window. The '''Export '''command is displayed.  

[[Image:Batch processing (27).gif]]

6. Optionally, you may save the batch file by pressing '''Save Batch'''.

7. Press '''OK''' to run the batch, and '''OK''' in the ''Batch Completed'' window to return to the BESA main window.

8. Finally, open the file '''S1+S2.fsg''' to confirm that it contains the two merged files.

'''C. Merge raw data'''

# Repeat the above task to merge the two raw data files '''S1.cnt''' and '''S2.cnt''' into a single target file '''S1+S2.foc'''. In this case, select one of the compression options as the target data format. Note that you would not normally want to merge two files from different subjects. However, several data blocks from the same subject can conveniently be merged using this method.

Note that ''<nowiki>*.fsg</nowiki>'' files can also be merged using the ''Combine Conditions'' dialog. 

== Combine Conditions, Channels ==

=== Combine Condition Scripts ===

With the Combine-Conditions module you can do a variety of operations on BESA averages (files with the extension '''<nowiki>*.fsg</nowiki>''', and other segment files, such as '''<nowiki>*.mul</nowiki>''', '''<nowiki>*.avr</nowiki>''', '''<nowiki>*.swf</nowiki>'''):

* Create grand averages
* Combine averages (add, subtract, weighted/unweighted)
* Merge files
* Exclude unwanted averages
* Rename conditions
* Rename or resort channels
* Generate averages or differences over selected channels
* Transform the data: standard interpolated 81 electrodes, change sampling rate, change interval
* Determine peaks, mean amplitudes, or integrals on data averages
* These operations can be performed on one or more files simultaneously. Results of an operation are stored in a single target file.

The module includes four tabbed windows:

* File List: Define a list of files on which the operations will be performed.
* Condition List: List the condition names, define target condition names, and how input conditions are combined into target conditions.
* Channel List: List the channel names, define target channel names, and how input channels are combined into target channels.
* Run Scripts: Define global options for the output (e.g. spatial interpolation, resampling, copy/merge or average, peak analysis). Start the operation.
* Note that in all four tabs, configurations can be saved for future use, and the '''Load Previous''' button restores the most recently used configuration.

=== Condition List Tab ===

List the condition names, define target condition names, and how input conditions are combined into target conditions.

The first column of the list box shows a list of all the condition names found in the source files.

Rows of the list box define the source conditions. Columns define the target conditions.

'''Initial setting'''

When first selecting the tab, each column shows each condition name found in the source files (as in the example below). In the list box, there is a "+1" along the diagonal. The result of this selection is that target conditions will have the same name as source conditions. Right click on source condition labels to view properties (e.g. no. of samples, time range, sampling rate).

[[Image:Batch processing (28).gif]]

'''Editing the condition list'''

* Target condition names can be edited, inserted or deleted by clicking on the label at the top of each column.
* Click on a box within the list to toggle between "+1", "-1" and blank. These correspond to the operations:
** "+1" = add
** "-1" = subtract
** blank = do nothing
* Right click on a box for further operations: conditions can be weighted by a given factor other than 1.

'''Divide result by sum of PLUS factors'''

* Normally, when creating an average over conditions, the sum is divided by the number of conditions, or a weighted average is generated (see below).  If "''Divide result by sum of PLUS factors''" is unchecked, the conditions will be summed rather than averaged.
* Note that, when making differences between conditions, no such division is required. BESA Research will uncheck the checkbox automatically if subtraction ("-1") is specified somewhere in the condition list.

'''Weighting of averages'''

* Below the list, click on the ''Weighted Average'' row to toggle "YES" and "NO". "YES" means that averages will be weighted by the number of epochs contributing to the average. For instance, if average A contained 100 epochs and average B contained 200 epochs, the weighted average will be computed as

<div style="margin-left:1cm;margin-right:0cm;">(100 * A +  200 * B) / (100 + 200)</div>

<div style="margin-left:1cm;margin-right:0cm;">Select "NO" for an unweighted average. For the above example, the average is computed as</div>

<div style="margin-left:1cm;margin-right:0cm;">(A + B) / 2</div>

<div style="margin-left:1cm;margin-right:0cm;">Weighted averages are not permitted if one of the boxes contains a negative value.</div>

* Values other than +1 or -1 in the boxes apply a different kind of weighting. For instance, we want to compute the difference between the means of conditions A, B, C and D, E. Use a right click to specify the fraction 1/3 for each of A, B, and C, and -1/2 for each of D and E (see example below).

[[Image:Batch processing (29).gif]]

'''Save the current condition list'''

* Press the '''Save Condition List''' button.

'''Load a condition list'''

* Press the '''Load Condition List''' button.

'''Load previous settings'''

* Press the '''Load Previous''' button

'''Feedback'''

* Conditions that have different numbers of electrodes (averaging across different files) can only be combined if channels are interpolated to a standard set of electrodes.
* Conditions that have different durations or sampling rates can only be combined if the sampling rate and durations are made the same.
* Feedback about the above situations is displayed by the presence of tick marks above the list box.

=== Channel List Tab ===

List the channel names, define target channel names, and how input channels are combined into target channels.

Note that this tab is very similar in usage to the '''Condition List Tab'''. Note also that some of the functions performed in this tab could also be done in the Montage Editor. It may be a matter of convenience whether you choose to perform these operations here or in the Montage Editor.

The first column of the list box shows a list of all the channel names found in the source files.

Rows of the list box define the ''source'' channel. Columns define the'' target'' channel.

'''Initial setting'''

When first selecting the tab, each column shows each channel name found in the source files (as in the example below). In the list box, there is a "+1" along the diagonal. The result of this selection is that target channel will have the same name as source channel.

'''Combining files'''

If files with different channel configurations are included in the File List, the rows and columns of the Channel List Tab will only contain the labels for the channels that are in common among the files.

If the files in the File List have a different sequence of channels, the sequence of the first file in the list will be adopted in the Channel List.

Thus, for the initial setting, unless the "''Ignore Settings in this Tab''" checkbox is checked, the target grand average or peak/amplitude analysis, etc. will be applied using only channels that are in common among the input files, and using the channel sequence of the first file in the File List. By changing the target channels or by changing the entries in the Channel List, new channels consisting of averages or differences can be generated.

'''What can the Channel List be used for?'''

Some examples:

* Reorder or relabel channels
* Create channel differences
* Create averages over channel groups, e.g. for peak analysis
* Extract a selection of channels for peak analysis or mean amplitudes
* Create grand averages across files with different channel configurations, just using channels in common among the files

[[Image:Batch processing (30).gif]]

'''Editing the channel list'''

* Target channel names can be edited, inserted or deleted by clicking on the label at the top of each column.
* Click on a box within the list to toggle between "+1", "-1" and blank. These correspond to the operations:
** "+1" = add
** "-1" = subtract
** blank = do nothing
* Right click on a box for further operations: channels can be weighted by a given factor other than 1.

'''Divide result by sum of PLUS factors'''

* Normally, when creating an average over channels, the sum is divided by the number of channels, or a weighted average is generated (see below).  If "Divide result by sum of PLUS factors" is unchecked, the channels will be summed rather than averaged.
* Note that, when making differences between channels, no such division is required. BESA Research will uncheck the checkbox automatically if subtraction ("-1") is specified somewhere in the channel list.

'''Save the current channel list'''

* Press the '''Save Channel List''' button.

'''Load a channel list'''

* Press the '''Load Channel List '''button.

'''Load previous settings'''

* Press the '''Load Previous''' button

=== Run Scripts Tab ===

Define global options for the output (e.g. spatial interpolation, resampling, copy/merge or average, peak detection. Start the operation.

[[Image:Batch processing (7).jpg]]

'''Load or Save Settings'''

* You can save the current settings of this tab to a file (*.run) which can be loaded later.
* When you run the script, the current settings are saved automatically to a file "'''PreviousSettings.run'''".

'''Load Previous'''

* Press this button to load the previous settings (from "'''PreviousSettings.run'''").

'''Averages to Generate'''

* '''Generate separate averages for each source file'''. Averages are performed over conditions within the source file, and are then appended to the target file.
* '''Combine data from source files'''. Conditions are combined over all source files into a single target average.
* '''No averages, just copy'''. Files are copied and merged to the target file. Use this option for renaming conditions, merging files, removing unwanted averages (see below), changing the sampling rate and interval.
* '''Peaks and mean amplitudes'''. Specify time ranges for peaks, mean amplitudes, or integrals (areas).
* Note: When generating or copying averages (first three options), filters and baseline settings are turned off. For Peaks and mean amplitudes, filters and baseline settings are specified in the dialog.

'''Spatial Interpolation'''

* '''Interpolate to Standard 81 electrodes'''. The target file will contain only electrodes (other channels are omitted), using the Standard 81 configuration (as in other export functions within BESA Research). This cannot be selected if the source data contain less than 16 EEG channels.
* '''Interpolate Bad Channels'''. Bad electrode channels in the source file will be interpolated. If the above option is deselected and bad channels exist in one or more of the source files, this option is always on.

BESA Research can interpolate EEG, and MEG if the sensors are axial gradiometers or magnetometers. If other channels are marked as bad in one or more of the source files, these will be defined as bad in the target file. This applies to MEG planar gradiometers, to polygraphic data, and to ICR channels.

'''Temporal Interpolation'''

* '''Spline to New Sampling Rate and Interval'''. Data can be converted to a new sampling rate, and the interval can be changed.
** If the sampling rate is reduced, the data will be low-pass filtered at 1/3 sampling frequency before reduction.
** If the sampling interval is changed, the prestimulus and poststimulus intervals are limited by the smallest intervals in the conditions contributing to the averages. These limits are shown below the edit boxes.

'''Peaks and Mean Amplitudes'''

[[Image:Batch processing (31).gif]]

'''Peaks:'''

* Select the time range between which peaks are to be determined.
* Select the montage on which the peaks are to be determined.
* Define the filter settings.
* Define the baseline settings.
* Specify whether peaks are to be defined at one latency: if so, select the channel on which peaks are to be detected.
* Specify whether you want to find positive or negative peaks.

'''Mean amplitudes and areas:'''

* Select the time range over which the mean amplitudes or areas are to be determined.
* Select the montage on which the mean amplitudes or areas are to be determined.
* Define the filter settings.
* Note that when computing areas, data are first rectified (made positive) and then summed over the time range.

'''Output options of the analysis:'''

* A single ASCII file that contains the result of the analysis for all data sets, conditions, and channels including header and information lines.
* A sparse output suitable for import in SPSS. Each variable (e.g. a latency, a channel amplitude) constitutes one column of the output file.
* Direct transfer to MATLAB into a struct besa_peak. For more information on the data transfer from BESA Research to MATLAB, please refer to help chapter ''“The MATLAB interface”.''

'''Starting the Operation'''

* Press '''OK''' to start the operation. After the operation is completed, and the "Open target file in BESA" box is checked, BESA Research will open the target file.  "Open target file in BESA" cannot be checked if "Peaks and mean amplitudes" was selected - then the result of the operation will be an ASCII file or a MATLAB transfer.
* You will be asked for the name of the target file (unless a MATLAB transfer of peak data has been performed).

'''Restrictions'''

* Depending on source file configurations, not all options above are selectable. For instance, if two files contain different numbers of electrodes, and the "''Ignore Settings in this Tab''" checkbox is checked in the '''''Channel List''''' Tab, spatial interpolation to Standard 81 is enforced in the target. Similarly, if different sampling rates are used in different files, temporal interpolation is enforced.
* You are not allowed to add files to the file list if the channel configuration is different, and the data cannot be combined with Standard 81 interpolation. Since Standard 81 interpolation is only possible for EEG, multiple files without EEG can only be loaded if they have the same number of channels.

=== How to Create Grand Averages ===

* Open the files you want to average in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. To average across different conditions, click in the list boxes to obtain "+1" for each source condition to combine, and rename the target condition to define a meaningful name for the average.
* Click on the '''Run Scripts Tab'''.
* If you have more than one file, specify whether averages should be generated across files ('''Combine data from source files''') or within files ('''Generate separate averages for each source file''').
* Select other options if required (spatial or temporal resampling).
* Press '''OK'''.

=== How to Generate Differences Between Conditions ===

* Open the files you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. To create differences, click in the list boxes to obtain "+1" for one of the source conditions, and "-1" for the source condition to subtract, and rename the target condition to define a meaningful name for the difference.
* Click on the '''Run Scripts Tab'''.
* If you have more than one file, specify whether averages should be generated across files ('''Combine data from source files''') or within files ('''Generate separate averages for each source file''').
* Select other options if required (spatial or temporal resampling).
* Press '''OK'''. An average of the differences is generated. If only one example of each condition exists, e.g. in a grand average file, the result is the difference between conditions.

=== How to Merge Files ===

* Open the files you want to merge in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions''...).
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press '''OK'''.

'''Notes'''

* If the source files have different electrode configurations, use the Standard 81 configuration for the target.
* If the source files have different sampling rates or intervals, use Temporal Interpolation.

=== How to Remove Unwanted Averages ===

'''Removing one or more unwanted segments'''

* Normally, all conditions are read from a source file. To exclude one or more segments from operations in the Combine Conditions module, mark the segments as artifacts in the main program display. It is sufficient for the beginning or the end of an artifact interval to be within the segment for the segment to be excluded.
* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press''' OK'''.
* The target file contains the copied data without the conditions that were marked as averages.

'''Removing one or more unwanted conditions (by label)'''

* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...).''
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Deselect the target conditions you want to omit (replace the "+1" by a blank).
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Press''' OK'''.
* The target file contains the copied data without the conditions that were marked as artifacts.

=== How to Rename Conditions ===

* Open the file you want to operate on in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions''...).
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions. Click on column headings to rename the target conditions.
* Click on the''' Run Scripts Tab'''. Select "''No averages, just copy''".
* Press '''OK'''.
* The target file contains the copied data with the renamed conditions.

=== How to Change the Sampling Rate ===

* Open the file(s) you want to change in BESA Research.
* Start the Combine Conditions Module (''ERP / Combine Conditions...'').
* Click on the '''Condition List Tab'''. By default, the target conditions receive the same name as the source conditions.
* Click on the '''Run Scripts Tab'''. Select "''No averages, just copy''".
* Select "''Spline to New Sampling Rate and Interval''" and type the new sampling rate into the edit box.
* Press '''OK'''.

=== Example: Create grand average and combinations of conditions ===

In this example, we will generate a grand average of the results of the Auditory Intensity Experiment. The experiment includes averages from five different stimulus intensities. We will create a grand average over each intensity, but also include means over the two lowest and the two highest intensities, and the difference between these two combinations.

'''A. File selection'''

# Start BESA Research and open files '''S1_av.fsg - S10_av.fsg''' in the ''Examples\ERP-Auditory-Intensity'' folder. The files contain the individual averaged data of the 10 subjects who participated in this study.
# Select ''ERP / Combine Conditions...'' The file list should display the two files, with feedback about the number of averages and conditions. 8 epochs are found. See the ''“Data averaging in the auditory intensity'' ''experiment”'' example for examples how to manipulate the file list.

[[Image:Batch processing (32).gif]]

'''B. Define conditions'''

1. Click on the '''Condition List Tab'''. The initial window defines target conditions with the same name as the source conditions. To generate the grand average over these conditions we could proceed without further changes to the '''Run Scripts Tab'''. However, we want to modify the condition list and create a condition that contains the grand averaged difference between the''' High''' and '''Low''' conditions.

[[Image:Batch processing (8).jpg]]

2. Click on the '''All '''column label. In the resulting window, rename condition '''All''' to''' Difference'''. Then press '''OK'''.

[[Image:Batch processing (33).gif]]

3. The last column is now labeled '''Difference.''' Left-click twice onto the ‘'''+1’''' entry that links this condition to the '''All '''input condition. This will remove the link and leave the field blank. To define the ‘Difference’ condition as the average of ‘High’ minus ‘Low’ over subjects, left-click once into the field linking input '''High''' with target '''Difference''' to generate an entry ‘'''+1’''' in this field. Left-click twice into the field linking input '''Low '''with target '''Difference''' to generate an entry '-'''1'''’.

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;"></div>

<div style="margin-left:1.27cm;margin-right:0cm;">[[Image:Batch processing (35).gif]]</div>

4. Press '''Save Condition List''' and save the list to '''ERP-aud-ex1.clist'''. This condition combination can thus be loaded later using the '''Load Condition List''' button.

'''C. Run the script'''

# Click on the '''Run Script Tab'''.
# The default tab settings are ready for generating the grand average ('''Combine data from source file''' and '''Open target file in BESA''' should be checked). Just press '''OK'''. Enter '''All_Subjects_cc-test.fsg''' as file name and press''' Save'''.

The resulting file contains the 8 target conditions, 60db, 70dB, 80dB, 90dB, 100dB, Low, High, and Difference.

=== Example: Average files from different experiments ===

This example is intended to illustrate several features of the ''Combine Conditions'' Dialog, such as electrode interpolation and resampling. We will combine an average from the Auditory Intensity experiment with one from the P300 auditory experiment. In this particular case, it is not a very meaningful thing to do, but it shows what is possible. For instance, the same experiment may have been performed using different sampling rates or electrode combinations. This example shows how such data may be combined.

'''A. File selection'''

# Start BESA Research and open the file '''All_Subjects_GA.fsg''' in the ''Examples\ERP-Auditory-Intensity'' folder. The file contains the grand average data from the auditory intensity experiment.
# Open the file '''RareFrequentResponseLeft.fsg''' in the ''Examples\ERP-P300-Auditory'' folder. This file contains averages from the P300 auditory experiment.
# Select ''ERP / Combine Conditions... ''Note that the files have different sampling rates and different numbers of electrodes.

[[Image:Batch processing (36).gif]]

'''B. Define conditions'''

1. Click on the '''Condition List Tab'''. Note that the feedback text at the bottom of the window displays the text "Standard 81 interpolation required to generate average; Across files: resampling or change in time range required to generate average". The condition labels show all the names from both files.

[[Image:Batch processing (37).gif]]

2. We will exclude most conditions, and just combine the most similar conditions from the two experiments: the "Standard" and the "80dB" conditions. Click on the title of the first column,''' Blink'''. Select “''Delete all conditions to the right of this column”'', and press '''OK'''.

[[Image:Batch processing (38).gif]]

3. Click on the title again, and rename the target condition to "Standard".

[[Image:Batch processing (39).gif]]

4. Click twice in the first line to remove the "+1" entry there. Click once in the third row ("Frequent"), and in the 7th row ("80dB"), to display "+1" at each entry. Thus, just two of the conditions will be combined into one target condition.

[[Image:Batch processing (40).gif]]

'''C. Run the script'''

1. Click on the '''Run Script Tab'''.

[[Image:Batch processing (41).gif]]

2. Note that '''Interpolate to Standard 81 electrodes''' is checked and grayed: since two different electrode sets are to be combined, we can only do this by interpolating electrodes. Also, both '''Spline to new sampling rate''' and '''Clip interval '''are checked and grayed. Again, these settings are required in order to be able to average the two data files together. The sampling rate is set to the higher of the two selections. The time range is set to the largest possible range that can be clipped from the two data sets. For now, leave these settings as they are, and press '''OK'''. Save the target to '''TestCombineExpts_CC-std81.fsg'''.

{{BESAManualNav}}

File:SA-Introduction (5).gif

2021-05-04T12:30:10Z

Abinash: Abinash uploaded a new version of "File:SA-Introduction (5).gif"

File:SA-Introduction (3).gif

2021-05-04T12:29:03Z

Abinash: Abinash uploaded a new version of "File:SA-Introduction (3).gif"

File:SA-Introduction (2).gif

2021-05-04T12:27:29Z

Abinash: Abinash uploaded a new version of "File:SA-Introduction (2).gif"

File:Source Analysis1.jpg

2021-05-04T12:25:21Z

Abinash: Abinash uploaded a new version of "File:Source Analysis1.jpg"

File:Source Analysis1.jpg

2021-05-04T12:24:16Z

Abinash: Abinash uploaded a new version of "File:Source Analysis1.jpg"

Source Analysis Introduction

2021-05-04T12:06:24Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Standard or higher
|version = 6.1 or higher
}}

== Introduction ==

The Source Analysis module provides a highly interactive environment for analyzing the sources of electric or magnetic brain activity.

The following chapters will guide you through the most important features of the Source Analysis module in chronological order of data processing. For a thorough introduction to source analysis, we also recommend that you work through the [[https://www.besa.de/downloads/training-material/tutorials/ tutorials]] that are available for download on [[https://www.besa.de/ our website]].

The ''Reference'' chapter in our online help offers a detailed description of the available features. It is subdivided into the following sections: ''Menu Bar, Popup Menus, Special Controls, Dialog Boxes.''

== Starting the Source Analysis Module ==

Once you have opened a file for source analysis, you can decide which part of the averaged data will be analyzed. The BESA format for file segments (fsg-format) separates different averaged conditions by segment boundaries, as in the example file shown below.

[[Image:Source_Analysis1.jpg]]

To mark the entire condition on the left, simply click the right mouse button somewhere in the condition and select the popup menu entry '''Whole Segment'''.

To mark a part of the condition, create a block somewhere within the left condition by dragging with the left mouse button. Then press the right mouse button to obtain a popup menu containing the following entries:

[[Image:SA-Introduction (2).gif |top]]

Choosing ''Source Analysis'' opens the following dialog box:

[[Image:SA-Introduction (3).gif |top]]

* The left-hand '''Block Size and Position''' section controls the time interval which is sent to the Source Analysis module. The predefined setting is to make a custom definition of the block size. You can change the settings to mark the whole segment. If you choose ''Custom Definition'', the bottom part of the section becomes active, and you can enter the exact time range you wish to analyze. If you choose ''All Conditions'', all conditions in the current data set are sent to the Source Analysis module.
* In the '''Filter Settings''' section, high frequency cutoff filters or low frequency cutoff filters can be quickly switched on and off using the'' Enabled'' tick mark.
* The '''Source Analysis''' button applies the settings and immediately starts the Source Analysis module.
* You can apply the settings to the data block using the '''Set Block''' button.
* The''' Cancel''' button closes the dialog box without modifications.
* If the option ''All Conditions'' is selected while the '''Source Analysis''' button is pressed, all conditions of the current data file (instead of only the selected c condition) are sent into the Source Analysis window simultaneously using the specified parameters.

'''Tip:'''

If you want to analyze a second data block with the same settings as before, mark an arbitrary block within the other data segment and click the right mouse button. The settings that you chose previously are displayed in the popup menu:

[[Image:SA-Introduction (5).gif |top]]

Selecting the entry at the bottom automatically reproduces the settings and starts the Source Analysis module with the specified data block.

{{BESAManualNav}}

MATLAB Interface

2021-05-04T10:42:22Z

Abinash: /* How the interface works */

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = 6.1 or higher
}}

= MATLAB Interface =

== 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 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 [https://www.besa.de/downloads/training-material/tutorials 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 “''Installation” ''chapter! 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!

'''1'''. '''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\)''.

'''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 MATLAB 2009b:
** 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 Windows key and pressing the Pause key at the same time.
** In Window 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]]

* Select the "Advanced" tab in the "''System Properties''" dialog.

[[Image:Matlab (2) .gif]]

* Press the "'''Environment Variables...'''" button.

[[Image:Matlab (3) .gif]]

* Under "System variables" click on the "Path" variable and press "'''Edit...'''".
* 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.

[[Image:Matlab (4) .gif]]

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

'''3. Additional configuration''' (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 root folder (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 drop-down list, select the Matlab version that you are using.

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

This program does two operations:

1. it copies the appropriate interface Dll to the BESA Research root folder and renames it to "'''BesaMatlab.dll'''" (32-bit version) or "'''BesaMatlab64.dll'''" (64-bit version), and

2. if you are using a 64-bit version it creates an entry in '''BESA.ini''' (C:\Users\Public\Documents\BESA\Research_7_1) as follows:
[Matlab]

Platform=64

'''4. 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:

* 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.
* Run '''CMD (Command Prompt) as administrator''', and then execute the following command (registers MATLAB as a Component Object Model (COM) server).:
** <code>matlab -regserver</code>
** 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.
* Run '''CMD (Command Prompt) as NOT administrator''', and then execute the following command (Manually create automation server: start MATLAB as a Component Object Model (COM) Automation server. MATLAB does not display the splash screen).:
**<code>matlab -automation</code>
** Close the CMD and MATLAB Command Window (there should be no error message).

'''5. 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 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:Matlab1.png]]

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

[[Image: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 "'''<code>besa_channels</code>'''" variable, which contains the data for the marked data segment.

[[Image: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 (step 2 above) 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 "'''<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'''

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'' 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 7 typically ''C:\Users\Public\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.

[[Category:Research Manual]]

{{BESAManualNav}}

MATLAB Interface

2021-05-04T10:41:47Z

Abinash: /* Configuration */

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = 6.1 or higher
}}

= MATLAB Interface =

== 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 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 [https://www.besa.de/downloads/training-material/tutorials 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 “''Installation” ''chapter! 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!

'''1'''. '''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\)''.

'''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 MATLAB 2009b:
** 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 Windows key and pressing the Pause key at the same time.
** In Window 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]]

* Select the "Advanced" tab in the "''System Properties''" dialog.

[[Image:Matlab (2) .gif]]

* Press the "'''Environment Variables...'''" button.

[[Image:Matlab (3) .gif]]

* Under "System variables" click on the "Path" variable and press "'''Edit...'''".
* 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.

[[Image:Matlab (4) .gif]]

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

'''3. Additional configuration''' (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 root folder (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 drop-down list, select the Matlab version that you are using.

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

This program does two operations:

1. it copies the appropriate interface Dll to the BESA Research root folder and renames it to "'''BesaMatlab.dll'''" (32-bit version) or "'''BesaMatlab64.dll'''" (64-bit version), and

2. if you are using a 64-bit version it creates an entry in '''BESA.ini''' (C:\Users\Public\Documents\BESA\Research_7_1) as follows:
[Matlab]

Platform=64

'''4. 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:

* 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.
* Run '''CMD (Command Prompt) as administrator''', and then execute the following command (registers MATLAB as a Component Object Model (COM) server).:
** <code>matlab -regserver</code>
** 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.
* Run '''CMD (Command Prompt) as NOT administrator''', and then execute the following command (Manually create automation server: start MATLAB as a Component Object Model (COM) Automation server. MATLAB does not display the splash screen).:
**<code>matlab -automation</code>
** Close the CMD and MATLAB Command Window (there should be no error message).

'''5. 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 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:Matlab1.png]]

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

[[Image: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 "'''<code>besa_channels</code>'''" variable, which contains the data for the marked data segment.

[[Image: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 (step 2 above) 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 "'''<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'''

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'' 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 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.

[[Category:Research Manual]]

{{BESAManualNav}}

MATLAB Interface

2021-05-04T10:10:44Z

Abinash: /* Introduction */

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = 6.1 or higher
}}

= MATLAB Interface =

== 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 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 [https://www.besa.de/downloads/training-material/tutorials 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 “''Installation” ''chapter! 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!

'''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 '''Windows''' key and pressing the '''Pause '''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".

[[Image:Matlab (1) .gif]]

* Select the "Advanced" tab.

[[Image:Matlab (2) .gif]]

* Press the "'''Environment Variables'''" button.

[[Image:Matlab (3) .gif]]

* Under "System variables" click on the "Path" variable and press "'''Edit'''". In the resulting dialog, enter a semicolon (;) at the end of the path string, and add the path after the semicolon.

[[Image:Matlab (4) .gif]]

* Press "'''OK'''" to close and save the path variable. Press "'''OK'''" to close the "System Properties" Dialog.

'''3. Additional configuration''' (only required after a change of your MATLAB configuration after installation of BESA Research):

During the installation process of BESA Research, the program "''SetupBesaMatlabInterface.exe''" 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.

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

This program does two operations:

1. it copies the appropriate interface Dll to the BESA Research root folder and renames it to "'''BesaMatlab.dll'''" (32-bit version) or "'''BesaMatlab64.dll'''" (64-bit version), and

2. if you are using a 64-bit version it creates an entry in '''BESA.ini''' as follows:

[Matlab]

Platform=64

'''4. 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 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:Matlab1.png]]

The Matlab window should open, and BESA Research will display a progress bar:

[[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.

Examine the "'''<code>besa_channels</code>'''" variable, which contains the data for the marked data segment.

[[Image: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 (step 2 above) 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 "'''<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'''

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'' 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 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.

[[Category:Research Manual]]

{{BESAManualNav}}

Test Page

2021-05-04T09:27:36Z

Abinash: /* This is a test page */

[[Category:TestPage]]
==This is a test page==
This is a reference for The Origins of EEG <ref>[http://www.bri.ucla.edu/nha/ishn/ab24-2002.htm Millet, David (2002). "The Origins of EEG".]'' International Society for the History of the Neurosciences'' (ISHN).</ref>

<math>\zeta(s) = \sum_{n=1}^\infty \frac{1}{n^s} = \frac{1}{1^s} + \frac{1}{2^s} + \frac{1}{3^s} + \cdots.</math>

<math>
f(n) =
\begin{cases}
n/2, & \text{if }n\text{ is even} \\
3n+1, & \text{if }n\text{ is odd}
\end{cases}
</math>

{{font color|red| <pre> 0 0 0 0 0 0 0 0 0 0 0 0 0 </pre>}}

{{font color|#FF1493|2.52 6.71 10.07 5.04 8.39 5.04 10.07 4.20 6.71 11.75 5.04 12.59 5.04 9.23 5.04 10.07 4.20 10.07 8.39 7.55 8.39 5.87 11.75 3.36 5.04 1.68}}
{{font color|#FF1493|7.55 2.52 10.91 5.04 6.71 5.04 2.52 5.04 12.59 11.75 14.27 5.87 6.71 6.71 7.55 2.52 13.43 15.11 5.87 8.39 3.36 7.55 8.39 13.43 2.52 8.39}}

<iframe key="test" path="" />

Hover over me.

== References ==
<references />

{{BESANav}}

[[Category:TestPage]]

File:AudIntensity-average.bbat

2021-02-09T09:49:29Z

Abinash:

Using BESA to correct blink and EKG artifacts in MEG data

2021-02-02T13:26:01Z

Abinash: /* Artifact options: which correction model? */

{{BESAInfobox
|title = Module information
|module = BESA Research Standard or higher
|version = 6.1 or higher
}}

Eyeblinks and EKG cause large artifact signals in the magnetometer channels. The artifact correction facilities of BESA can correct these artifacts quite well. The procedure is quite simple for blinks but more complex for EKG. The following text outlines the procedures and current limitations of BESA for artifact correction.

The principles of the artifact correction procedure are described in Berg and Scherg (1994).

In summary, the following steps are required:

* Use pattern search and average to identify the latencies of blink/EKG signals in the raw data. Pattern search works best if you have recorded a vertical EOG and EKG with the MEG data, but it will also work on selected MEG channels, using the appropriate filters.
* A spatial PCA is performed on the average to identify the main topographies/components of the artifact signal. For blinks, only one topography is required. For EKG, two or three topographies may be required.
* The topographies/components are combined into a coefficient file (''*.atf''). Using the '''Artifact''' Menu, the ''atf'' file can be loaded and correction switched on. Contrary to the warning message displayed by the ERP module, averaging can be performed using artifact corrected data.
* When the average is loaded into the Source Analysis module, the artifact coefficients (saved in the average file) need to be activated. They will then be incorporated into source modelling using subspace projection (SSP – see also Uusitalo et al. (1997)). In this case, SSP is equivalent to the “optimized correction method” described in Berg and Scherg (1994).

'''References'''
* Berg, P., and Scherg, M. A multiple source approach to the correction of eye artifacts, Electroenceph. clin. Neurophysiol., 1994, 90: 229-241.
* Uusitalo, M.A., Ilmoniemi, R.J. Signal-space projection method for separating MEG or EEG into components. Med. Biol. Eng. Comput., 1997, 35: 135-140.

== Pattern search for blinks and EKG ==

=== Eyeblinks ===

# Select filters 0.5 – 8 Hz ('''Filters/Edit Filter Settings…'''). Make sure the low cutoff filter type is '''Forward'''! (This is to ensure that no contribution from the blink topography bleeds back into the baseline time interval).
# View Polygraphic signals only (press the '''Pgr''' button at the top right of the BESA window), so that the vertical EOG channel is displayed
# Define the search block from –100 ms to +400 ms ('''Edit/Default Block Epoch…''')
# Select Pattern Search ('''Search/Pattern''')
# Select Search Query ('''Search/Query''')
# Select Buffer 1 for averaging ('''Tags/Pattern 1''')
# Identify a clear blink signal on the vertical EOG channel. Right-click at the '''onset''' of the blink, and select '''Default Block''' in the dropdown menu. The marked block should look something like this: [[File:EKG_artifacts_in_MEG_data__(1).png|75x55px]]
# Click once on the VEOG channel label, so that a rightward arrow is displayed (ignore the correlation window that opens on the right): [[File:EKG_artifacts_in_MEG_data__(2).png|100x55px]]
# Press the '''SAW''' button (Search/Average/Write). BESA will start scanning through the file, and it will stop at each occurrence of a blink. Press “Yes” to accept. “No” to reject, or “Stop asking” to let BESA accept everything automatically. Save the result to a file name of your choice (e.g. ''name_artifact.fsg''), labelling the segment, e.g. “blink”.

=== EKG ===

# In contrast to blink averaging we use two steps: first, filters are set to enhance the EKG for pattern search. Second, the filters are opened up, and the average is repeated.
# Select filters 5-20 Hz. This should generate a fairly clear signal on the EKG.
# Set the default block epoch so that the R-wave and the T-wave are well inside the epoch. The setting used for blinks may be OK, but you may need to extend the post-cursor interval, e.g. from 400 to 500 ms.
# Proceed as with blinks, but selecting Buffer 2 for averaging ('''Tags/Pattern 2'''). Mark a block around the onset of an R-wave. The marked block should look something like this: [[File:EKG_artifacts_in_MEG_data__(3).png|100x56px]]
# Save the average in the same file as the averaged blinks, labelling the segment, e.g. “EKG”.
# Select filters 1-30 Hz. Select '''Search/Tagged Events''', and press '''SAW'''. This repeats the average using the tags that were identified during the first step. Opening up the filters ensures that the average includes more of the EKG signal.

=== What to do if there is no VEOG or EKG channel ===

The procedure is similar to the above, but you need to identify a MEG channel that displays the blink or EKG waveform clearly. You may need to experiment with filter settings to make the artifact pattern clearer (the filter settings described above are not fixed rules – you may find that other settings work better for pattern search). You may find the “Create Triggers from EMG/EEG” tool helpful for detecting EKG ('''ERP/Create Triggers from EMG/EEG…'''). See the BESA help file (tutorial on creating triggers).

== Spatial PCA and the *.atf file ==

Open the file in which you saved the averages (e.g. ''name_artifact.fsg''). Make sure that prestimulus baseline correction is switched on ('''Filters/Use Prestimulus Baseline''').

=== Blinks ===

# Mark the whole blink epoch: Right-click onto the epoch, and select '''Whole Segment'''.
# Select '''Artifact/Assign/Blink'''. The spatial PCA is computed, and the first spatial component is assigned to describe the blink. You may check if the correction works by selecting '''Artifact/Correct'''.
# The coefficients are saved automatically to a file with the same basename as the average, and the extension ''“.atf''”.

=== EKG ===

EKG coefficients are corrected analogously to blinks. A difference is that the topographic distribution of the EKG over the MEG sensors is more complex than that of blinks. It changes over time. The reasons for this are unclear, and may be due to movement of the heart (and its equivalent dipoles) over time, but also to ballistic effects: movement of the head due to blood flow.

Since topographic distribution changes over time, more than one component is required for correction. We choose the number of components in the Artifact Select Dialog Box empirically: As a rule of thumb, if a component explains more than 5-10% of the variance of the averaged EKG signal, the component is included. Note that the number of components you select can also be changed when the coefficients are applied to the raw data.

== Correcting the raw data ==

* Switch back to the raw data file, and load the ''*.atf'' file you have created ('''Artifact/Load…''').
* Optionally, check that the artifact correction channels are visible (Artifact/View)
* Switch on artifact correction (Artifact/Correct).
* The figure on the next page shows the result of correction of channels A75-A148 on a three-second interval containing both EKG and eye activity. The blue label “1” marks the onset of a blink found during pattern search. The red “2” shows the onset of R-waves found during pattern search.
* Note that correction is quite good, but it is not perfect. In particular, there is some residual eye activity, e.g. around channels A91, A113, A131.

{|
! '''uncorrected'''
! '''corrected'''
|-
| [[File:EKG_artifacts_in_MEG_data__(4).png|57x57px]][[File:EKG_artifacts_in_MEG_data__(5).png|272x802px]]
| [[File:EKG_artifacts_in_MEG_data__(6).png|273x801px]]
|}

== Averaging the raw data ==

You can leave correction on during data averaging. When you press the Average button, a warning dialog will appear:

[[File:EKG_artifacts_in_MEG_data__(7).png|539x124px]]

You may select either option. Because of the recent installation of subspace projection (SSP) in the Source Module, the “distorted topographies” in the warning are no longer an issue for source analysis, provided SSP is switched on when the data are sent to the Source Module. The decision has consequences a) if you intend to analyze data waveform amplitudes and/or latencies, and b) if you intend to export the averages for analysis with other software.

==== Option “Yes” – turn off artifact correction ====

The averaged data will include EKG and eye artifacts, but these artifacts will not cause epochs to be rejected. The same number of epochs will be included in the average whether or not “Yes” or “No” is chosen.

You may load the correction coefficients (''*.atf'') for the average, and switch on artifact correction.

==== Option “No” – leave artifact correction on ====

The averaged data will be corrected. Each epoch is corrected before being included in the average.

==== Artifact options: which correction model? ====

The result of the correction on the raw data or the averaged data can be slightly different. The effects of correction will also vary, depending on the settings in '''Artifact/Options'''. These differences can be considered as consequences of variations in the “surrogate” or “adaptive” model of brain activity concurrent with the artifact activity (cf. Berg & Scherg 1994). These differences lead to changes in the estimate of the amounts of artifact activity to be removed by correction. If you intend to use the data waveforms outside BESA, and if you don’t use SSP with the artifact coefficients, then the settings in '''Artifact/Options''' become important. In current versions of BESA, these settings are based on EEG amplitude levels. We generally use the values shown on the right. Note that these values are '''irrelevant''' if we use SSP in Source Analysis.

[[File:EKG_artifacts_in_MEG_data__(8).png|353x231px]]

== Sending the data to Source Analysis ==

When the average is generated, the correction coefficients are saved in the ''*.fsg'' file. Before you send the data to the Source Module, these coefficients must be '''activated'''.

* If you averaged the corrected data, coefficients are already activated. This should be apparent from the red “corrected” displayed above the channel labels.
* If you averaged the uncorrected data, load the saved ''*.atf'' file ('''Artifact/Load…'''), and switch on correction ('''Artifact/Correct''').

Then mark a time range and send the data to Source Analysis. At the right of the status bar, the text '''ART''' indicates that the artifact components are used in SSP.

[[File:EKG_artifacts_in_MEG_data__(9).png|143x158px]]

'''Alternatively, if you averaged the uncorrected data, load the average to Source Analysis, and then load the artifact coefficients as part of the dipole model (load or append solution, and use the dropdown list in the File Open box to select ''*.atf'' instead of ''*.bsa''). This approach has the advantage that the source waveforms of the spatial components show the contribution of eye and EKG activity to the model.'''

This implicit application of SSP during Source Analysis is mathematically equivalent to the “optimizing” correction method (cf. Berg & Scherg 1994): the topographies of the artifacts are implicitly incorporated into any dipole model.

== Limitations of the correction method in BESA ==

=== Bad channels ===

The ''*.atf'' file contains a two-line header with a) the number of channels, and b) the channel labels. If these do not match with the current data file, artifact correction is not possible. Bad channels are marked (with an asterisk next to the label), and the corresponding coefficient is set to zero. The irritating, but logical, the consequence is that if a channel was excluded (defined as “bad”) when the coefficients were generated, it is not possible to make the channel “good” again.

The solution is to regenerate the ''*.atf'' file, making sure the same bad channels are defined in the averaged artifact file as the to-be-corrected raw or average data file. You do not need to regenerate the artifact averages.

EKG correction is difficult because the topographic distribution of EKG signals is close to some MEG distributions: for instance, we sometimes observe a considerable reduction in alpha amplitudes with EKG correction. For event-related averaging, an EKG correction is often unnecessary, because the EKG is not synchronized with the stimulus.

[[Category:Data Import/Export]] [[Category:Preprocessing]] [[Category:Source Analysis]]

Using BESA to correct blink and EKG artifacts in MEG data

2021-02-02T11:57:01Z

Abinash: /* EKG */

{{BESAInfobox
|title = Module information
|module = BESA Research Standard or higher
|version = 6.1 or higher
}}

= Using BESA to correct blink and EKG artifacts in MEG data =

Eyeblinks and EKG cause large artifact signals in the magnetometer channels. The artifact correction facilities of BESA can correct these artifacts quite well. The procedure is quite simple for blinks but more complex for EKG. The following text outlines the procedures and current limitations of BESA for artifact correction.

The principles of the artifact correction procedure are described in ''Berg, P., Scherg, M. (1994) A multiple source approach to the correction of eye artifacts. Electroenceph. clin. Neurophysiol, 90: 229-241''.

In summary, the following steps are required:

* Use pattern search and average to identify the latencies of blink/EKG signals in the raw data. Pattern search works best if you have recorded a vertical EOG and EKG with the MEG data, but it will also work on selected MEG channels, using the appropriate filters.
* A spatial PCA is performed on the average to identify the main topographies/components of the artifact signal. For blinks, only one topography is required. For EKG, two or three topographies may be required.
* The topographies/components are combined into a coefficient file (''*.atf''). Using the '''Artifact''' Menu, the ''atf'' file can be loaded and correction switched on. Contrary to the warning message displayed by the ERP module, averaging can be performed using artifact corrected data.
* When the average is loaded into the Source Analysis module, the artifact coefficients (saved in the average file) need to be activated. They will then be incorporated into source modelling using subspace projection (SSP – see also papers by Uusitalo et al.). In this case, SSP is equivalent to the “optimized correction method” described in Berg & Scherg (1994).

== Pattern search for blinks and EKG ==

=== Eyeblinks ===

# Select filters 0.5 – 8 Hz ('''Filters/Edit Filter Settings…'''). Make sure the low cutoff filter type is '''Forward'''! (This is to ensure that no contribution from the blink topography bleeds back into the baseline time interval).
# View Polygraphic signals only (press the '''Pgr''' button at the top right of the BESA window), so that the vertical EOG channel is displayed
# Define the search block from –100 ms to +400 ms ('''Edit/Default Block Epoch…''')
# Select Pattern Search ('''Search/Pattern''')
# Select Search Query ('''Search/Query''')
# Select Buffer 1 for averaging ('''Tags/Pattern 1''')
# Identify a clear blink signal on the vertical EOG channel. Right-click at the '''onset''' of the blink, and select '''Default Block''' in the dropdown menu. The marked block should look something like this: [[File:EKG_artifacts_in_MEG_data__(1).png|75x55px]]
# Click once on the VEOG channel label, so that a rightward arrow is displayed (ignore the correlation window that opens on the right): [[File:EKG_artifacts_in_MEG_data__(2).png|100x55px]]
# Press the '''SAW''' button (Search/Average/Write). BESA will start scanning through the file, and it will stop at each occurrence of a blink. Press “Yes” to accept. “No” to reject, or “Stop asking” to let BESA accept everything automatically. Save the result to a file name of your choice (e.g. ''name_artifact.fsg''), labelling the segment, e.g. “blink”.

=== EKG ===

# In contrast to blink averaging we use two steps: first, filters are set to enhance the EKG for pattern search. Second, the filters are opened up, and the average is repeated.
# Select filters 5-20 Hz. This should generate a fairly clear signal on the EKG.
# Set the default block epoch so that the R-wave and the T-wave are well inside the epoch. The setting used for blinks may be OK, but you may need to extend the post-cursor interval, e.g. from 400 to 500 ms.
# Proceed as with blinks, but selecting Buffer 2 for averaging ('''Tags/Pattern 2'''). Mark a block around the onset of an R-wave. The marked block should look something like this: [[File:EKG_artifacts_in_MEG_data__(3).png|100x56px]]
# Save the average in the same file as the averaged blinks, labelling the segment, e.g. “EKG”.
# Select filters 1-30 Hz. Select '''Search/Tagged Events''', and press '''SAW'''. This repeats the average using the tags that were identified during the first step. Opening up the filters ensures that the average includes more of the EKG signal.

=== What to do if there is no VEOG or EKG channel ===

The procedure is similar to the above, but you need to identify a MEG channel that displays the blink or EKG waveform clearly. You may need to experiment with filter settings to make the artifact pattern clearer (the filter settings described above are not fixed rules – you may find that other settings work better for pattern search). You may find the “Create Triggers from EMG/EEG” tool helpful for detecting EKG ('''ERP/Create Triggers from EMG/EEG…'''). See the BESA help file (tutorial on creating triggers).

== Spatial PCA and the *.atf file ==

Open the file in which you saved the averages (e.g. ''name_artifact.fsg''). Make sure that prestimulus baseline correction is switched on ('''Filters/Use Prestimulus Baseline''').

=== Blinks ===

# Mark the whole blink epoch: Right-click onto the epoch, and select '''Whole Segment'''.
# Select '''Artifact/Assign/Blink'''. The spatial PCA is computed, and the first spatial component is assigned to describe the blink. You may check if the correction works by selecting '''Artifact/Correct'''.
# The coefficients are saved automatically to a file with the same basename as the average, and the extension ''“.atf''”.

=== EKG ===

EKG coefficients are corrected analogously to blinks. A difference is that the topographic distribution of the EKG over the MEG sensors is more complex than that of blinks. It changes over time. The reasons for this are unclear, and may be due to movement of the heart (and its equivalent dipoles) over time, but also to ballistic effects: movement of the head due to blood flow.

Since topographic distribution changes over time, more than one component is required for correction. We choose the number of components in the Artifact Select Dialog Box empirically: As a rule of thumb, if a component explains more than 5-10% of the variance of the averaged EKG signal, the component is included. Note that the number of components you select can also be changed when the coefficients are applied to the raw data.

== Correcting the raw data ==

* Switch back to the raw data file, and load the ''*.atf'' file you have created ('''Artifact/Load…''').
* Optionally, check that the artifact correction channels are visible (Artifact/View)
* Switch on artifact correction (Artifact/Correct).
* The figure on the next page shows the result of correction of channels A75-A148 on a three-second interval containing both EKG and eye activity. The blue label “1” marks the onset of a blink found during pattern search. The red “2” shows the onset of R-waves found during pattern search.
* Note that correction is quite good, but it is not perfect. In particular, there is some residual eye activity, e.g. around channels A91, A113, A131.

{|
! '''uncorrected'''
! '''corrected'''
|-
| [[File:EKG_artifacts_in_MEG_data__(4).png|57x57px]][[File:EKG_artifacts_in_MEG_data__(5).png|272x802px]]
| [[File:EKG_artifacts_in_MEG_data__(6).png|273x801px]]
|}

== Averaging the raw data ==

You can leave correction on during data averaging. When you press the Average button, a warning dialog will appear:

[[File:EKG_artifacts_in_MEG_data__(7).png|539x124px]]

You may select either option. Because of the recent installation of subspace projection (SSP) in the Source Module, the “distorted topographies” in the warning are no longer an issue for source analysis, provided SSP is switched on when the data are sent to the Source Module. The decision has consequences a) if you intend to analyze data waveform amplitudes and/or latencies, and b) if you intend to export the averages for analysis with other software.

==== Option “Yes” – turn off artifact correction ====

The averaged data will include EKG and eye artifacts, but these artifacts will not cause epochs to be rejected. The same number of epochs will be included in the average whether or not “Yes” or “No” is chosen.

You may load the correction coefficients (''*.atf'') for the average, and switch on artifact correction.

==== Option “No” – leave artifact correction on ====

The averaged data will be corrected. Each epoch is corrected before being included in the average.

==== Artifact options: which correction model? ====

The result of the correction on the raw data or the averaged data can be slightly different. The effects of correction will also vary, depending on the settings in '''Artifact/Options'''. These differences can be considered as consequences of variations in the “surrogate” or “adaptive” model of brain activity concurrent with the artifact activity (cf. Berg & Scherg 1994). These differences lead to changes in the estimate of the amounts of artifact activity to be removed by correction. If you intend to use the data waveforms outside BESA, and if you don’t use SSP with the artifact coefficients, then the settings in '''Artifact/Options''' become important. In current versions of BESA, these settings are based on EEG amplitude levels. In Konstanz, we generally use the values shown on the right. Note that these values are '''irrelevant''' if we use SSP in Source Analysis.

[[File:EKG_artifacts_in_MEG_data__(8).png|353x231px]]

== Sending the data to Source Analysis ==

When the average is generated, the correction coefficients are saved in the ''*.fsg'' file. Before you send the data to the Source Module, these coefficients must be '''activated'''.

* If you averaged the corrected data, coefficients are already activated. This should be apparent from the red “corrected” displayed above the channel labels.
* If you averaged the uncorrected data, load the saved ''*.atf'' file ('''Artifact/Load…'''), and switch on correction ('''Artifact/Correct''').

Then mark a time range and send the data to Source Analysis. At the right of the status bar, the text '''ART''' indicates that the artifact components are used in SSP.

[[File:EKG_artifacts_in_MEG_data__(9).png|143x158px]]

'''Alternatively, if you averaged the uncorrected data, load the average to Source Analysis, and then load the artifact coefficients as part of the dipole model (load or append solution, and use the dropdown list in the File Open box to select ''*.atf'' instead of ''*.bsa''). This approach has the advantage that the source waveforms of the spatial components show the contribution of eye and EKG activity to the model.'''

This implicit application of SSP during Source Analysis is mathematically equivalent to the “optimizing” correction method (cf. Berg & Scherg 1994): the topographies of the artifacts are implicitly incorporated into any dipole model.

== Limitations of the correction method in BESA ==

=== Bad channels ===

The ''*.atf'' file contains a two-line header with a) the number of channels, and b) the channel labels. If these do not match with the current data file, artifact correction is not possible. Bad channels are marked (with an asterisk next to the label), and the corresponding coefficient is set to zero. The irritating, but logical, the consequence is that if a channel was excluded (defined as “bad”) when the coefficients were generated, it is not possible to make the channel “good” again.

The solution is to regenerate the ''*.atf'' file, making sure the same bad channels are defined in the averaged artifact file as the to-be-corrected raw or average data file. You do not need to regenerate the artifact averages.

EKG correction is difficult because the topographic distribution of EKG signals is close to some MEG distributions: for instance, we sometimes observe a considerable reduction in alpha amplitudes with EKG correction. For event-related averaging, an EKG correction is often unnecessary, because the EKG is not synchronized with the stimulus.

[[Category:Data Import/Export]] [[Category:Preprocessing]] [[Category:Source Analysis]]

Using BESA to correct blink and EKG artifacts in MEG data

2021-02-02T11:56:44Z

Abinash: /* Eyeblinks */

{{BESAInfobox
|title = Module information
|module = BESA Research Standard or higher
|version = 6.1 or higher
}}

= Using BESA to correct blink and EKG artifacts in MEG data =

Eyeblinks and EKG cause large artifact signals in the magnetometer channels. The artifact correction facilities of BESA can correct these artifacts quite well. The procedure is quite simple for blinks but more complex for EKG. The following text outlines the procedures and current limitations of BESA for artifact correction.

The principles of the artifact correction procedure are described in ''Berg, P., Scherg, M. (1994) A multiple source approach to the correction of eye artifacts. Electroenceph. clin. Neurophysiol, 90: 229-241''.

In summary, the following steps are required:

* Use pattern search and average to identify the latencies of blink/EKG signals in the raw data. Pattern search works best if you have recorded a vertical EOG and EKG with the MEG data, but it will also work on selected MEG channels, using the appropriate filters.
* A spatial PCA is performed on the average to identify the main topographies/components of the artifact signal. For blinks, only one topography is required. For EKG, two or three topographies may be required.
* The topographies/components are combined into a coefficient file (''*.atf''). Using the '''Artifact''' Menu, the ''atf'' file can be loaded and correction switched on. Contrary to the warning message displayed by the ERP module, averaging can be performed using artifact corrected data.
* When the average is loaded into the Source Analysis module, the artifact coefficients (saved in the average file) need to be activated. They will then be incorporated into source modelling using subspace projection (SSP – see also papers by Uusitalo et al.). In this case, SSP is equivalent to the “optimized correction method” described in Berg & Scherg (1994).

== Pattern search for blinks and EKG ==

=== Eyeblinks ===

# Select filters 0.5 – 8 Hz ('''Filters/Edit Filter Settings…'''). Make sure the low cutoff filter type is '''Forward'''! (This is to ensure that no contribution from the blink topography bleeds back into the baseline time interval).
# View Polygraphic signals only (press the '''Pgr''' button at the top right of the BESA window), so that the vertical EOG channel is displayed
# Define the search block from –100 ms to +400 ms ('''Edit/Default Block Epoch…''')
# Select Pattern Search ('''Search/Pattern''')
# Select Search Query ('''Search/Query''')
# Select Buffer 1 for averaging ('''Tags/Pattern 1''')
# Identify a clear blink signal on the vertical EOG channel. Right-click at the '''onset''' of the blink, and select '''Default Block''' in the dropdown menu. The marked block should look something like this: [[File:EKG_artifacts_in_MEG_data__(1).png|75x55px]]
# Click once on the VEOG channel label, so that a rightward arrow is displayed (ignore the correlation window that opens on the right): [[File:EKG_artifacts_in_MEG_data__(2).png|100x55px]]
# Press the '''SAW''' button (Search/Average/Write). BESA will start scanning through the file, and it will stop at each occurrence of a blink. Press “Yes” to accept. “No” to reject, or “Stop asking” to let BESA accept everything automatically. Save the result to a file name of your choice (e.g. ''name_artifact.fsg''), labelling the segment, e.g. “blink”.

=== EKG ===

# In contrast to blink averaging we use two steps: first, filters are set to enhance the EKG for pattern search. Second, the filters are opened up, and the average is repeated.
# Select filters 5-20 Hz. This should generate a fairly clear signal on the EKG.
# Set the default block epoch so that the R-wave and the T-wave are well inside the epoch. The setting used for blinks may be OK, but you may need to extend the post-cursor interval, e.g. from 400 to 500 ms.
# Proceed as with blinks, but selecting Buffer 2 for averaging ('''Tags/Pattern 2'''). Mark a block around the onset of an R-wave. The marked block should look something like this: [[File:EKG_artifacts_in_MEG_data__(3).png|129x89px]]
# Save the average in the same file as the averaged blinks, labelling the segment, e.g. “EKG”.
# Select filters 1-30 Hz. Select '''Search/Tagged Events''', and press '''SAW'''. This repeats the average using the tags that were identified during the first step. Opening up the filters ensures that the average includes more of the EKG signal.

=== What to do if there is no VEOG or EKG channel ===

The procedure is similar to the above, but you need to identify a MEG channel that displays the blink or EKG waveform clearly. You may need to experiment with filter settings to make the artifact pattern clearer (the filter settings described above are not fixed rules – you may find that other settings work better for pattern search). You may find the “Create Triggers from EMG/EEG” tool helpful for detecting EKG ('''ERP/Create Triggers from EMG/EEG…'''). See the BESA help file (tutorial on creating triggers).

== Spatial PCA and the *.atf file ==

Open the file in which you saved the averages (e.g. ''name_artifact.fsg''). Make sure that prestimulus baseline correction is switched on ('''Filters/Use Prestimulus Baseline''').

=== Blinks ===

# Mark the whole blink epoch: Right-click onto the epoch, and select '''Whole Segment'''.
# Select '''Artifact/Assign/Blink'''. The spatial PCA is computed, and the first spatial component is assigned to describe the blink. You may check if the correction works by selecting '''Artifact/Correct'''.
# The coefficients are saved automatically to a file with the same basename as the average, and the extension ''“.atf''”.

=== EKG ===

EKG coefficients are corrected analogously to blinks. A difference is that the topographic distribution of the EKG over the MEG sensors is more complex than that of blinks. It changes over time. The reasons for this are unclear, and may be due to movement of the heart (and its equivalent dipoles) over time, but also to ballistic effects: movement of the head due to blood flow.

Since topographic distribution changes over time, more than one component is required for correction. We choose the number of components in the Artifact Select Dialog Box empirically: As a rule of thumb, if a component explains more than 5-10% of the variance of the averaged EKG signal, the component is included. Note that the number of components you select can also be changed when the coefficients are applied to the raw data.

== Correcting the raw data ==

* Switch back to the raw data file, and load the ''*.atf'' file you have created ('''Artifact/Load…''').
* Optionally, check that the artifact correction channels are visible (Artifact/View)
* Switch on artifact correction (Artifact/Correct).
* The figure on the next page shows the result of correction of channels A75-A148 on a three-second interval containing both EKG and eye activity. The blue label “1” marks the onset of a blink found during pattern search. The red “2” shows the onset of R-waves found during pattern search.
* Note that correction is quite good, but it is not perfect. In particular, there is some residual eye activity, e.g. around channels A91, A113, A131.

{|
! '''uncorrected'''
! '''corrected'''
|-
| [[File:EKG_artifacts_in_MEG_data__(4).png|57x57px]][[File:EKG_artifacts_in_MEG_data__(5).png|272x802px]]
| [[File:EKG_artifacts_in_MEG_data__(6).png|273x801px]]
|}

== Averaging the raw data ==

You can leave correction on during data averaging. When you press the Average button, a warning dialog will appear:

[[File:EKG_artifacts_in_MEG_data__(7).png|539x124px]]

You may select either option. Because of the recent installation of subspace projection (SSP) in the Source Module, the “distorted topographies” in the warning are no longer an issue for source analysis, provided SSP is switched on when the data are sent to the Source Module. The decision has consequences a) if you intend to analyze data waveform amplitudes and/or latencies, and b) if you intend to export the averages for analysis with other software.

==== Option “Yes” – turn off artifact correction ====

The averaged data will include EKG and eye artifacts, but these artifacts will not cause epochs to be rejected. The same number of epochs will be included in the average whether or not “Yes” or “No” is chosen.

You may load the correction coefficients (''*.atf'') for the average, and switch on artifact correction.

==== Option “No” – leave artifact correction on ====

The averaged data will be corrected. Each epoch is corrected before being included in the average.

==== Artifact options: which correction model? ====

The result of the correction on the raw data or the averaged data can be slightly different. The effects of correction will also vary, depending on the settings in '''Artifact/Options'''. These differences can be considered as consequences of variations in the “surrogate” or “adaptive” model of brain activity concurrent with the artifact activity (cf. Berg & Scherg 1994). These differences lead to changes in the estimate of the amounts of artifact activity to be removed by correction. If you intend to use the data waveforms outside BESA, and if you don’t use SSP with the artifact coefficients, then the settings in '''Artifact/Options''' become important. In current versions of BESA, these settings are based on EEG amplitude levels. In Konstanz, we generally use the values shown on the right. Note that these values are '''irrelevant''' if we use SSP in Source Analysis.

[[File:EKG_artifacts_in_MEG_data__(8).png|353x231px]]

== Sending the data to Source Analysis ==

When the average is generated, the correction coefficients are saved in the ''*.fsg'' file. Before you send the data to the Source Module, these coefficients must be '''activated'''.

* If you averaged the corrected data, coefficients are already activated. This should be apparent from the red “corrected” displayed above the channel labels.
* If you averaged the uncorrected data, load the saved ''*.atf'' file ('''Artifact/Load…'''), and switch on correction ('''Artifact/Correct''').

Then mark a time range and send the data to Source Analysis. At the right of the status bar, the text '''ART''' indicates that the artifact components are used in SSP.

[[File:EKG_artifacts_in_MEG_data__(9).png|143x158px]]

'''Alternatively, if you averaged the uncorrected data, load the average to Source Analysis, and then load the artifact coefficients as part of the dipole model (load or append solution, and use the dropdown list in the File Open box to select ''*.atf'' instead of ''*.bsa''). This approach has the advantage that the source waveforms of the spatial components show the contribution of eye and EKG activity to the model.'''

This implicit application of SSP during Source Analysis is mathematically equivalent to the “optimizing” correction method (cf. Berg & Scherg 1994): the topographies of the artifacts are implicitly incorporated into any dipole model.

== Limitations of the correction method in BESA ==

=== Bad channels ===

The ''*.atf'' file contains a two-line header with a) the number of channels, and b) the channel labels. If these do not match with the current data file, artifact correction is not possible. Bad channels are marked (with an asterisk next to the label), and the corresponding coefficient is set to zero. The irritating, but logical, the consequence is that if a channel was excluded (defined as “bad”) when the coefficients were generated, it is not possible to make the channel “good” again.

The solution is to regenerate the ''*.atf'' file, making sure the same bad channels are defined in the averaged artifact file as the to-be-corrected raw or average data file. You do not need to regenerate the artifact averages.

EKG correction is difficult because the topographic distribution of EKG signals is close to some MEG distributions: for instance, we sometimes observe a considerable reduction in alpha amplitudes with EKG correction. For event-related averaging, an EKG correction is often unnecessary, because the EKG is not synchronized with the stimulus.

[[Category:Data Import/Export]] [[Category:Preprocessing]] [[Category:Source Analysis]]

Using BESA to correct blink and EKG artifacts in MEG data

2021-02-02T11:55:20Z

Abinash: /* Pattern search for blinks and EKG */

{{BESAInfobox
|title = Module information
|module = BESA Research Standard or higher
|version = 6.1 or higher
}}

= Using BESA to correct blink and EKG artifacts in MEG data =

Eyeblinks and EKG cause large artifact signals in the magnetometer channels. The artifact correction facilities of BESA can correct these artifacts quite well. The procedure is quite simple for blinks but more complex for EKG. The following text outlines the procedures and current limitations of BESA for artifact correction.

The principles of the artifact correction procedure are described in ''Berg, P., Scherg, M. (1994) A multiple source approach to the correction of eye artifacts. Electroenceph. clin. Neurophysiol, 90: 229-241''.

In summary, the following steps are required:

* Use pattern search and average to identify the latencies of blink/EKG signals in the raw data. Pattern search works best if you have recorded a vertical EOG and EKG with the MEG data, but it will also work on selected MEG channels, using the appropriate filters.
* A spatial PCA is performed on the average to identify the main topographies/components of the artifact signal. For blinks, only one topography is required. For EKG, two or three topographies may be required.
* The topographies/components are combined into a coefficient file (''*.atf''). Using the '''Artifact''' Menu, the ''atf'' file can be loaded and correction switched on. Contrary to the warning message displayed by the ERP module, averaging can be performed using artifact corrected data.
* When the average is loaded into the Source Analysis module, the artifact coefficients (saved in the average file) need to be activated. They will then be incorporated into source modelling using subspace projection (SSP – see also papers by Uusitalo et al.). In this case, SSP is equivalent to the “optimized correction method” described in Berg & Scherg (1994).

== Pattern search for blinks and EKG ==

=== Eyeblinks ===

# Select filters 0.5 – 8 Hz ('''Filters/Edit Filter Settings…'''). Make sure the low cutoff filter type is '''Forward'''! (This is to ensure that no contribution from the blink topography bleeds back into the baseline time interval).
# View Polygraphic signals only (press the '''Pgr''' button at the top right of the BESA window), so that the vertical EOG channel is displayed
# Define the search block from –100 ms to +400 ms ('''Edit/Default Block Epoch…''')
# Select Pattern Search ('''Search/Pattern''')
# Select Search Query ('''Search/Query''')
# Select Buffer 1 for averaging ('''Tags/Pattern 1''')
# Identify a clear blink signal on the vertical EOG channel. Right-click at the '''onset''' of the blink, and select '''Default Block''' in the dropdown menu. The marked block should look something like this: [[File:EKG_artifacts_in_MEG_data__(1).png|100x75px]]
# Click once on the VEOG channel label, so that a rightward arrow is displayed (ignore the correlation window that opens on the right): [[File:EKG_artifacts_in_MEG_data__(2).png|100x55px]]
# Press the '''SAW''' button (Search/Average/Write). BESA will start scanning through the file, and it will stop at each occurrence of a blink. Press “Yes” to accept. “No” to reject, or “Stop asking” to let BESA accept everything automatically. Save the result to a file name of your choice (e.g. ''name_artifact.fsg''), labelling the segment, e.g. “blink”.

=== EKG ===

# In contrast to blink averaging we use two steps: first, filters are set to enhance the EKG for pattern search. Second, the filters are opened up, and the average is repeated.
# Select filters 5-20 Hz. This should generate a fairly clear signal on the EKG.
# Set the default block epoch so that the R-wave and the T-wave are well inside the epoch. The setting used for blinks may be OK, but you may need to extend the post-cursor interval, e.g. from 400 to 500 ms.
# Proceed as with blinks, but selecting Buffer 2 for averaging ('''Tags/Pattern 2'''). Mark a block around the onset of an R-wave. The marked block should look something like this: [[File:EKG_artifacts_in_MEG_data__(3).png|129x89px]]
# Save the average in the same file as the averaged blinks, labelling the segment, e.g. “EKG”.
# Select filters 1-30 Hz. Select '''Search/Tagged Events''', and press '''SAW'''. This repeats the average using the tags that were identified during the first step. Opening up the filters ensures that the average includes more of the EKG signal.

=== What to do if there is no VEOG or EKG channel ===

The procedure is similar to the above, but you need to identify a MEG channel that displays the blink or EKG waveform clearly. You may need to experiment with filter settings to make the artifact pattern clearer (the filter settings described above are not fixed rules – you may find that other settings work better for pattern search). You may find the “Create Triggers from EMG/EEG” tool helpful for detecting EKG ('''ERP/Create Triggers from EMG/EEG…'''). See the BESA help file (tutorial on creating triggers).

== Spatial PCA and the *.atf file ==

Open the file in which you saved the averages (e.g. ''name_artifact.fsg''). Make sure that prestimulus baseline correction is switched on ('''Filters/Use Prestimulus Baseline''').

=== Blinks ===

# Mark the whole blink epoch: Right-click onto the epoch, and select '''Whole Segment'''.
# Select '''Artifact/Assign/Blink'''. The spatial PCA is computed, and the first spatial component is assigned to describe the blink. You may check if the correction works by selecting '''Artifact/Correct'''.
# The coefficients are saved automatically to a file with the same basename as the average, and the extension ''“.atf''”.

=== EKG ===

EKG coefficients are corrected analogously to blinks. A difference is that the topographic distribution of the EKG over the MEG sensors is more complex than that of blinks. It changes over time. The reasons for this are unclear, and may be due to movement of the heart (and its equivalent dipoles) over time, but also to ballistic effects: movement of the head due to blood flow.

Since topographic distribution changes over time, more than one component is required for correction. We choose the number of components in the Artifact Select Dialog Box empirically: As a rule of thumb, if a component explains more than 5-10% of the variance of the averaged EKG signal, the component is included. Note that the number of components you select can also be changed when the coefficients are applied to the raw data.

== Correcting the raw data ==

* Switch back to the raw data file, and load the ''*.atf'' file you have created ('''Artifact/Load…''').
* Optionally, check that the artifact correction channels are visible (Artifact/View)
* Switch on artifact correction (Artifact/Correct).
* The figure on the next page shows the result of correction of channels A75-A148 on a three-second interval containing both EKG and eye activity. The blue label “1” marks the onset of a blink found during pattern search. The red “2” shows the onset of R-waves found during pattern search.
* Note that correction is quite good, but it is not perfect. In particular, there is some residual eye activity, e.g. around channels A91, A113, A131.

{|
! '''uncorrected'''
! '''corrected'''
|-
| [[File:EKG_artifacts_in_MEG_data__(4).png|57x57px]][[File:EKG_artifacts_in_MEG_data__(5).png|272x802px]]
| [[File:EKG_artifacts_in_MEG_data__(6).png|273x801px]]
|}

== Averaging the raw data ==

You can leave correction on during data averaging. When you press the Average button, a warning dialog will appear:

[[File:EKG_artifacts_in_MEG_data__(7).png|539x124px]]

You may select either option. Because of the recent installation of subspace projection (SSP) in the Source Module, the “distorted topographies” in the warning are no longer an issue for source analysis, provided SSP is switched on when the data are sent to the Source Module. The decision has consequences a) if you intend to analyze data waveform amplitudes and/or latencies, and b) if you intend to export the averages for analysis with other software.

==== Option “Yes” – turn off artifact correction ====

The averaged data will include EKG and eye artifacts, but these artifacts will not cause epochs to be rejected. The same number of epochs will be included in the average whether or not “Yes” or “No” is chosen.

You may load the correction coefficients (''*.atf'') for the average, and switch on artifact correction.

==== Option “No” – leave artifact correction on ====

The averaged data will be corrected. Each epoch is corrected before being included in the average.

==== Artifact options: which correction model? ====

The result of the correction on the raw data or the averaged data can be slightly different. The effects of correction will also vary, depending on the settings in '''Artifact/Options'''. These differences can be considered as consequences of variations in the “surrogate” or “adaptive” model of brain activity concurrent with the artifact activity (cf. Berg & Scherg 1994). These differences lead to changes in the estimate of the amounts of artifact activity to be removed by correction. If you intend to use the data waveforms outside BESA, and if you don’t use SSP with the artifact coefficients, then the settings in '''Artifact/Options''' become important. In current versions of BESA, these settings are based on EEG amplitude levels. In Konstanz, we generally use the values shown on the right. Note that these values are '''irrelevant''' if we use SSP in Source Analysis.

[[File:EKG_artifacts_in_MEG_data__(8).png|353x231px]]

== Sending the data to Source Analysis ==

When the average is generated, the correction coefficients are saved in the ''*.fsg'' file. Before you send the data to the Source Module, these coefficients must be '''activated'''.

* If you averaged the corrected data, coefficients are already activated. This should be apparent from the red “corrected” displayed above the channel labels.
* If you averaged the uncorrected data, load the saved ''*.atf'' file ('''Artifact/Load…'''), and switch on correction ('''Artifact/Correct''').

Then mark a time range and send the data to Source Analysis. At the right of the status bar, the text '''ART''' indicates that the artifact components are used in SSP.

[[File:EKG_artifacts_in_MEG_data__(9).png|143x158px]]

'''Alternatively, if you averaged the uncorrected data, load the average to Source Analysis, and then load the artifact coefficients as part of the dipole model (load or append solution, and use the dropdown list in the File Open box to select ''*.atf'' instead of ''*.bsa''). This approach has the advantage that the source waveforms of the spatial components show the contribution of eye and EKG activity to the model.'''

This implicit application of SSP during Source Analysis is mathematically equivalent to the “optimizing” correction method (cf. Berg & Scherg 1994): the topographies of the artifacts are implicitly incorporated into any dipole model.

== Limitations of the correction method in BESA ==

=== Bad channels ===

The ''*.atf'' file contains a two-line header with a) the number of channels, and b) the channel labels. If these do not match with the current data file, artifact correction is not possible. Bad channels are marked (with an asterisk next to the label), and the corresponding coefficient is set to zero. The irritating, but logical, the consequence is that if a channel was excluded (defined as “bad”) when the coefficients were generated, it is not possible to make the channel “good” again.

The solution is to regenerate the ''*.atf'' file, making sure the same bad channels are defined in the averaged artifact file as the to-be-corrected raw or average data file. You do not need to regenerate the artifact averages.

EKG correction is difficult because the topographic distribution of EKG signals is close to some MEG distributions: for instance, we sometimes observe a considerable reduction in alpha amplitudes with EKG correction. For event-related averaging, an EKG correction is often unnecessary, because the EKG is not synchronized with the stimulus.

[[Category:Data Import/Export]] [[Category:Preprocessing]] [[Category:Source Analysis]]

Using BESA to correct blink and EKG artifacts in MEG data

2021-02-02T11:54:41Z

Abinash: /* Pattern search for blinks and EKG */

{{BESAInfobox
|title = Module information
|module = BESA Research Standard or higher
|version = 6.1 or higher
}}

= Using BESA to correct blink and EKG artifacts in MEG data =

Eyeblinks and EKG cause large artifact signals in the magnetometer channels. The artifact correction facilities of BESA can correct these artifacts quite well. The procedure is quite simple for blinks but more complex for EKG. The following text outlines the procedures and current limitations of BESA for artifact correction.

The principles of the artifact correction procedure are described in ''Berg, P., Scherg, M. (1994) A multiple source approach to the correction of eye artifacts. Electroenceph. clin. Neurophysiol, 90: 229-241''.

In summary, the following steps are required:

* Use pattern search and average to identify the latencies of blink/EKG signals in the raw data. Pattern search works best if you have recorded a vertical EOG and EKG with the MEG data, but it will also work on selected MEG channels, using the appropriate filters.
* A spatial PCA is performed on the average to identify the main topographies/components of the artifact signal. For blinks, only one topography is required. For EKG, two or three topographies may be required.
* The topographies/components are combined into a coefficient file (''*.atf''). Using the '''Artifact''' Menu, the ''atf'' file can be loaded and correction switched on. Contrary to the warning message displayed by the ERP module, averaging can be performed using artifact corrected data.
* When the average is loaded into the Source Analysis module, the artifact coefficients (saved in the average file) need to be activated. They will then be incorporated into source modelling using subspace projection (SSP – see also papers by Uusitalo et al.). In this case, SSP is equivalent to the “optimized correction method” described in Berg & Scherg (1994).

== Pattern search for blinks and EKG ==

=== Eyeblinks ===

# Select filters 0.5 – 8 Hz ('''Filters/Edit Filter Settings…'''). Make sure the low cutoff filter type is '''Forward'''! (This is to ensure that no contribution from the blink topography bleeds back into the baseline time interval).
# View Polygraphic signals only (press the '''Pgr''' button at the top right of the BESA window), so that the vertical EOG channel is displayed
# Define the search block from –100 ms to +400 ms ('''Edit/Default Block Epoch…''')
# Select Pattern Search ('''Search/Pattern''')
# Select Search Query ('''Search/Query''')
# Select Buffer 1 for averaging ('''Tags/Pattern 1''')
# Identify a clear blink signal on the vertical EOG channel. Right-click at the '''onset''' of the blink, and select '''Default Block''' in the dropdown menu. The marked block should look something like this: [[File:EKG_artifacts_in_MEG_data__(1).png|100x75px]]
# Click once on the VEOG channel label, so that a rightward arrow is displayed (ignore the correlation window that opens on the right): [[File:EKG_artifacts_in_MEG_data__(2).png|134x72px]]
# Press the '''SAW''' button (Search/Average/Write). BESA will start scanning through the file, and it will stop at each occurrence of a blink. Press “Yes” to accept. “No” to reject, or “Stop asking” to let BESA accept everything automatically. Save the result to a file name of your choice (e.g. ''name_artifact.fsg''), labelling the segment, e.g. “blink”.

=== EKG ===

# In contrast to blink averaging we use two steps: first, filters are set to enhance the EKG for pattern search. Second, the filters are opened up, and the average is repeated.
# Select filters 5-20 Hz. This should generate a fairly clear signal on the EKG.
# Set the default block epoch so that the R-wave and the T-wave are well inside the epoch. The setting used for blinks may be OK, but you may need to extend the post-cursor interval, e.g. from 400 to 500 ms.
# Proceed as with blinks, but selecting Buffer 2 for averaging ('''Tags/Pattern 2'''). Mark a block around the onset of an R-wave. The marked block should look something like this: [[File:EKG_artifacts_in_MEG_data__(3).png|129x89px]]
# Save the average in the same file as the averaged blinks, labelling the segment, e.g. “EKG”.
# Select filters 1-30 Hz. Select '''Search/Tagged Events''', and press '''SAW'''. This repeats the average using the tags that were identified during the first step. Opening up the filters ensures that the average includes more of the EKG signal.

=== What to do if there is no VEOG or EKG channel ===

The procedure is similar to the above, but you need to identify a MEG channel that displays the blink or EKG waveform clearly. You may need to experiment with filter settings to make the artifact pattern clearer (the filter settings described above are not fixed rules – you may find that other settings work better for pattern search). You may find the “Create Triggers from EMG/EEG” tool helpful for detecting EKG ('''ERP/Create Triggers from EMG/EEG…'''). See the BESA help file (tutorial on creating triggers).

== Spatial PCA and the *.atf file ==

Open the file in which you saved the averages (e.g. ''name_artifact.fsg''). Make sure that prestimulus baseline correction is switched on ('''Filters/Use Prestimulus Baseline''').

=== Blinks ===

# Mark the whole blink epoch: Right-click onto the epoch, and select '''Whole Segment'''.
# Select '''Artifact/Assign/Blink'''. The spatial PCA is computed, and the first spatial component is assigned to describe the blink. You may check if the correction works by selecting '''Artifact/Correct'''.
# The coefficients are saved automatically to a file with the same basename as the average, and the extension ''“.atf''”.

=== EKG ===

EKG coefficients are corrected analogously to blinks. A difference is that the topographic distribution of the EKG over the MEG sensors is more complex than that of blinks. It changes over time. The reasons for this are unclear, and may be due to movement of the heart (and its equivalent dipoles) over time, but also to ballistic effects: movement of the head due to blood flow.

Since topographic distribution changes over time, more than one component is required for correction. We choose the number of components in the Artifact Select Dialog Box empirically: As a rule of thumb, if a component explains more than 5-10% of the variance of the averaged EKG signal, the component is included. Note that the number of components you select can also be changed when the coefficients are applied to the raw data.

== Correcting the raw data ==

* Switch back to the raw data file, and load the ''*.atf'' file you have created ('''Artifact/Load…''').
* Optionally, check that the artifact correction channels are visible (Artifact/View)
* Switch on artifact correction (Artifact/Correct).
* The figure on the next page shows the result of correction of channels A75-A148 on a three-second interval containing both EKG and eye activity. The blue label “1” marks the onset of a blink found during pattern search. The red “2” shows the onset of R-waves found during pattern search.
* Note that correction is quite good, but it is not perfect. In particular, there is some residual eye activity, e.g. around channels A91, A113, A131.

{|
! '''uncorrected'''
! '''corrected'''
|-
| [[File:EKG_artifacts_in_MEG_data__(4).png|57x57px]][[File:EKG_artifacts_in_MEG_data__(5).png|272x802px]]
| [[File:EKG_artifacts_in_MEG_data__(6).png|273x801px]]
|}

== Averaging the raw data ==

You can leave correction on during data averaging. When you press the Average button, a warning dialog will appear:

[[File:EKG_artifacts_in_MEG_data__(7).png|539x124px]]

You may select either option. Because of the recent installation of subspace projection (SSP) in the Source Module, the “distorted topographies” in the warning are no longer an issue for source analysis, provided SSP is switched on when the data are sent to the Source Module. The decision has consequences a) if you intend to analyze data waveform amplitudes and/or latencies, and b) if you intend to export the averages for analysis with other software.

==== Option “Yes” – turn off artifact correction ====

The averaged data will include EKG and eye artifacts, but these artifacts will not cause epochs to be rejected. The same number of epochs will be included in the average whether or not “Yes” or “No” is chosen.

You may load the correction coefficients (''*.atf'') for the average, and switch on artifact correction.

==== Option “No” – leave artifact correction on ====

The averaged data will be corrected. Each epoch is corrected before being included in the average.

==== Artifact options: which correction model? ====

The result of the correction on the raw data or the averaged data can be slightly different. The effects of correction will also vary, depending on the settings in '''Artifact/Options'''. These differences can be considered as consequences of variations in the “surrogate” or “adaptive” model of brain activity concurrent with the artifact activity (cf. Berg & Scherg 1994). These differences lead to changes in the estimate of the amounts of artifact activity to be removed by correction. If you intend to use the data waveforms outside BESA, and if you don’t use SSP with the artifact coefficients, then the settings in '''Artifact/Options''' become important. In current versions of BESA, these settings are based on EEG amplitude levels. In Konstanz, we generally use the values shown on the right. Note that these values are '''irrelevant''' if we use SSP in Source Analysis.

[[File:EKG_artifacts_in_MEG_data__(8).png|353x231px]]

== Sending the data to Source Analysis ==

When the average is generated, the correction coefficients are saved in the ''*.fsg'' file. Before you send the data to the Source Module, these coefficients must be '''activated'''.

* If you averaged the corrected data, coefficients are already activated. This should be apparent from the red “corrected” displayed above the channel labels.
* If you averaged the uncorrected data, load the saved ''*.atf'' file ('''Artifact/Load…'''), and switch on correction ('''Artifact/Correct''').

Then mark a time range and send the data to Source Analysis. At the right of the status bar, the text '''ART''' indicates that the artifact components are used in SSP.

[[File:EKG_artifacts_in_MEG_data__(9).png|143x158px]]

'''Alternatively, if you averaged the uncorrected data, load the average to Source Analysis, and then load the artifact coefficients as part of the dipole model (load or append solution, and use the dropdown list in the File Open box to select ''*.atf'' instead of ''*.bsa''). This approach has the advantage that the source waveforms of the spatial components show the contribution of eye and EKG activity to the model.'''

This implicit application of SSP during Source Analysis is mathematically equivalent to the “optimizing” correction method (cf. Berg & Scherg 1994): the topographies of the artifacts are implicitly incorporated into any dipole model.

== Limitations of the correction method in BESA ==

=== Bad channels ===

The ''*.atf'' file contains a two-line header with a) the number of channels, and b) the channel labels. If these do not match with the current data file, artifact correction is not possible. Bad channels are marked (with an asterisk next to the label), and the corresponding coefficient is set to zero. The irritating, but logical, the consequence is that if a channel was excluded (defined as “bad”) when the coefficients were generated, it is not possible to make the channel “good” again.

The solution is to regenerate the ''*.atf'' file, making sure the same bad channels are defined in the averaged artifact file as the to-be-corrected raw or average data file. You do not need to regenerate the artifact averages.

EKG correction is difficult because the topographic distribution of EKG signals is close to some MEG distributions: for instance, we sometimes observe a considerable reduction in alpha amplitudes with EKG correction. For event-related averaging, an EKG correction is often unnecessary, because the EKG is not synchronized with the stimulus.

[[Category:Data Import/Export]] [[Category:Preprocessing]] [[Category:Source Analysis]]

Main Page

2021-02-02T11:47:05Z

Abinash: /* File Formats */

Welcome to the BESA Wiki!

This wiki is designed to help users with typical questions around using BESA to achieve their goals.

Topics are available for the following categories:

== Manual ==

[[BESA Research Manual]]

== Videos ==

[[Video tutorials]]

== FAQ ==

=== Licensing ===

:[[Licensing]]

:[[License session not freed|License session not freed (BESA MRI 64 bit version)]]

=== File Formats ===

:[[ASCII File Format]]

:[[Channel Definition File Formats]]

:[[Event File Format]]

:[[MEG Sensor Coordinate Files]]

:[[Supported Data Formats]]

:[[Paradigm File Format in BESA]]

:[[Importing Electrode Locations in Combined EEG/MEG Measurements with the Neuromag System]]

:[[BESA files extensions]]

:[[Talairach Transformation File]]

:[[Reading BioSemi data with BESA]]

:[[Using Net Station Data with BESA]]

=== Data Review and Analysis ===

:[[Importing Digitized Coordinates]]

:[[Verify Electrode Coordinates]]

:[[Export Single Trial Data]]

:[[How to Average EEG channels]]

:[[Averaging Across EEG Datasets from Different Recording Systems]]

:[[Time Frequency Resolution In BESA]]

:[[Change Waveform Colours]]

:[[Best Strategy to Define a Multiple Source Model]]

:[[Export Dipole Moments of Fitted Sources]]

:[[Recommended Electrode Configurations]]

:[[Exporting Artifact-Corrected Data]]

:[[Create Triggers for Artifact-Rejected Epochs]]

:[[Inserting Triggers Relative to Existing Events]]

:[[Change or Exclude Erroneous Head Surface Point Locations]]

:[[Exporting Top Viewer Waveforms into other Graphics Software for Further Processing]]

:[[Seed dipole solutions from cortical images]]

:[[Pipeline for simultaneous EEG-fMRI recording]]

:[[The source space in individual FEM head models]]

:[[Export each gradiometer and magnetometer data separately]]

:[[Peak Finder explained]]

:[[Using BESA to correct blink and EKG artifacts in MEG data]]

=== MATLAB interface ===

:[[How Do I Configure the Matlab Interface?]]

:[[Updating the Matlab Interface after Matlab Upgrade]]

:[[Exporting Data from Matlab to BESA Statistics]]

:[[Visualization with BESA Plot in FieldTrip]]

=== BESA MRI===

:[[Marking AC-PC Points in BESA MRI]]

=== BESA Statistics ===

:[[Cluster Alpha vs. Neighbor Distance]]

:[[How to Prepare Data for BESA Statistics]]

:[[Importing BESA Statistics Results into Excel]]

:[[Exporting Data from Matlab to BESA Statistics]]

=== BESA Connectivity ===

:[[How to Prepare Data for BESA Connectivity]]

:[[Export Connectivity Results]]

:[[How to Convert BESA Connectivity results for BESA Statistics]]

=== Operating systems ===

:[[Running BESA Research on the Mac]]

=== Troubleshooting ===

:[[MF Error 211| The internal error MF_211 (BESA MRI, BESA Statistics and BESA Connectivity)]]

:[[3D Graphics Display Issue Handling]]

:[[Batch Error Handling]]

:[[Error message: Failed to load library|Error message: Failed to load library during software installation]]

:[[License session not freed|License session not freed in BESA MRI 64 bit version]]

:[[Install And Update File Format Readers]]

:[[Wrong characters in BESA software]]

:[[Blank white screen when capturing the 3D window of the source analysis window]]

:[[Error opening program or opening the file dialog box]]

== BESA Recipes ==

<div style="column-count:2; -moz-column-count:2; -webkit-column-count:2">

* [[Control of BESA Research by external programs]]
* [[Correcting Volume Conductor Segmentations]]
* [[Exporting Data from Matlab to BESA Statistics]]
* [[Integration of Custom Template Head-Models]]
* [[Random Averaging]]
* [[Statistical Analysis for More than Two Levels]]
* [[Visualization with BESA Plot in FieldTrip]]
* [[Pipeline for simultaneous EEG-fMRI recording]]
* [[How to deal with TMS artifact in BESA Research]]

</div>

== Did you know...? ==

<div style="column-count:2; -moz-column-count:2; -webkit-column-count:2">

* [[Moving Dipole Fit]]
* [[BESA Anonymizer]]
* [[Batch Processing]]
* [[Analyzing Electrocorticography Data]]
* [[Advanced Top Viewer Features]]

</div>

== Coming soon ==

* a collection of useful batches
* and further content we will be publishing on this wiki

Contributions to the Wiki from the community are very welcome! Please create an account with a valid email to edit the BESA Wiki's content.

Consult the [//meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.

Using Net Station Data with BESA

2021-02-02T11:46:24Z

Abinash:

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = 6.0 or higher
}}

= Using Net Station Data with BESA =

== Introduction ==

When sharing Net Station data with BESA, it is best to either share:

* Data that hasn’t been processed in any way, except segmentation markup, discussed below (ie don’t filter, don’t convert to microvolts [in the future, after a known issue in Net Station is resolved it will be possible to convert to microvolts]), or
* ERP data, in other words, data that has been processed in Net Station all the way through averaging.

In either case, the recommended file format is Epoch Marked Simple Binary File. Also, known as Epoch Marked Raw. Export to this format is only available in Net Station 3.0, through the File Export tool of the Waveform Tools. If you need to share Net Station data with BESA, and you don’t have access to this tool, please contact EGI Support ([mailto:support@egi.com) support@egi.com)].

The details vary, depending on whether you are exporting unprocessed data or ERP data. Each of these cases is discussed below:

== Exporting Unprocessed Data ==

=== Segmentation Markup ===

This section assumes you are familiar with Net Station Segmentation, and the structure of a simple standard/target experiment.

Net Station events contain key lists, in other words, mini databases. Using a simple standard/target experiment as an example, in Net Station all stimuli events might be named “stim.” The distinction between standards and targets can’t be determined from the name of the event. It can only be determined from the key list in the events. In most programs, including BESA, events only have names. They don’t have key lists.

To make the jump from key-list events to non-keylist events, you must use Net Station’s segmentation markup. Segmentation markup adds events to the recording that BESA can use. To use segmentation markup, create a segmentation specification, and check the “Mark Up File” checkbox in the segmentation specification editor. When you run segmentation using this specification, instead of segmenting the file, new events will be added for BESA.

For example, if all your standard and target stimuli are named “stim”, you would create a segmentation specification just as you would for segmenting this file into standard and target categories. Then, if you check the “Mark Up File” checkbox, the specification will cause new events to be added to the file instead of segmentation. Then, you can add events called “stnd” for standard, and “targ” for target.

Note: Although Net Station allows you to add markup events with spaces in the names, it might cause unpredictable results in BESA. Also, Net Station generates the event names automatically, but you can modify them. Sometimes the automatically generated ones contain spaces. Simply edit them, for example, replace the spaces with underscore characters.

The objective is to be able to do segmentation in BESA. So, before exporting to BESA, use segmentation markup to add all the events you might want to use in BESA. Although a simple standard/target experiment was used in this example, you can combine the full power of Net Station’s segmentation with the segmentation markup feature.

=== Export ===

As mentioned above, you need to export to the Epoch Marked Simple Binary File format using the File Export tool. The following explains the options to use:

Since this data hasn’t been re-referenced, do not export the reference channel. In other words, leave the “Export Reference Channel” checkbox unchecked.

You have the option of using integer or floating-point precision. Each of these options is discussed below.

The advantage of using integer precision is that export is faster, and results in a file that is about half the size of floating-point. The disadvantage is that the individual gains and zeros aren’t applied to the data. If your amplifier is in spec, the loss should be negligible. If you choose this option, leave the “Calibrate Data” checkbox unchecked.

The advantage of using floating-point precision is that it is much more precise. The disadvantage is that export is slower, and results in a file that is about twice the size of an integer. If you choose this option, make sure that you do check the “Calibrate Data” checkbox.

In either case, set the name of the output file to append the extension “.raw”.

=== Opening in BESA ===

After you have generated the .raw file, move it to the BESA PC. You should now be able to read this file with BESA. To do so, in the File Open Dialog Box, set the “Files of type” dropdown list to “EGI Formats(*.raw…”.

If you do this, BESA will read all the events in the file, and assign trigger numbers to them (except the following, which are meaningless to BESA: CELL, SESS, bgin and TRSP).

Optionally, you can control which events are read by BESA by creating a .trig file. A .trig file is a tab-delimited file that contains one line for each event type that you want BESA to read. Each line consists of the name of the event, followed by a tab character, followed by a number between 1 and <255? 256? 65535? 65536?>. The following is an example of a .trig file:

stnd 1

targ 2

resp 128

You might want to use a .trig file if:

* your data has a large number of events, and you don’t need most of them in BESA, or,
* you want to include events with any of these names: CELL, SESS, bgin and TRSP.

To use a .trig file, just make sure that the file is in the same directory as your data file when you open the data file. In addition, the .trig file must be named either “default.trig”, or <your data file name>.trig (eg “subject1.trig”).

=== Loading Sensor Coordinates ===

After you have opened the file, you must load the sensor coordinate files (File->”Head Surface Points and Sensors”->”Load Coordinate Files”. If want to use average sensor position files (as opposed to files individually digitized for your subject), use the files in “C:\Besa\Examples\Xtras\EEG Binary Formats\EGI” directory.

If you have 256 channel data, use GSN256andRef.ela, and GSN257.sfp.

If you have 128 channel data, use GSN128andRef.ela, and GSN129.sfp.

If you have 64 channel data v1, use GSN64andRef.ela, and GSN65v1_0.sfp.

If you have 64 channel data v2, use GSN64andRef.ela, and GSN65v2_0.sfp.

You are now ready to do your ERP derivation in BESA.

== Exporting Averaged ERP Data ==

=== Export ===

If you have derived your ERP in Net Station, and wish to export it to BESA for source localization, once again, use the File Export tool, exporting in the Epoch Marked Simple Binary File format. The following explains the options to use:

(This explanation assumes that the data has been re-referenced during the ERP derivation process.)

Since this data has been re-referenced, you should export the reference channel. In other words, check the “Export Reference Channel” checkbox.

For averaged data, you need to export using floating-point precision. Since the data has been calibrated during the ERP derivation process, it doesn’t matter what you do with the “Calibrate Data” checkbox. Set the name of the output file to append the extension “.raw”.

When exporting averaged ERP data (or any Net Station data that has been categorized, for example, segmented data), Net Station generates an additional file: < your file name>.epoc. This file contains the names of the conditions for each epoch in the data.

=== Opening in BESA ===

After you have generated the .raw file, move it, and the .epoc file, to the BESA PC, keeping both files in the same directory. You should now be able to read this file with BESA. To do so, in the File Open Dialog Box, set the “Files of type” dropdown list to “EGI Formats(*.raw…”.

=== Loading Sensor Coordinates ===

After you have opened the file, you must load the sensor coordinate files (File->”Head Surface Points and Sensors”->”Load Coordinate Files”. If want to use average sensor position files (as opposed to files individually digitized for your subject), use the files in “C:\Besa\Examples\Xtras\EEG Binary Formats\EGI” directory.

If you have 256 channel data, use GSN257.ela, and GSN257.sfp.

If you have 128 channel data, use GSN129.ela, and GSN129.sfp.

If you have 64 channel data v1, use GSN65.ela, and GSN65v1_0.sfp.

If you have 64 channel data v2, use GSN65.ela, and GSN65v2_0.sfp.

You are now ready to do source analysis in BESA.

[[Category:Setup]] [[Category:Data Import/Export]]

Using Net Station Data with BESA

2021-02-02T11:45:07Z

Abinash: /* Export */

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = 6.0 or higher
}}

= Using Net Station Data with BESA =

== Introduction ==

When sharing Net Station data with BESA, it is best to either share:

* Data that hasn’t been processed in any way, except segmentation markup, discussed below (ie don’t filter, don’t convert to microvolts [in the future, after a known issue in Net Station is resolved it will be possible to convert to microvolts]), or
* ERP data, in other words data that has been processed in Net Station all the way through averaging.

In either case, the recommended file format is Epoch Marked Simple Binary File. Also, known as Epoch Marked Raw. Export to this format is only available in Net Station 3.0, through the File Export tool of the Waveform Tools. If you need to share Net Station data with BESA, and you don’t have access to this tool, please contact EGI Support ([mailto:support@egi.com) support@egi.com)].

The details vary, depending on whether you are exporting unprocessed data, or ERP data. Each of these cases is discussed below:

== Exporting Unprocessed Data ==

=== Segmentation Markup ===

This section assumes you are familiar with Net Station Segmentation, and the structure of a simple standard/target experiment.

Net Station events contain key lists, in other words, mini databases. Using a simple standard/target experiment as an example, in Net Station all stimulii events might be named “stim.” The distinction between standards and targets can’t be determined from the name of the event. It can only be determined from the key list in the events. In most programs, including BESA, events only have names. They don’t have key lists.

To make the jump from key-list events to non-keylist events, you must use Net Station’s segmentation markup. Segmentation markup adds events to the recording that BESA can use. To use segmentation markup, create a segmentation specification, and check the “Mark Up File” checkbox in the segmentation specification editor. When you run segmentation using this specification, instead of segmenting the file, new events will be added for BESA.

For example, if all your standard and target stimulii are named “stim”, you would create a segmentation specification just as you would for segmenting this file into standard and target categories. Then, if you check the “Mark Up File” checkbox, the specification will cause new events to be added to the file instead of segmentation. Then, you can add events called “stnd” for standard, and “targ” for target.

Note: Although Net Station allows you to add markup events with spaces in the names, it might cause unpredictable results in BESA. Also, Net Station generates the event names automatically, but you can modify them. Sometimes the automatically generated ones contain spaces. Simply edit them, for example, replace thespaces with underscore characters.

The objective is to be able to do segmentation in BESA. So, before exporting to BESA, use segmentation markup to add all the events you might want to use in BESA. Although a simple standard/target experiment was used in this example, you can combine the full power of Net Station’s segmentation with the segmentation markup feature.

=== Export ===

As mentioned above, you need to export to the Epoch Marked Simple Binary File format using the File Export tool. The following explains the options to use:

Since this data hasn’t been rereferenced, do not export the reference channel. In other words, leave the “Export Reference Channel” checkbox unchecked.

You have the option of using integer or floating point precision. Each of these options is discussed below.

The advantage of using integer precision is that export is faster, and results in a file that is about half the size of floating point. The disadvantage is that the individual gains and zeros aren’t applied to the data. If your amplifier is in spec, the loss should be negligible. If you choose this option, leave the “Calibrate Data” checkbox unchecked.

The advantage of using floating point precision is that it is much more precise. The disadvantage is that export is slower, and results in a file that is about twice the size of integer. If you choose this option, make sure that you do check the “Calibrate Data” checkbox.

In either case, set the name of the output file to append the extention “.raw”.

=== Opening in BESA ===

After you have generated the .raw file, move it to the BESA PC. You should now be able to read this file with BESA. To do so, in the File Open Dialog Box, set the “Files of type” dropdown list to “EGI Formats(*.raw…”.

If you do this, BESA will read all the events in the file, and assign trigger numbers to them (except the following, which are meaningless to BESA: CELL, SESS, bgin and TRSP).

Optionally, you can control which events are read by BESA by creating a .trig file. A .trig file is a tab delimited file that contains one line for each event type that you want BESA to read. Each line consists of the name of the event, followed by a tab character, followed by a number between 1 and <255? 256? 65535? 65536?>. The following is an example of a .trig file:

stnd 1

targ 2

resp 128

You might want to use a .trig file if:

* your data has a large number of events, and you don’t need most of them in BESA, or,
* you want to include events with any of these names: CELL, SESS, bgin and TRSP.

To use a .trig file, just make sure that the file is in the same directory as your data file when you open the data file. In addition, the .trig file must be named either “detault.trig”, or <your data file name>.trig (eg “subject1.trig”).

=== Loading Sensor Coordinates ===

After you have opened the file, you must load the sensor coordinate files (File->”Head Surface Points and Sensors”->”Load Coordinate Files”. If want to use average sensor position files (as opposed to files individually digitized for your subject), use the files in “C:\Besa\Examples\Xtras\EEG Binary Formats\EGI” directory.

If you have 256 channel data, use GSN256andRef.ela, and GSN257.sfp.

If you have 128 channel data, use GSN128andRef.ela, and GSN129.sfp.

If you have 64 channel data v1, use GSN64andRef.ela, and GSN65v1_0.sfp.

If you have 64 channel data v2, use GSN64andRef.ela, and GSN65v2_0.sfp.

You are now ready to do your ERP derivation in BESA.

== Exporting Averaged ERP Data ==

=== Export ===

If you have derived your ERP in Net Station, and wish to export it to BESA for source localization, once again, use the File Export tool, exporting in the Epoch Marked Simple Binary File format. The following explains the options to use:

(This explanation assumes that the data has been re-referenced during the ERP derivation process.)

Since this data has been re-referenced, you should export the reference channel. In other words, check the “Export Reference Channel” checkbox.

For averaged data, you need to export using floating-point precision. Since the data has been calibrated during the ERP derivation process, it doesn’t matter what you do with the “Calibrate Data” checkbox. Set the name of the output file to append the extension “.raw”.

When exporting averaged ERP data (or any Net Station data that has been categorized, for example, segmented data), Net Station generates an additional file: < your file name>.epoc. This file contains the names of the conditions for each epoch in the data.

=== Opening in BESA ===

After you have generated the .raw file, move it, and the .epoc file, to the BESA PC, keeping both files in the same directory. You should now be able to read this file with BESA. To do so, in the File Open Dialog Box, set the “Files of type” dropdown list to “EGI Formats(*.raw…”.

=== Loading Sensor Coordinates ===

After you have opened the file, you must load the sensor coordinate files (File->”Head Surface Points and Sensors”->”Load Coordinate Files”. If want to use average sensor position files (as opposed to files individually digitized for your subject), use the files in “C:\Besa\Examples\Xtras\EEG Binary Formats\EGI” directory.

If you have 256 channel data, use GSN257.ela, and GSN257.sfp.

If you have 128 channel data, use GSN129.ela, and GSN129.sfp.

If you have 64 channel data v1, use GSN65.ela, and GSN65v1_0.sfp.

If you have 64 channel data v2, use GSN65.ela, and GSN65v2_0.sfp.

You are now ready to do source analysis in BESA.

[[Category:Setup]] [[Category:Data Import/Export]]

Using Net Station Data with BESA

2021-02-02T11:44:09Z

Abinash: Created page with "{{BESAInfobox |title = Module information |module = BESA Research Basic or higher |version = 6.0 or higher }} = Using Net Station Data with BESA = == Introduction == When s..."

{{BESAInfobox
|title = Module information
|module = BESA Research Basic or higher
|version = 6.0 or higher
}}

= Using Net Station Data with BESA =

== Introduction ==

When sharing Net Station data with BESA, it is best to either share:

* Data that hasn’t been processed in any way, except segmentation markup, discussed below (ie don’t filter, don’t convert to microvolts [in the future, after a known issue in Net Station is resolved it will be possible to convert to microvolts]), or
* ERP data, in other words data that has been processed in Net Station all the way through averaging.

In either case, the recommended file format is Epoch Marked Simple Binary File. Also, known as Epoch Marked Raw. Export to this format is only available in Net Station 3.0, through the File Export tool of the Waveform Tools. If you need to share Net Station data with BESA, and you don’t have access to this tool, please contact EGI Support ([mailto:support@egi.com) support@egi.com)].

The details vary, depending on whether you are exporting unprocessed data, or ERP data. Each of these cases is discussed below:

== Exporting Unprocessed Data ==

=== Segmentation Markup ===

This section assumes you are familiar with Net Station Segmentation, and the structure of a simple standard/target experiment.

Net Station events contain key lists, in other words, mini databases. Using a simple standard/target experiment as an example, in Net Station all stimulii events might be named “stim.” The distinction between standards and targets can’t be determined from the name of the event. It can only be determined from the key list in the events. In most programs, including BESA, events only have names. They don’t have key lists.

To make the jump from key-list events to non-keylist events, you must use Net Station’s segmentation markup. Segmentation markup adds events to the recording that BESA can use. To use segmentation markup, create a segmentation specification, and check the “Mark Up File” checkbox in the segmentation specification editor. When you run segmentation using this specification, instead of segmenting the file, new events will be added for BESA.

For example, if all your standard and target stimulii are named “stim”, you would create a segmentation specification just as you would for segmenting this file into standard and target categories. Then, if you check the “Mark Up File” checkbox, the specification will cause new events to be added to the file instead of segmentation. Then, you can add events called “stnd” for standard, and “targ” for target.

Note: Although Net Station allows you to add markup events with spaces in the names, it might cause unpredictable results in BESA. Also, Net Station generates the event names automatically, but you can modify them. Sometimes the automatically generated ones contain spaces. Simply edit them, for example, replace thespaces with underscore characters.

The objective is to be able to do segmentation in BESA. So, before exporting to BESA, use segmentation markup to add all the events you might want to use in BESA. Although a simple standard/target experiment was used in this example, you can combine the full power of Net Station’s segmentation with the segmentation markup feature.

=== Export ===

As mentioned above, you need to export to the Epoch Marked Simple Binary File format using the File Export tool. The following explains the options to use:

Since this data hasn’t been rereferenced, do not export the reference channel. In other words, leave the “Export Reference Channel” checkbox unchecked.

You have the option of using integer or floating point precision. Each of these options is discussed below.

The advantage of using integer precision is that export is faster, and results in a file that is about half the size of floating point. The disadvantage is that the individual gains and zeros aren’t applied to the data. If your amplifier is in spec, the loss should be negligible. If you choose this option, leave the “Calibrate Data” checkbox unchecked.

The advantage of using floating point precision is that it is much more precise. The disadvantage is that export is slower, and results in a file that is about twice the size of integer. If you choose this option, make sure that you do check the “Calibrate Data” checkbox.

In either case, set the name of the output file to append the extention “.raw”.

=== Opening in BESA ===

After you have generated the .raw file, move it to the BESA PC. You should now be able to read this file with BESA. To do so, in the File Open Dialog Box, set the “Files of type” dropdown list to “EGI Formats(*.raw…”.

If you do this, BESA will read all the events in the file, and assign trigger numbers to them (except the following, which are meaningless to BESA: CELL, SESS, bgin and TRSP).

Optionally, you can control which events are read by BESA by creating a .trig file. A .trig file is a tab delimited file that contains one line for each event type that you want BESA to read. Each line consists of the name of the event, followed by a tab character, followed by a number between 1 and <255? 256? 65535? 65536?>. The following is an example of a .trig file:

stnd 1

targ 2

resp 128

You might want to use a .trig file if:

* your data has a large number of events, and you don’t need most of them in BESA, or,
* you want to include events with any of these names: CELL, SESS, bgin and TRSP.

To use a .trig file, just make sure that the file is in the same directory as your data file when you open the data file. In addition, the .trig file must be named either “detault.trig”, or <your data file name>.trig (eg “subject1.trig”).

=== Loading Sensor Coordinates ===

After you have opened the file, you must load the sensor coordinate files (File->”Head Surface Points and Sensors”->”Load Coordinate Files”. If want to use average sensor position files (as opposed to files individually digitized for your subject), use the files in “C:\Besa\Examples\Xtras\EEG Binary Formats\EGI” directory.

If you have 256 channel data, use GSN256andRef.ela, and GSN257.sfp.

If you have 128 channel data, use GSN128andRef.ela, and GSN129.sfp.

If you have 64 channel data v1, use GSN64andRef.ela, and GSN65v1_0.sfp.

If you have 64 channel data v2, use GSN64andRef.ela, and GSN65v2_0.sfp.

You are now ready to do your ERP derivation in BESA.

== Exporting Averaged ERP Data ==

=== Export ===

If you have derived your ERP in Net Station, and wish to export it to BESA for source localization, once again, use the File Export tool, exporting in the Epoch Marked Simple Binary File format. The following explains the options to use:

(This explanation assumes that the data has been rereferenced during the ERP derivation process.)

Since this data has been rereferenced, you should export the reference channel. In other words, check the “Export Reference Channel” checkbox.

For averaged data, you need to export using floating point precision. Since the data has been calibrated during the ERP derivation process, it doesn’t matter what you do with the “Calibrate Data” checkbox. Set the name of the output file to append the extention “.raw”.

When exporting averaged ERP data (or any Net Station data that has been categorized, for example segmented data), Net Station generates an additional file: <your file name>.epoc. This file contains the names of the conditions for each epoch in the data.

=== Opening in BESA ===

After you have generated the .raw file, move it, and the .epoc file, to the BESA PC, keeping both files in the same directory. You should now be able to read this file with BESA. To do so, in the File Open Dialog Box, set the “Files of type” dropdown list to “EGI Formats(*.raw…”.

=== Loading Sensor Coordinates ===

After you have opened the file, you must load the sensor coordinate files (File->”Head Surface Points and Sensors”->”Load Coordinate Files”. If want to use average sensor position files (as opposed to files individually digitized for your subject), use the files in “C:\Besa\Examples\Xtras\EEG Binary Formats\EGI” directory.

If you have 256 channel data, use GSN257.ela, and GSN257.sfp.

If you have 128 channel data, use GSN129.ela, and GSN129.sfp.

If you have 64 channel data v1, use GSN65.ela, and GSN65v1_0.sfp.

If you have 64 channel data v2, use GSN65.ela, and GSN65v2_0.sfp.

You are now ready to do source analysis in BESA.

[[Category:Setup]] [[Category:Data Import/Export]]

Using BESA to correct blink and EKG artifacts in MEG data

2021-02-02T11:26:08Z

Abinash: /* Sending the data to Source Analysis */

{{BESAInfobox
|title = Module information
|module = BESA Research Standard or higher
|version = 6.1 or higher
}}

= Using BESA to correct blink and EKG artifacts in MEG data =

Eyeblinks and EKG cause large artifact signals in the magnetometer channels. The artifact correction facilities of BESA can correct these artifacts quite well. The procedure is quite simple for blinks but more complex for EKG. The following text outlines the procedures and current limitations of BESA for artifact correction.

The principles of the artifact correction procedure are described in ''Berg, P., Scherg, M. (1994) A multiple source approach to the correction of eye artifacts. Electroenceph. clin. Neurophysiol, 90: 229-241''.

In summary, the following steps are required:

* Use pattern search and average to identify the latencies of blink/EKG signals in the raw data. Pattern search works best if you have recorded a vertical EOG and EKG with the MEG data, but it will also work on selected MEG channels, using the appropriate filters.
* A spatial PCA is performed on the average to identify the main topographies/components of the artifact signal. For blinks, only one topography is required. For EKG, two or three topographies may be required.
* The topographies/components are combined into a coefficient file (''*.atf''). Using the '''Artifact''' Menu, the ''atf'' file can be loaded and correction switched on. Contrary to the warning message displayed by the ERP module, averaging can be performed using artifact corrected data.
* When the average is loaded into the Source Analysis module, the artifact coefficients (saved in the average file) need to be activated. They will then be incorporated into source modelling using subspace projection (SSP – see also papers by Uusitalo et al.). In this case, SSP is equivalent to the “optimized correction method” described in Berg & Scherg (1994).

== Pattern search for blinks and EKG ==

=== Eyeblinks ===

# Select filters 0.5 – 8 Hz ('''Filters/Edit Filter Settings…'''). Make sure the low cutoff filter type is '''Forward'''! (This is to ensure that no contribution from the blink topography bleeds back into the baseline time interval).
# View Polygraphic signals only (press the '''Pgr''' button at the top right of the BESA window), so that the vertical EOG channel is displayed
# Define the search block from –100 ms to +400 ms ('''Edit/Default Block Epoch…''')
# Select Pattern Search ('''Search/Pattern''')
# Select Search Query ('''Search/Query''')
# Select Buffer 1 for averaging ('''Tags/Pattern 1''')
# Identify a clear blink signal on the vertical EOG channel. Right-click at the '''onset''' of the blink, and select '''Default Block''' in the dropdown menu. The marked block should look something like this: [[File:EKG_artifacts_in_MEG_data__(1).png|155x101px]]
# Click once on the VEOG channel label, so that a rightward arrow is displayed (ignore the correlation window that opens on the right): [[File:EKG_artifacts_in_MEG_data__(2).png|134x72px]]
# Press the '''SAW''' button (Search/Average/Write). BESA will start scanning through the file, and it will stop at each occurrence of a blink. Press “Yes” to accept. “No” to reject, or “Stop asking” to let BESA accept everything automatically. Save the result to a file name of your choice (e.g. ''name_artifact.fsg''), labelling the segment, e.g. “blink”.

=== EKG ===

# In contrast to blink averaging we use two steps: first, filters are set to enhance the EKG for pattern search. Second, the filters are opened up, and the average is repeated.
# Select filters 5-20 Hz. This should generate a fairly clear signal on the EKG.
# Set the default block epoch so that the R-wave and the T-wave are well inside the epoch. The setting used for blinks may be OK, but you may need to extend the post-cursor interval, e.g. from 400 to 500 ms.
# Proceed as with blinks, but selecting Buffer 2 for averaging ('''Tags/Pattern 2'''). Mark a block around the onset of an R-wave. The marked block should look something like this: [[File:EKG_artifacts_in_MEG_data__(3).png|129x89px]]
# Save the average in the same file as the averaged blinks, labelling the segment, e.g. “EKG”.
# Select filters 1-30 Hz. Select '''Search/Tagged Events''', and press '''SAW'''. This repeats the average using the tags that were identified during the first step. Opening up the filters ensures that the average includes more of the EKG signal.

=== What to do if there is no VEOG or EKG channel ===

The procedure is similar to the above, but you need to identify a MEG channel that displays the blink or EKG waveform clearly. You may need to experiment with filter settings to make the artifact pattern clearer (the filter settings described above are not fixed rules – you may find that other settings work better for pattern search). You may find the “Create Triggers from EMG/EEG” tool helpful for detecting EKG ('''ERP/Create Triggers from EMG/EEG…'''). See the BESA help file (tutorial on creating triggers).

== Spatial PCA and the *.atf file ==

Open the file in which you saved the averages (e.g. ''name_artifact.fsg''). Make sure that prestimulus baseline correction is switched on ('''Filters/Use Prestimulus Baseline''').

=== Blinks ===

# Mark the whole blink epoch: Right-click onto the epoch, and select '''Whole Segment'''.
# Select '''Artifact/Assign/Blink'''. The spatial PCA is computed, and the first spatial component is assigned to describe the blink. You may check if the correction works by selecting '''Artifact/Correct'''.
# The coefficients are saved automatically to a file with the same basename as the average, and the extension ''“.atf''”.

=== EKG ===

EKG coefficients are corrected analogously to blinks. A difference is that the topographic distribution of the EKG over the MEG sensors is more complex than that of blinks. It changes over time. The reasons for this are unclear, and may be due to movement of the heart (and its equivalent dipoles) over time, but also to ballistic effects: movement of the head due to blood flow.

Since topographic distribution changes over time, more than one component is required for correction. We choose the number of components in the Artifact Select Dialog Box empirically: As a rule of thumb, if a component explains more than 5-10% of the variance of the averaged EKG signal, the component is included. Note that the number of components you select can also be changed when the coefficients are applied to the raw data.

== Correcting the raw data ==

* Switch back to the raw data file, and load the ''*.atf'' file you have created ('''Artifact/Load…''').
* Optionally, check that the artifact correction channels are visible (Artifact/View)
* Switch on artifact correction (Artifact/Correct).
* The figure on the next page shows the result of correction of channels A75-A148 on a three-second interval containing both EKG and eye activity. The blue label “1” marks the onset of a blink found during pattern search. The red “2” shows the onset of R-waves found during pattern search.
* Note that correction is quite good, but it is not perfect. In particular, there is some residual eye activity, e.g. around channels A91, A113, A131.

{|
! '''uncorrected'''
! '''corrected'''
|-
| [[File:EKG_artifacts_in_MEG_data__(4).png|57x57px]][[File:EKG_artifacts_in_MEG_data__(5).png|272x802px]]
| [[File:EKG_artifacts_in_MEG_data__(6).png|273x801px]]
|}

== Averaging the raw data ==

You can leave correction on during data averaging. When you press the Average button, a warning dialog will appear:

[[File:EKG_artifacts_in_MEG_data__(7).png|539x124px]]

You may select either option. Because of the recent installation of subspace projection (SSP) in the Source Module, the “distorted topographies” in the warning are no longer an issue for source analysis, provided SSP is switched on when the data are sent to the Source Module. The decision has consequences a) if you intend to analyze data waveform amplitudes and/or latencies, and b) if you intend to export the averages for analysis with other software.

==== Option “Yes” – turn off artifact correction ====

The averaged data will include EKG and eye artifacts, but these artifacts will not cause epochs to be rejected. The same number of epochs will be included in the average whether or not “Yes” or “No” is chosen.

You may load the correction coefficients (''*.atf'') for the average, and switch on artifact correction.

==== Option “No” – leave artifact correction on ====

The averaged data will be corrected. Each epoch is corrected before being included in the average.

==== Artifact options: which correction model? ====

The result of the correction on the raw data or the averaged data can be slightly different. The effects of correction will also vary, depending on the settings in '''Artifact/Options'''. These differences can be considered as consequences of variations in the “surrogate” or “adaptive” model of brain activity concurrent with the artifact activity (cf. Berg & Scherg 1994). These differences lead to changes in the estimate of the amounts of artifact activity to be removed by correction. If you intend to use the data waveforms outside BESA, and if you don’t use SSP with the artifact coefficients, then the settings in '''Artifact/Options''' become important. In current versions of BESA, these settings are based on EEG amplitude levels. In Konstanz, we generally use the values shown on the right. Note that these values are '''irrelevant''' if we use SSP in Source Analysis.

[[File:EKG_artifacts_in_MEG_data__(8).png|353x231px]]

== Sending the data to Source Analysis ==

When the average is generated, the correction coefficients are saved in the ''*.fsg'' file. Before you send the data to the Source Module, these coefficients must be '''activated'''.

* If you averaged the corrected data, coefficients are already activated. This should be apparent from the red “corrected” displayed above the channel labels.
* If you averaged the uncorrected data, load the saved ''*.atf'' file ('''Artifact/Load…'''), and switch on correction ('''Artifact/Correct''').

Then mark a time range and send the data to Source Analysis. At the right of the status bar, the text '''ART''' indicates that the artifact components are used in SSP.

[[File:EKG_artifacts_in_MEG_data__(9).png|143x158px]]

'''Alternatively, if you averaged the uncorrected data, load the average to Source Analysis, and then load the artifact coefficients as part of the dipole model (load or append solution, and use the dropdown list in the File Open box to select ''*.atf'' instead of ''*.bsa''). This approach has the advantage that the source waveforms of the spatial components show the contribution of eye and EKG activity to the model.'''

This implicit application of SSP during Source Analysis is mathematically equivalent to the “optimizing” correction method (cf. Berg & Scherg 1994): the topographies of the artifacts are implicitly incorporated into any dipole model.

== Limitations of the correction method in BESA ==

=== Bad channels ===

The ''*.atf'' file contains a two-line header with a) the number of channels, and b) the channel labels. If these do not match with the current data file, artifact correction is not possible. Bad channels are marked (with an asterisk next to the label), and the corresponding coefficient is set to zero. The irritating, but logical, the consequence is that if a channel was excluded (defined as “bad”) when the coefficients were generated, it is not possible to make the channel “good” again.

The solution is to regenerate the ''*.atf'' file, making sure the same bad channels are defined in the averaged artifact file as the to-be-corrected raw or average data file. You do not need to regenerate the artifact averages.

EKG correction is difficult because the topographic distribution of EKG signals is close to some MEG distributions: for instance, we sometimes observe a considerable reduction in alpha amplitudes with EKG correction. For event-related averaging, an EKG correction is often unnecessary, because the EKG is not synchronized with the stimulus.

[[Category:Data Import/Export]] [[Category:Preprocessing]] [[Category:Source Analysis]]