For the 'end user' of the BBCI online system, essentially two operations are required: calibration of the system and online application of the system. These operations are performed by the functions bbci_calibration and bbci_apply respectively. After calibration, the calibrated system can be saved via bbci_save. 

% Define in 'bbci' the type of calibration and calibration specific parameters
bbci= struct('calibrate');
bbci.calibrate.fcn= @bbci_calibrate_csp;
bbci.calibrate.settings.classes= {'left', 'right'};

% Run calibration
[bbci, data]= bbci_calibrate(bbci);

% optionally specify in 'bbci' application specific parameters
feedback_arrow.receiver= 'matlab';
feedback_arrow.fcn= @bbci_feedback_cursor;

% saving the classifier is not necessary for operation, but advisable
% optinally feature vectors and figures of the calibration can be saved
bbci_save(bbci, data);

[bbci, data]= bbci_apply(bbci);

* Defining the calibration file (fields of bbci.calibrate):

.folder

CHAR, default TODAY_DIR (global variable)

.file

CHAR, no default: must be specified

.marker_fcn

FUNC HANDLE, default []

.marker_param

CELL, default {}

.montage_fcn

FUNC HANDLE, default @getElectrodePositions

.montage_param

CELL, deafult {}

* Defining the type of calibration and calibration specific parameters

.fcn

FUNC HANDLE, no default: must be specified; this function should have the prefix bbci_calbrate_ and is called by the wrapper function bbci_calibrate

.settings

STRUCT defining the calibration specific parameters. Which parameters can be specified and their meaning should be described in the help of the specific calibration function. There is no general format.

* Defining whether and how information should be logged

.log

STRUCT with fields output (default 'screen&file'), folder (default TODAY_DIR), file (default 'bbci_calibrate_log'), and force_overwriting (deafult 0)

* Defining what and how calibration data should be saved

.save

'.file

CHAR, default 'bbci_classifier'

.folder

CHAR, default TODAY_DIR

.overwrite

BOOL, default 1. If 0, numbers are appended

.raw_data

BOOL, default 0. If 1, also calibration source data (fields cnt, mrk, and mnt) are stored. Otherwise only the other fields of data are stored

.data

CHAR, default separately

.figures

BOOL, default 0. If true, Matlab figures generated by calibration are saved in a subfolder figures

.figures_spec

CELL, default {'paperSize','auto'}: specification for saving the figures: this is passed to the function printFigure

Interactively Optimize Calibration Parameters

For rigorous experimental studies it is advisable to have the calibration completely deterministic, i.e., without having the experimenter tweaking parameters to the calibration data. (However, this view point is debateble.) Anyway, for exploratory studies, interactive optimization of the calibration process to the data of each participant is desirable. In the BBCI Online System this can be done by iterating the specification of calibration parameters in bbci.calibrate.settings and rerunning bbci_calibrate. In order to speed up and facilitate this process, some tricks are good to know (which also have to be taken into account when writing new calibrate functions.

To avoid re-loading the calibration data each time, you can provide the data structure, which is obtained as second output argument of bbci_calibrate, as further input argument to bbci_calibrate: 

% Run calibration for the first time
[bbci, data]= bbci_calibrate(bbci);

% Change some calibration specific settings, e.g.,
bbci.calibrate.settings.band= [10 13];

% Run calibration again. Calibration data is stored in the variable data,
% so it needs not to be reloaded.
[bbci, data]= bbci_calibrate(bbci, data);

More over, the calibration-specific function bbci_calibrate_* might be implemented such that some processing steps re be reused (without the user having to take care about that). For example, it might not be required to run artifact rejection again in subsequent runs (unless parameters that would affect artifact rejection are modified).

Another mechanism (which also has to be taken into account by programmers of new calibrate functions) lets users take over selections that might have been performed by a calibration run: All results of parameter selections during calibration should be store in data.result. In particular, the selected values for parameters that have been declared as 'auto' in bbci.calibrate.settings are stored in data.result in the same field. For example, 

% This example assumes bbci.calibrate.fcn= @bbci_calibrate_csp
% The following is default anyway, but made explicit here for demonstration
>> bbci.calibrate.settings.band= 'auto';
>> [bbci, data]= bbci_calibrate(bbci);
% The result of the selection of the frequency band is stored here
>> data.result.band
ans =
    9    13
% Still, the settings in bbci are unchanged (in contrast to the old system)
>> bbci.calibrate.settings.band
ans =
auto
% For inspecting and changing bbci.calibrate.setting, the function
% bbci_calibrate_set can be used, or the short hand bc_set.
% Checking values (same as above)
>> bc_set(bbci, 'band')
The value of 'band' is:
'auto'
% Setting values explicitly:
>> bc_set(bbci, 'band', [10 13])
>> bc_set(bbci, 'band')
The value of 'band' is:
[10,13]
% Providing data as further input, selections of the calibration can be copied:
>> bbci= bc_set(bbci, data, 'band');
>> bc_set(bbci, 'band')
The value of 'band' is:
[9,13]
% The function allows copying several parameters at the same time
>> bbci= bc_set(bbci, data, 'band', 'ival', 'classes');
% You can revert to the original value of a parameter by bbci_calibrate_reset
>> bbci= bbci_calibrate_reset(bbci, 'band');
>> bc_set(bbci, 'band')
The value of 'band' is:
'auto'

Implementing Calibration Functions

The function bbci_calibrate is just a wrapper that provides some basic functionality, like loading the calibration data. The calibration of the BBCI Online system is performed by calibration specific subfunctions, which should be named bbci_calibrate_XYZ with 'XYZ' being a specific and compact description of the type of calibration. The calling convention for the bbci_calibrate_* functions is described in online/calibration/Contents.m. Calibration functions that are of 'general interest' should be stored in this folder. (Please, add a short description in the Contents.m file.) More specilized calibration functions should be filed under bbci/acquisition/setups/*.

 [BBCI, DATA]= bbci_calibate_XYZ(BBCI, DATA) 

The objective of calibration functions is to define the online processing in the variable bbci, based on the calibration data given in the fields cnt, mrk, and mnt of data. Calibration specific parameters that can be selected by the user are provided in bbci.calibrate.settings. This is the only (sub-) field of the variable bbci that should be read by the calibration function. Otherwise, the bbci variable is only used to store information of specific online processing.

The field data.isnew indicates whether calibration data is new (loaded for the first time or reloaded) or whether it is the same as before. In the latter case, some steps of calibration might be omitted. For example, it might not be required to run artifact rejection again in subsequent runs (unless parameters that would affect artifact rejection are modified in bbci.calibrate.settings. In order to able to check which settings have been changed since the last run, data.previous_settings holds the settings of the previous calibration run. (This functionality is provided by bbci_calibrate.)

The result of the selection of parameters should be stored in data.result. This should be warranted, at least of the parameters that can be unspecified in bbci.calibrate.settings (typically by not defining them, or be defining them as 'auto'). But other results of the calibration process (e.g., list of rejected trials) should also be stored in data.result for documentation.

Finally, data.figure_handles should hold the handles of all Matlab figures that should be stored by bbci_save. If this field is not defined, bbci_save will save all Matlab figures (if saving figures is requested by bbci.calibrate.save.figures).