Data summary files

Participants file

Template:

participants.tsv
participants.json

The purpose of this RECOMMENDED file is to describe properties of participants such as age, sex, handedness, species and strain. If this file exists, it MUST contain the column participant_id, which MUST consist of sub-<label> values identifying one row for each participant, followed by a list of optional columns describing participants. Each participant MUST be described by one and only one row.

The participant_id entries MUST be a superset of all subject directories and all participant_id entries found among phenotypic and assessment data in the phenotype/ directory.

Commonly used optional columns in participants.tsv files are age, sex, handedness, strain, and strain_rrid.

The RECOMMENDED species column SHOULD be a binomial species name from the NCBI Taxonomy (for examples homo sapiens, mus musculus, rattus norvegicus). For backwards compatibility, if species is absent, the participant is assumed to be homo sapiens.

We RECOMMEND to make use of these columns, and in case that you do use them, we RECOMMEND to use the following values for them:

Column name	Requirement Level	Data type	Description
participant_id	REQUIRED	string	A participant identifier of the form sub-<label>, matching a participant entity found in the dataset. There MUST be exactly one row for each participant. Values in participant_id MUST be unique. This column must appear first in the file.
species	RECOMMENDED	string or number	The species column SHOULD be a binomial species name from the NCBI Taxonomy (for example, homo sapiens, mus musculus, rattus norvegicus). For backwards compatibility, if species is absent, the participant is assumed to be homo sapiens. This column may appear anywhere in the file.
age	RECOMMENDED	number	Numeric value in years (float or integer value). For privacy purposes, participant ages should be capped at 89. Using "89+" for ages above 88 is DEPRECATED. This column may appear anywhere in the file.
sex	RECOMMENDED	string	String value indicating phenotypical sex, one of "male", "female", "other". For "male", use one of these values: male, m, M, MALE, Male. For "female", use one of these values: female, f, F, FEMALE, Female. For "other", use one of these values: other, o, O, OTHER, Other. This column may appear anywhere in the file. For a list of valid values for this column, see the associated glossary entry.
handedness	RECOMMENDED	string	String value indicating one of "left", "right", "ambidextrous". For "left", use one of these values: left, l, L, LEFT, Left. For "right", use one of these values: right, r, R, RIGHT, Right. For "ambidextrous", use one of these values: ambidextrous, a, A, AMBIDEXTROUS, Ambidextrous. This column may appear anywhere in the file. For a list of valid values for this column, see the associated glossary entry.
strain	RECOMMENDED	string or number	For species different from homo sapiens, string value indicating the strain of the species, for example: C57BL/6J. This column may appear anywhere in the file.
strain_rrid	RECOMMENDED	string	For species different from homo sapiens, research resource identifier (RRID) of the strain of the species, for example: RRID:IMSR_JAX:000664. This column may appear anywhere in the file.
HED	OPTIONAL	string	Hierarchical Event Descriptor (HED) Tag. See the HED Appendix for details. This column may appear anywhere in the file.
Additional Columns	OPTIONAL	n/a	Additional columns are allowed.

Throughout BIDS you can indicate missing values with n/a (for "not available").

participants.tsv example:

participant_id	age	sex	handedness	group
sub-01	34	M	right	read
sub-02	12	F	right	write
sub-03	33	F	n/a	read

It is RECOMMENDED to accompany each participants.tsv file with a sidecar participants.json file to describe the TSV column names and properties of their values (see also the section on tabular files). Such sidecar files are needed to interpret the data, especially so when optional columns are defined beyond age, sex, handedness, species, strain, and strain_rrid, such as group in this example, or when a different age unit is needed (for example, gestational weeks). If no units is provided for age, it will be assumed to be in years relative to date of birth.

participants.json example:

{
    "age": {
        "Description": "age of the participant",
        "Units": "year"
    },
    "sex": {
        "Description": "sex of the participant as reported by the participant",
        "Levels": {
            "M": "male",
            "F": "female"
        }
    },
    "handedness": {
        "Description": "handedness of the participant as reported by the participant",
        "Levels": {
            "left": "left",
            "right": "right"
        }
    },
    "group": {
        "Description": "experimental group the participant belonged to",
        "Levels": {
            "read": "participants who read an inspirational text before the experiment",
            "write": "participants who wrote an inspirational text before the experiment"
        }
    }
}

Samples file

Template:

samples.tsv
samples.json

The purpose of this file is to describe properties of samples, indicated by the sample entity. This file is REQUIRED if sample-<label> is present in any filename within the dataset. Each sample MUST be described by one and only one row.

Column name	Requirement Level	Data type	Description
sample_id	REQUIRED	string	A sample identifier of the form sample-<label>, matching a sample entity found in the dataset. The combination of sample_id and participant_id MUST be unique.
participant_id	REQUIRED	string	A participant identifier of the form sub-<label>, matching a participant entity found in the dataset. The combination of sample_id and participant_id MUST be unique.
sample_type	REQUIRED	string	Biosample type defined by ENCODE Biosample Type. Must be one of: "cell line", "in vitro differentiated cells", "primary cell", "cell-free sample", "cloning host", "tissue", "whole organisms", "organoid", "technical sample".
pathology	RECOMMENDED	string or number	String value describing the pathology of the sample or type of control. When different from healthy, pathology SHOULD be specified. The pathology may be specified in either samples.tsv or sessions.tsv, depending on whether the pathology changes over time.
derived_from	RECOMMENDED	string	sample-<label> entity from which a sample is derived, for example a slice of tissue (sample-02) derived from a block of tissue (sample-01).
Additional Columns	OPTIONAL	n/a	Additional columns are allowed.

samples.tsv example:

sample_id	participant_id	sample_type	derived_from
sample-01	sub-01	tissue	n/a
sample-02	sub-01	tissue	sample-01
sample-03	sub-01	tissue	sample-01
sample-04	sub-02	tissue	n/a
sample-05	sub-02	tissue	n/a

It is RECOMMENDED to accompany each samples.tsv file with a sidecar samples.json file to describe the TSV column names and properties of their values (see also the section on tabular files).

samples.json example:

{
    "sample_type": {
        "Description": "type of sample from ENCODE Biosample Type (https://www.encodeproject.org/profiles/biosample_type)",
    },
    "derived_from": {
        "Description": "sample_id from which the sample is derived"
    }
}

Scans file

Template:

sub-<label>/
    [ses-<label>/]
        sub-<label>[_ses-<label>]_scans.tsv
        sub-<label>[_ses-<label>]_scans.json

Optional: Yes

The purpose of this file is to describe timing and other properties of each recording file within one session. In general, each of these files SHOULD be described by exactly one row.

For file formats that are based on several files of different extensions, or a directory of files with different extensions (multi-file file formats), only that file SHOULD be listed that would also be passed to analysis software for reading the data. For example for BrainVision data (.vhdr, .vmrk, .eeg), only the .vhdr SHOULD be listed; for EEGLAB data (.set, .fdt), only the .set file SHOULD be listed; and for CTF data (.ds), the whole .ds directory SHOULD be listed, and not the individual files in that directory.

Some neural recordings consist of multiple parts, that span several files, but that share the same extension. For example in entity-linked file collections, commonly used for qMRI, where recordings may be linked through entities such as echo and part (using .nii or .nii.gz extensions). For another example consider the case of large files in .fif format that are linked through the split entity (see Split files). Such recordings MUST be documented with one row per file (unlike the case of multi-file file formats described above).

Column name	Requirement Level	Data type	Description
filename	REQUIRED	string	Relative paths to files. There MUST be exactly one row for each file. Values in filename MUST be unique. This column must appear first in the file.
acq_time	OPTIONAL	string	Acquisition time refers to when the first data point in each run was acquired. Furthermore, if this header is provided, the acquisition times of all files from the same recording MUST be identical. Datetime format and their deidentification are described in Units. This column may appear anywhere in the file.
HED	OPTIONAL	string	Hierarchical Event Descriptor (HED) Tag. See the HED Appendix for details. This column may appear anywhere in the file.
Additional Columns	OPTIONAL	n/a	Additional columns are allowed.

Additional fields can include external behavioral measures relevant to the scan. For example vigilance questionnaire score administered after a resting state scan. All such included additional fields SHOULD be documented in an accompanying _scans.json file that describes these fields in detail (see Tabular files).

Example _scans.tsv:

filename	acq_time
func/sub-control01_task-nback_bold.nii.gz	1877-06-15T13:45:30
func/sub-control01_task-motor_bold.nii.gz	1877-06-15T13:55:33
meg/sub-control01_task-rest_split-01_meg.nii.gz	1877-06-15T12:15:27
meg/sub-control01_task-rest_split-02_meg.nii.gz	1877-06-15T12:15:27

Sessions file

Template:

sub-<label>/
    sub-<label>_sessions.tsv

Optional: Yes

In case of multiple sessions there is an option of adding additional sessions.tsv files describing variables changing between sessions. In such case one file per participant SHOULD be added. These files MUST include a session_id column and describe each session by one and only one row. Column names in sessions.tsv files MUST be different from group level participant key column names in the participants.tsv file.

Column name	Requirement Level	Data type	Description
session_id	REQUIRED	string	A session identifier of the form ses-<label>, matching a session found in the dataset. There MUST be exactly one row for each session. Values in session_id MUST be unique. This column must appear first in the file.
acq_time	OPTIONAL	string	Acquisition time refers to when the first data point of the first run was acquired. Datetime format and their deidentification are described in Units. This column may appear anywhere in the file.
pathology	RECOMMENDED	string or number	String value describing the pathology of the sample or type of control. When different from healthy, pathology SHOULD be specified. The pathology may be specified in either samples.tsv or sessions.tsv, depending on whether the pathology changes over time. This column may appear anywhere in the file.
HED	OPTIONAL	string	Hierarchical Event Descriptor (HED) Tag. See the HED Appendix for details. This column may appear anywhere in the file.
Additional Columns	OPTIONAL	n/a	Additional columns are allowed.

_sessions.tsv example:

session_id	acq_time	systolic_blood_pressure
ses-predrug	2009-06-15T13:45:30	120
ses-postdrug	2009-06-16T13:45:30	100
ses-followup	2009-06-17T13:45:30	110