BCI2000 Wiki - User contributions [en]

MARIO Technical Documentation

2006-12-15T20:39:54Z

Fcincotti: MarioTechnicalDocs moved to MARIO Technical Documentation: more descriptive title

==MARIO architecture==
MARIO is an off-line analysis application developed in MATLAB 7.0.2. It’s now modular, object-oriented and can be easily integrated with any other software for data analysis and visualization.
It can be used in Mu and P300 analysis and allows two kind of use: users can simply fill the forms of a graphical interface making any choice with a click of its mouse, run a ready-made script or, at least, write up their own scripts according to their needs.
This set of interfaces allows a wide range of possibilities for a wide range of different analysis.

Internally, the application is composed by 6 main functional modules connected each one in cascade as in the list below:

*Data import;
*Signal Conditioning;
*Feature Extraction;
*Spectral Extimation;
*Statistical Analysis;
*Visualization.

[[Image:arch_blocks.jpg]]

All these modules are hidden in the graphical user interface but they can be distinguished in the batch scripts. Each one of them can be easily replaced with an improved version, a custom version or a different analysis.

[[Image:Graph.png|thumb|left|Graph of modules]]
Here you can see a simplified version of the functions graph and of their relationships (click to enlarge). 

==Data Import Module==

Any script must have a first module to load data user wants to analyze.
There are 3 main kind of file containing different groups of information:

*Data files (.dat/.mat);
*Montage files (.mmf);
*External Parameter files (.prm) – it’s optional.

The data files contain all the data of the BCI session (Mu or P300).
These data are saved in different files, one for each run, containing 29 trials.
Internally any file is divided in two main parts: the first one (file header) includes all parameters set by the operator during the on-line experimentation; the second one contains the EEG signal recorded by the whole set of electrodes on the EEG cap.
A special function allows at least to load data from a Matlab file (.mat).

The montage file stores informations about the electrodes position on the scalp. It can be
drawn up writing in different sections divided by labels:

#a synthetic name;
#the channel labels;
#a valid channels list;
#the laplacian grid;
#the 3-dimensional spatial coordinates of all the electrodes (this section is optional).

These informations are divided by labels and can be written in the Montage file without a predefined order.

At least, user can import data from an additional data file, a parameters file, that can be used if he want to replace one or more parameters from the BCI2000 ones. In this chance is enough to copy and paste in a new prm file the header string selected, changing its value.

This module is clearly the same for Mu and P300 Analysis.

==Data Conditioning Module==

The MARIO v.2.0 Data Conditioning module allows users to select between a wide range of spatial filters such as to include custom filter in user data analysis. So the operator can identify which channels or set of channels can give better results at the end of the statistical analysis.

For a Mu analysis user can select between four different spatial filter algorithms:

*RAW;
*CAR (Common Average Reference);
*SMALL LAP;
*LARGE LAP.

The first one (RAW) is the choice not to use a filter and analyze raw recorded data. Every other selection agrees with the choice to employ any spatial filter. An user defined analysis will be available on further versions of MARIO.

The Data Conditioning module also allows the user to compile/modify a list of valid channels which any analysis will be conduced on.

P300 Analysis can now use only two of the above spatial filters: the RAW filter and the CAR one. Any other selection will report an unhandled error.

==Feature Extraction Module==

Feature extraction is one of the most important stages of elaboration; it affects any further analysis.

In a Mu rhythm analysis, any feature can be obtained arranging some of the 12 BCI2000 states.
User can now make a choice between two predefined analysis, a simple Mu analysis or an Extended version of the same. The first analysis considers any sample recorded between the cursor appearance on the screen and the end of the trial (when the cursor reaches the right side of the screen).
The MuExteded analysis instead considers any sample recorded since the target appearance (during the first subset of data subject didn’t have any feedback) till the end of trial.
In both choices, the statistical analysis will be conduced between two classes of data: the EEG activity recorded while moving up the cursor (target UP) versus the EEG activity recorded while moving down the cursor (target DOWN).
Anyone of these choice will produce different R2 values between the corresponding features of the two classes

For a P300 Analysis the classes compared are only two and automatically set as frequent events and rare events.

==Spectral Extimation Module ''(just for Mu rhythm analysis)''==

During this step, the program evaluates the spectrum of recorded data; any further analysis will be done on it.
To do that, EEG signal is divided into equal length epoch (that can be distinct or overlapped of a percentage of overlap that user can set by Graphical User Interface or script) and a spectrum value is evaluated for anyone of these.

At the end of this process, a 3 dimensional matrix (bin × channel × epoch) joined with the one (channel × sample) compiled during a BCI2000 recording session and read by the data import module will be produced.

The algorithm employed to estimate the signal spectrum is the MEM (the same used on-line by BCI2000).

Apart from the percentage of overlap MARIO allows the user to modify the values of:

#Sampling frequency of recorded data;
#Spatial resolution (delta);
#Detrending order (Mean or Linear);
#AR model order;
#Low pass filter frequency;
#High pass filter frequency;
#Filter bandwidth;
#Epoch length;
#Overlap percentage.

MARIO v2.0 also computes a virtual states matrix strictly joined with signal one and derived as a arrangement of the BCI2000 states. These states label spectrum samples as valid or not and as belonging to one class or another.

Since that, every further analysis on BCI2000 data can be done.

==Statistical Analysis Module==

At least, a statistical analysis (at present the R2) is employed to distinguish between the class of a BCI2000 task in any trial.

MARIO uses a module that computes the R2 value between two classes that can be TargetUP and TargetDOWN for a Mu rhythm analysis, such as frequent and rare events for a P300 analysis. These data are taken from the spectra matrix (Mu analysis) or from the samples one (P300 analysis) and the regressor vector is yield from BCI2000 states.

At the end of this analysis, the real index (in a range between -1 and 1) produced is the R2 value multiplied by R2 sign. If the R2 value is near 1 it means there is an high separability between classes and high performances. If instead its value is near 0, it’s difficult to distinguish a class from another, and it means low performances.

==Visualization Module==

Mario offers a wide set of visualization graphs that can be combined to have a complete visualization of produced data.
For a Mu rhythm analysis user can request to visualize:

#a trajectory plot shows the cursor position for any sample in a trial BCI2000 as user saw it on-line;
#a matrix (channel × bin) shows as a colour tint the R2 value of any feature. A colorbar shows the colour range between -1 and 1;
#Another panel shows a detail of the previous matrix. The upper topographic plot shows the R2 value for any channel in the selected bin of frequencies; the lower one is the spectrum of the selected channel for all the frequencies.

For a P300 analysis user can choose between:

#A R2 matrix
#An amplitude waveform graph;
#A topographic plot;
#An ERP response graph;
#A string prediction form.

All these result visualizations can be easily included in any of user scripts for custom analysis.

Mu Rhythm Off-line Analysis Tutorial

2006-12-15T20:38:54Z

Fcincotti: MuTutorial moved to Mu Rhythm Off-line Analysis Tutorial: more descriptive title

== Starting an analysis session ==

Every recording session has its own history. It is very difficult to say in advance what might happen during the recording. So we will assume that everything was perfect (the subject collaborated, no channel went lost, etc); later on we will consider the main causes of contamination, how to recognize it and what to do.

If the recording session run smoothly, in the folder ''\TestData\Data\Mu'' you should have now two files named ''ALFAS006R01.dat'' and ''ALFAS006R02.dat'', corresponding to two of the eight runs usually recorded, respectively.

Before you start the analysis you should locate on your hard disk the correct montage file. This is a file that describes the list of channels that were acquired. In this tutorial we will use ''Complete_Montage(suggested choice).mmf'', which is located in the folder ''\TestData\Montage''. If you need to edit the *.mmf file, check its data format.
< the of performances optimize that parameters try will we then online; performed BCI2000 analyses same off-line replicate to first>

== Opening files with Mario ==

After having run mario.exe, press "Select Data Files".

[[Image:Mu Rhy5.jpg]]

A dialog window will ask you to select the dat files. You can either select a single data file, or select multiple files. This time, we will select all files in the dataset.

A green box will surround the Raw Data box in the main window.

As an optional (but recommended) operation, push the LOAD MONTAGE button and choose the mmf file. This will allow you to see the labels of each channel the following steps, and to allow to apply spatial filters that depend on the electrode position.

At least you can load an additional parameters file according to different choices from those carried out during the experimentation.

At this point, you can check that Mu is selected in the Analysis menu (indicating that a Mu dataset has been recognized) and push the LOAD DATA button to confirm your choices. This will enable the EDIT CHANNEL LIST button you can use to select the channels you want to include in your analysis.

== Selecting Channels ==

Pushing the the EDIT CHANNEL LIST button, two forms will show you the channels list (valids' and not-valids' one) and an image reassuming valid channels and their location.

Clicking on Add and Remove buttons you can move whichever channel from one list to the other enabling or disabling it.

== Selecting the Spatial Filter ==

Coming back to main window, you can therefore choose which filter to apply for your elaborations, selecting it between the possible supplied solutions.

You can choose between:

:*RAW;
:*CAR;
:*Large Laplacian;
:*Small Laplacian.

Common Average Reference (CAR) will be fine for most the situations.

We hope to release soon an user defined solution for any custom analysis.

== Feature Extraction Analysis ==

The Analysis field in the Feature Extraction panel will appear automatically according to loaded files while the Feature Extractor field shows currently the only possible choice.

You can view/edit analysis details by pushing "Set Analysis Details" and "Set F.E. parameters"

This second form reports all the settings for the parametric (autoregressive) spectral estimation stage. Most of the values are set after the corresponding values used on-line (see BCI2000 setup for Mu). With settings as the ones reported in figure, the analysis software will:

:*data recorded at 200 Hz sampling rate;
:* remove the mean value;
:* sample the spectrum at points starting from 0 Hz to 60 Hz, every 0.2 Hz.;
:* Identify an auroregressive model of order 16;
:* average these values into 2 Hz wide bins;
:* take a 1 s long epoch of data.

You can modify these settings according to your aims. Changing the model order, for instance, brings sometimes to interesting results. Remember though that in the online version, spectral estimation is performed in epochs as short as 200 ms (i.e. 40 samples, at 200 Hz sampling rate), so you should avoid using model order higher than half the samples available in the epoch.
When you are done, remember to confirm your choices by pushing DONE. It will make the program accept changes.

Moreover, a button in the Spectral Extimation frame allows you to revert the values to the original.

Altogether you have to specify:

:* which data (in each trial) you want to take into account. Mu will only use the part of the trial when the cursor is visible, while MuExtended will take into account all the period when the target is visible. To learn more, see section D2Box Application States ;
:* If you have made an artifact rejection (or noted on the run sheet during the acquisition which trials contain artifacts), you can instruct the software not to use them;
:* Finally, you must decide how the software must extract EEG epochs from the continuous data.
The epochs can be partially overlapped. This attenuates the data loss in case the length of a trial is not a multiple of the length of an epoch.

The percentage of overlap can be set both in Mario GUI and in any batch script. It's equal to the value of the ''MU_params.overlapping'' variable and the corresponding GUI field can be found by pressing ''Set Analysis Details'' on MARIO main form.

At this point you can start the analysis by pressing the Evaluate and Plot button.

[[Image:Mu Rhy8.jpg]]

== View results ==

The first figure that appears is the R-square matrix (channels x frequency bins)
=== R-square matrix ===

The r-square matrix highlights the most relevant spectral features for the separation of the two classes of EEG - Cursor Up (target 1) and Cursor Down (target 2).

[[Image:Mu Rhy8.jpg]]

Each row of the matrix is related to a single channel, while a column represents a frequency bin (labeled with its central frequency). The color codes the statistical significance of the difference between the two kind of evoked potentials.

Thus a red color would mean that, on that channel and for that frequency, the "Up" EEG is significantly synchronized with respect to "Down" EEG.

Clicking on a cell of the matrix will open two more windows:

* Power spectral distribution of the selected channel;
* Topographic maps at the selected frequency.

You can choose whether to overwrite or to put the most recently evoked figures beside the previous one. Two sets of waveform/topography figures are available, and are linked to the click of the left, the central or right mouse button.
Left Button will create/overwrite a first figure, Right Button will do the same on a second figure, the Central Button will always open a new plot.

=== Power Spectra and Topographic Plots ===

In the lower panel you can find the spectral density of power for both classes of EEG. Blue line refers to "Up" condition, while Red line to "Down".
We can see that at the vertex the "Down" condition is generally more synchronized than the "Up", with maximal difference in the beta band, consistently with what is shown by the R-square matrix. The proportinality between spectral differences and R-square is anyway rough, since r-square is sensitive to the dispersion (variance) of single trials; thus, small differences between spectra could bring to a high r-square, if they were very reproducible.

The peak around 50 Hz is due to mains disturbance; this also allows to appreciate the leakage introduced by the spectral estimation.

[[Image:Mu_Rhy9.jpg]]

Over the spectral graph, a topografic plot shows the scalp distribution of the r-square.

The color coding is the same as the r-square matrix figure, and values on each channel are interpolated to create a continuous bidimensional map. The higher the number of electrodes, the more accurate is the map. The number of channels shown on the scalp may not coincide with the whole number of electrodes in case of a Surface Laplacian spatial filtering, since in that case the value of the laplacian is not computed on the border channels.
Interpretation of the results

The first step in the preliminary analysis of P300 BCI data is to find the absolute maximum of r-square. This simple statement must be mediated with a proper knowledge of physiological phenomena. In fact, we do not expect any sensorimotor activity at 3 Hz, so if the absolute maximum is at that frequency, you must suspect that it is actually an artifact. The same holds if the spatial localization of the peak is far away from the centro-parietal electrodes.

From a practical point of view, it is not important now to understand the reasons different component that explain the desynchrinization peak on Cz at 17 Hz, as far as we are confident that this component is stable enough to be exploitable during the next session to control the cursor.

The absolute value of R-square is mathematically bound to lie in the interval between 0 and 1. Values above 0.4 allow a rate of missed target in the order of a few percent. Values around 0.1 are promising. Values below 0.03 are possibly due to random fluctuations. All the previous figures are referred to analyses made on 240 trials.
''Beware of artifacts!''

During the acquisition, you should be particularly careful to avoid artifacts. While EOG and blink artifacts are confined to very low frequencies, EMG artifacts are mostly on the beta band and could largely overlap with the frequency band that characterize the mu rhythm.

If contaminated data was acquired, then you have two problems:

:* Realize that EMG is superimposed to data;
:* Distinguish between spectral modulation introduced by EEG and by EMG.

The first task is not as trivial as it might appear. If you did not acquire the data yourself (or even if you did it) you might complete the analysis procedure without giving a single glance to the raw data. So you must be particularly careful when you analyze the R-square maps, and always wonder whether the peak you are seeing might be due to an artifact.

Discriminant features between EEG and EMG are both in the frequency distribution and in the spatial distribution.

EMG that strongly affects the recordings is mostly generated by muscles at the forehead or close to the ears/jaws. Thus their spatial distribution is such that the most responsive channel is one of those at the border of the montage. Of course, due to volume conduction, the effects can be seen even on electrodes on the opposite part of the montage, but they show a degrading pattern.
On the other hand, a peak that shows its maximum on a central channel, can hardly be generated by a muscle or by other non-cephalic source.

The spectrum of EEG is mainly concentrated in the alpha band, with a possible flatter and lower peak in beta. With the exception of the beta peak/plateau, the EEG spectrum decreases almost linearly (if measured in dB) after 12 Hz.
On the other hand, EMG spectrum becomes significant at about 20 Hz and is still very high at the highest frequencies we usually analyze (60 Hz). A spectrum with a pattern more similar to the latter, must induce the suspect that non-EEG activity is present in the data.

==Improving the analysis==

The first cause of an unsuccessful analysis is a poor quality of the recording. For this reason it is highly recommended that, at least for the first experiments, the subject is highly motivated and cooperative. If this is the case, data of low quality are usually present in one or a few runs. And if the experimenter is careful enough, he/she should have noted down the occurrence of strong artifacts on the run sheet.
In this hypothesis, the following step is to repeat an unsatisfactory data analysis after having excluded the (putative) bad runs.
To do this, just go back to the file selection dialog, choose LOAD Data again and load only the runs that you believe are clean. The number of runs should not be too low (as a rule of thumb, the data set should contain at least 100 trials), otherwise the r-square statistical analysis would loose sensitivity.

== Analyzing the Screening ==

The screening experiment is not different from a regular training session, from the point of view of data format. You will have four sets (horizontal movement, horizontal imagination, vertical movement, and vertical imagination) of three runs, containing EEG acquired in two conditions (up and down, or left and right).

Start analyzing the vertical movement execution, and mark a few possible responsive features. The analysis on vertical movement imagination should confirm (though with a lower R-square) those that are actually related to sensorimotor cognitive states.

In the hypothesis that no reliable responsive EEG feature is found, the analysis can be repeated on the horizontal dataset.

If both the vertical and horizontal dataset show responsive features, and these are different, the subject should be trained for some session on the vertical training until he/she decreases the false positive below 10%; at that point the training of the horizontal modulation can begin, with the aim that at a certain point the subject can control both the vertical and the horizontal simultaneously in a two-dimensional task.

==Conclusions==

If you are confident that you have found a significant difference between conditions, that is due to EEG rather than an artifact, and that reflects a cognitive process that is likely to be reproduced (or even enhanced with training) in the next session, well you have reached your goal.
Next time the same subject practices with the D2Box Application, you will have to change the MUD matrix so that it reflects the feature that you just outlined.

==Troubleshooting==

Some OpenGL drivers may sometimes show defective figures like the following:

[[Image:Defective.jpg]]

Matlab customers can go round this problem using this simple procedure:
:* Select the defective figure window;
:* Go to the Matlab Command Window;
:* Execute one of the following command line:
:**set(gcf, 'Renderer', 'Painters');
:**set(gcf, 'Renderer', 'zbuffer').

The figure will be plot using a different renderer (Painters or zBuffer).

P300 Off-line Analysis Tutorial

2006-12-15T20:37:23Z

Fcincotti: P3Tutorial moved to P300 Off-line Analysis Tutorial: more descriptive title

File:P300 8.jpg

2006-12-15T20:35:52Z

Fcincotti:

File:P300 7.jpg

2006-12-15T20:35:42Z

Fcincotti:

File:P300 6.jpg

2006-12-15T20:35:32Z

Fcincotti:

File:P300 5.jpg

2006-12-15T20:35:21Z

Fcincotti:

File:P300 4.jpg

2006-12-15T20:35:09Z

Fcincotti:

File:P300 3.jpg

2006-12-15T20:34:58Z

Fcincotti:

File:P300 2.jpg

2006-12-15T20:34:43Z

Fcincotti:

File:P300 1.jpg

2006-12-15T20:34:28Z

Fcincotti:

File:Defective.jpg

2006-12-15T20:31:04Z

Fcincotti:

File:Mu Rhy9.jpg

2006-12-15T20:30:48Z

Fcincotti:

File:Mu Rhy8.jpg

2006-12-15T20:30:11Z

Fcincotti:

File:Mu Rhy5.jpg

2006-12-15T20:29:48Z

Fcincotti:

P300 Off-line Analysis Tutorial

2006-12-15T20:25:26Z

Fcincotti:

Mu Rhythm Off-line Analysis Tutorial

2006-12-15T20:24:55Z

Fcincotti:

MARIO Technical Documentation

2006-12-15T20:19:21Z

Fcincotti:

File:Graph.png

2006-12-15T20:08:18Z

Fcincotti:

File:Arch blocks.jpg

2006-12-15T20:07:52Z

Fcincotti: