== A Guide for Implementing new 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`).