RS-BIDSify is a package that leverages MNE and MNE-BIDS to easily and flexibly convert legacy resting-state EEG datasets to BIDS-compliant datasets.
It has been designed and built to be used as part of the #EEGManyLabs Resting-State project (ElectroPool/RosettaState).
RS-BIDSify works with Python>=3.12 and can be installed directly from GitHub:
pip install rs-bidsify@git+https://github.com/ubdbra001/rs-bidsify.gitIt is recommended that you install the package into a virtual environment.
The input directory requires a specific structure to work. Each participant should have a single directory for their data, and there should only be a single recording in each directory.
dataset/
├── data_metadata.json
├── participant_data.ods
├── sub-001/
│ └── sub-001.edf
├── sub-002/
│ └── sub-002.edf
├── sub-003/
│ └── sub-003.edf
├── ...
└── sub-xxx/
└── sub-xxx.edfEach subject directory can, optionally, contain task sub-directories, but again there should be a single recording per directory. e.g.:
dataset/
├── sub-001/
│ ├── rest/
│ │ └── sub-001-rest.edf
│ └── video/
│ └── sub-001-video.edf
...The JSON file containg the dataset metadata and the spreadsheet (ods) containing the participant information should be in the root of the raw data directory. These do not have to be named as in the example above, but should have the correct file extensions, and there should only be a single file for each.
This file specifies the metadata describing the dataset. It is split into 4 different sections.
See the appendix below for an example of a complete metatdata file
This is a array/list outlining the different tasks present in the data set. It can be omitted if there is only a single task (in which case the task name will default to "rest"), but it is required when task directories are present in the dataset file structure, and the values should correspond exactly.
"tasks": ["rest", "video"]This structure contains infomation about dataset-level metadata (i.e. values that would not differ between participants)
"metadata": {
"population": "Healthy Adults",
"dataset_name": "Test dataset",
"authors": [
"Pavlov, Yuri"
],
"funding": "n/a",
"ethics_approval": "Approved",
"references_links": "n/a",
"license": "n/a",
"institution_name": "n/a",
"institution_dept": "n/a"
}This structure contains information about the specifics of each recording. It can be broken down into several sections:
This is the basic information about the recording, e.g. sampling frequency, power line frequency, input file format, etc.
"software": "Brain Vision Recorder",
"acquisition_freq": 1000,
"file_format": ".set",
"amplifier_model": "Brain Products",
"power_line_freq": 50,This structure contains information about the EEG channels present in the recording.
"eeg_channels": {
"number" : 63,
"montage": {
"mne_name": "standard_1005"
},
"ground": "FPz",
"reference": "Cz"
}This structure outlines the details of all the non-EEG channels present in the recordings.
Each channel should be named as they are in the recording, and should include information about the type of channel in both MNE and BIDS, as well as the location of the channel, measurement units, and description.
"aux_channels": {
"ECG": {
"mne_type": "ecg",
"bids_type": "ECG",
"location": {
"active": "right wrist",
"reference": "left wrist",
"ground": "left inner forearm 3 cm distal from the elbow"
}
},
"PPG": {
"mne_type": "misc",
"bids_type": "PPG",
"description": "photoplethysmography",
"location": "placed on the left index finger",
"units": "µV"
},
"audio": {
"mne_type": "misc",
"bids_type": "AUDIO",
"description": "Audio channel",
"location": "n/a"
}
}This section consists of a list of all the hardware and software filters soecified for the recording.
Each filter should consist of an object with a name, a type (Hardware or Software), and info about the filter.
Info should be represented in an object with key value pairs, and these are translated directly to the BIDS recording sidecar file.
"filters": [
{
"name": "Low-pass filter",
"type": "Software",
"info": {
"cut-off frequency (Hz)": 260
}
}
],
This structure specifies extra metadata that may be recorded but does not have a formal place in BIDS, and so may optioanlly be included in the final BIDS-compliant dataset. This section is entirely optional, as are each of the fields contained within.
"extras": {
"acceptable_impedance": {"value": 25, "units": "kOhm"},
"electrode_type": "active",
"conductive_medium": "gel",
"faraday_cage": false,
"sound_proof": false,
"lighting_conditions": {
"description": "380 lux ambient lighting",
"measurement": "measured with a luxmeter around the head of the participant"
}
}This section conatins information about the resting state tasks undertaken during the recording.
In includes information about the instructions issued to the participants, the duration of the eyes-open and eyes-closed tasks, the stimuli used during these tasks, any other tasks recorded, and the detials of the event markers captured during the recording.
"resting_state": {
"instructions": "A prerecorded voice gave commands to open and close the eyes every minute. The stimuli were presented in PsychoPy.",
"eyes_closed": {
"duration_secs": 240
},
"eyes_open": {
"duration_secs": 240,
"stimulus_description": "white fixation cross on a grey background"
},
"other_task": [
{
"task_name": "video watching",
"duration_secs": 231,
"stimulus_description": "a short animated movie 'The man who was afraid of falling' (https://osf.io/x9jpz)"
}
],
"events": {
"S 20": "Eyes open",
"S 21": "Eyes closed",
"S 22": "Movie start",
"S 23": "Movie end",
"S254": "Start of Resting State Recording",
"S252": "End of Resting State Recording"
}
}This file contians information about the participants. This information should be stored in tabular form in a single worksheet with the columns: participant_id, age, sex, and handedness.
It should also contain a codebook: a seperate sheet with a table describing what each of these columns represent.
This file can also optionally contain a sheet with phenotype data collected from the participants. This data should also be stored in tabular form with the required column participant_id, whose values should match the values in the participant information worksheet. As many other columns may be added to the sheet.
If a phenotype sheet is included then a phenotype codebook sheet is required. As with the participant dataset codebook, this should describe each of the columns present in the phenotype datasheet.
By default a .ods spreadsheet is expected, but this can be customised in the config file (see below).
RS-BIDSify has the following command line options:
Usage: rs-bidsify [OPTIONS] COMMAND [ARGS]
Options:
--version, -v : Show the installed veriosn of RS-BIDSify
--help: Show the available options and commands
Commands:
convert: Convert a raw EEG dataset into BIDS-compliant format.
Command for converting a raw EEG dataset with metadata into BIDS-compliant format.
Usage: rs-bidsify convert [OPTIONS] RAW_DATA_PATH BIDS_DATA_PATH
Arguments:
RAW_DATA_PATH: Path to the directory containig the raw EEG Dataset and metadata
BIDS_DATA_PATH: Path to the directory where the BIDS-formatted dataset will be saved
Options:
--config: Path to a user specified YAML configuration file
--logs: Location for logs (defaults to '../logs' relative to raw_data_path)
Example usage:
# Standard Usage
rs-bidsify convert path/to/raw/data path/for/bids/data
# Specify a custom configuration file
rs-bidsify convert path/to/raw/data path/for/bids/data --config path/to/config.yml
# Specify a different location for the log file
rs-bidsify convert path/to/raw/data path/for/bids/data --logs path/to/logs
See below for information about options that can be specifed in the configuration file.
The configuration file should be a yaml file, and can be used to set the following options:
This describes mappings between text and numeric values for how sex and handedness may be described in the participants spreadsheet.
demographic_mappings:
sex:
u: 0
unknown: 0
m: 1
male: 1
f: 2
female: 2
hand:
r: 1
right: 1
l: 2
left: 2
a: 3
ambidextrous: 3This describes the location and index column for each sheet in the participant information spreadsheet:
sheet_info:
participant:
dataset:
sheet_name: 6
index_col: "participant_id"
codebook:
sheet_name: 7
index_col: "Variable"
phenotype:
dataset:
sheet_name: 8
index_col: "participant_id"
codebook:
sheet_name: 9
index_col: "Variable"The file extension to search for when looking up the participant spreadsheet:
spreadsheet_ext: "ods"The file extension to search for when looking up the metadta file:
metadata_ext: "json"The file format to save the EEG data to in the BIDS-compliant output:
output_EEG_format: "edf"A flag indicating whether the extra information section of the metadata should be written to the EEG recording sidecar files.
include_extras: trueBelow is an example of a complete JSON metadata file:
{
"tasks": ["rest", "video"],
"metadata": {
"population": "Healthy Adults",
"dataset_name": "Test dataset",
"authors": [
"Pavlov, Yuri"
],
"funding": "n/a",
"ethics_approval": "Approved",
"references_links": "n/a",
"license": "n/a",
"institution_name": "n/a",
"institution_dept": "n/a"
},
"acquisition_spec": {
"software": "Brain Vision Recorder",
"amplifier_model": "Brain Products",
"power_line_freq": 50,
"acquisition_freq": 1000,
"file_format": ".set",
"eeg_channels": {
"number" : 63,
"montage": {
"mne_name": "standard_1005"
},
"ground": "FPz",
"reference": "VARIES"
},
"aux_channels": {
"ECG": {
"mne_type": "ecg",
"bids_type": "ECG",
"location": {
"active": "right wrist",
"reference": "left wrist",
"ground": "left inner forearm 3 cm distal from the elbow"
}
},
"PPG": {
"mne_type": "misc",
"bids_type": "PPG",
"description": "photoplethysmography",
"location": "placed on the left index finger",
"units": "µV"
},
"audio": {
"mne_type": "misc",
"bids_type": "AUDIO",
"description": "Audio channel",
"location": "n/a"
}
},
"filters": [
{
"name": "Low-pass filter",
"type": "Software",
"info": {
"cut-off frequency (Hz)": 260
}
}
],
"extras": {
"acceptable_impedance": {"value": 25, "units": "kOhm"},
"electrode_type": "active",
"conductive_medium": "gel",
"faraday_cage": false,
"sound_proof": false,
"lighting_conditions": {
"description": "380 lux ambient lighting",
"measurement": "measured with a luxmeter around the head of the participant"
}
}
},
"resting_state": {
"instructions": "A prerecorded voice gave commands to open and close the eyes every minute. The stimuli were presented in PsychoPy.",
"eyes_closed": {
"duration_secs": 240
},
"eyes_open": {
"duration_secs": 240,
"stimulus_description": "white fixation cross on a grey background"
},
"other_tasks": [
{
"task_name": "video watching",
"duration_secs": 231,
"stimulus_description": "a short animated movie 'The man who was afraid of falling' (https://osf.io/x9jpz)"
}
],
"events": {
"S 20": "Eyes open",
"S 21": "Eyes closed",
"S 22": "Movie start",
"S 23": "Movie end",
"S254": "Start of Resting State Recording",
"S252": "End of Resting State Recording"
}
},
}