BrailleBCI/README

# Braille BCI experiment EEG experiment

## Brief experiment description
10 blind and 10 sighted subjects were using tactile P300 BCI, implemented with Alva 640 comfort Braille display.

4 fingers on each hand were placed on separate Braille cells, serving as stimuli. Each stimulus was activated 10 times in random order. Participant's task was to count activations of target cell.

For blind subjects, Braille proficiency was assessed with the reading test before the experiment.
The experiment included BCI sessions with large (8 dots) and small (1 dot) stimuli.

The present analysis is focused on the comparison of BCI performance for large and small stimuli in blind and sighted individuals.

For more details, see our preprint at ############

Complete analysis is available at https://github.com/eegdude/erp_analysis/tree/brlbci
The scripts are designed to work with contents of sourcedata folder

## Sourcedata description

Per-record markup is provided in sourcedata. Per-epoch markup is calculated at preprocessing step.
Various stimuli parameters for each epoch are descriped in events.tsv files

### Per-record markup

|column name |description
|---|---|
|  user|  user id
|  folder|  folder with a record inside the user folder
|  reg|  BCI mode. 'large' for large stimuli, 'small' for small |  stimuli 
|  targets|  list of target stimuli for all learning and stimuli selection cycles
|  fingers|  which finger corresponds to specific stimuli code.<br> right hand  0 - pinky, 1 - ring, 2 - middle, 3 - index<br>left hand  4 - index, 5 - middle, 6 - ring, 7 - pinky
|  ecg_r_peak_direction|  1 if R-peak is up, -1 if R-peak is down, 0 or 2 if no ECG
|  leading_hand|  'r' if right, 'l' if left
|  ignore_events_id|  list of events to not include into analysis
|  reading_finger|  list of fingers used for Braille reading
|  blind|  1 if blind, 0 if sighted
|  order|  index of the record in the experiment. Failed sessions that have not made it into the dataset are counted.
|  blindness_age|  age of complete vision loss
|  reading_time|  time of reading Braille text of standard informed consent
|  braille_display_user|  1 if the subject uses Braille display in daily life
|  daily_braille_time|  self-reported daily Braille usage, hours
|  age|  user's age
|  music|  1 if the subject has musical experience (except vocal), 0 if not
|  remaining_vision|  1 if the user has residual vision, 0 if not
|  sex|  male or female
|  blind_years|  years passed from total vision loss
|  congenitaly_blind|  1 if congenital blindness, 0 if acquired

### Per-epoch markup
The preprocessed dataset has some added columns, which are calculated during the preprocessing stage.
|column name |description
|---|---|
|  id|  unique epoch id
|  event|  epoch event (activated stimuli id)
|  target|  id of current target stimuli
|  is_target|  1 if epoch is target, 0 if not
|  session_id|  stimuli selection cycle index inside experiment
|  epoch_id|  epoch index inside stimuli selection cycle (from 0 to 79)
|  ms_after_r|  milliseconds after R-peak
|  ms_before_r|  milliseconds before next R-peak

### Sourcedata folder structure
```
\
└── markup.csv                               # metadata for all records
└── user 
    └── record
        └── _data_$MODE__play_$TIME.npy      # Raw EEG data
        └── _events_$MODE__play_$TIME.npy    # BCI events
        └── _photocell_$MODE__play_$TIME.npy # sync events
        └── Rpeaks.npy                       # preprocessed R-peaks, if availible
```
users are numbered from 6 to 26

$MODE can be 'large' for large stimuli and 'small' for small stimuli

### Preprocessed data folder structure
```
\
└── markup.csv                               # metadata for all epochs, created at preprocessing stage
└── 0.pickle                                 # pickle files, corresponding to single epochs

...

└── $N.pickle
```