Overview
--------
This is the "Matching Pennies" dataset. It was collected as part of a small
scale replication project targeting the following reference:

Matthias Schultze-Kraft et al.
"Predicting Motor Intentions with Closed-Loop Brain-Computer Interfaces".
In: Springer Briefs in Electrical and Computer Engineering.
Springer International Publishing, 2017, pp. 79–90.

In brief, it contains EEG data for 7 subjects raising either their left or right hand,
thus giving rise to a lateralized readiness potential as measured with the EEG.
For details, see the `Details about the experiment` section.


Citing this dataset
-------------------
Please cite as follows:

Appelhoff, S., Sauer, D., & Gill, S. S. (2018, July 22).
Matching Pennies: A Brain Computer Interface Implementation Dataset.

For more information, see the `dataset_description.json` file.


License
-------
This eeg_matchingpennies dataset is made available under the Open Database
License: See the LICENSE file. A human readable information can be found at:

https://opendatacommons.org/licenses/odbl/summary/

Any rights in individual contents of the database are licensed under the
Database Contents License: http://opendatacommons.org/licenses/dbcl/1.0/


Format
------
The dataset is formatted according to the Brain Imaging Data Structure. See the
`dataset_description.json` file for the specific version used.

Generally, you can find data in the .tsv files and descriptions in the
accompanying .json files.

An important BIDS definition to consider is the "Inheritance Principle", which
is described in the BIDS specification under the following link:

https://bids-specification.rtfd.io/en/stable/02-common-principles.html#the-inheritance-principle

The section states that:

> Any metadata file (​.json​,​.bvec​,​.tsv​, etc.) may be defined at any directory
level. The values from the top level are inherited by all lower levels unless
they are overridden by a file at the lower level.


Details about the experiment
----------------------------
For a detailed description of the task, see Schultze-Kraft et al. (2017)
and the supplied `task-matchingpennies_eeg.json` file.

Subjects 1 to 4 participated in the pilot testing only. Their data are not
included in this dataset.

In the matching pennies experiment, EEG data was evaluated in a closed-loop
BCI online setup. Due to an inherent latency of the system, the data used in
the online analysis does not necessarily coincide with the offline data marked
through EEG triggers. Therefore, after each trial-wise online analysis, the
used data was saved separately as an "online chunk". Based on the online chunks
of data, it was possible to calculate a latency of each trial with respect to
the time difference between when an event happened at the electrode level and
when it arrived in digitized format at the classification function. These
latencies were calculated by sliding the online chunk of data across the data
recording until a perfect match was found. The index of this perfect match is
then compared to the timepoint of the event trigger and that difference
constitutes the latency. The values are included in the events.tsv files for
each subject.

The original data was recorded in `.xdf` format using labstreaminglayer
(https://github.com/sccn/labstreaminglayer). It is stored in the `/sourcedata`
directory. To comply with the BIDS format, the .xdf format was converted to
brainvision format (see the `.eeg` file for binary eeg data, the `.vhdr` as a
text header filer containing meta data, and the `.vmrk` as a text file storing
the eeg markers).

Note that in the experiment, the only EEG TTL triggers that were recorded are related
to the button release of the left (=value 1) or right (=value 2) hand.
The onset of the feedback stimulus (drawing ofleft or right hand shown on the screen)
was not recorded, however it can be crudely estimated to be around 50ms + ~10ms + ~8ms,
where 50ms were a hardcoded break before getting the online data from LSL, ~10ms was
the time to get a prediction from the BCI classifier, but this varied around 10ms,
and finally the ~8ms at the end come from the uncertainty of the refresh rate of the
screen (60fps = 1 screen every 16.66666ms)