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. For participants with multiple sessions, the session_id column is RECOMMENDED.

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. When in use, the session_id entries MUST be a superset of all session directories, all tabular phenotypic session_id entries found among phenotypic and assessment data in the phenotype/ directory, and all session_id entries found in the sessions file(s).

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. The combination of `participant_id` and `session_id` MUST be unique. This column must appear first in the file.
session_id	RECOMMENDED	string	A session identifier of the form `ses-<label>`, matching a session found in the dataset. The combination of `participant_id` and `session_id` MUST be unique. This column must appear second 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) tags. 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:

{
    "participant_id": {
        "Description": "participant identifier"
    },
    "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"
        }
    }
}

It is RECOMMENDED to use the age column to record participant age at every session in longitudinal or multi-session data sets. This reduces data duplication across tabular data files. The Units of age do not have to be years so long as the units of the age are written in participants.json. Consider participant privacy or study objectives when selecting the Units of age or the accuracy of age data.

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) tags. 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

In case of multiple sessions there is an option of adding an additional sessions.tsv file describing each session and variables changing between sessions. It is RECOMMENDED to provide this as a single file at the root-level of the dataset. It is OPTIONAL to instead provide these as separate files at the subject-level of the dataset. The intent of the sessions file is to describe the sessions in a data set and non-demographic variables changing between sessions. Column names in sessions.tsv files MUST be different from participant key column names in the participants file.

Column name	Requirement Level	Data type	Description
participant_id	OPTIONAL	string	A participant identifier of the form `sub-<label>`, matching a participant entity found in the dataset. The combination of `participant_id`, `session_id` and `run_id` MUST be unique. This column must appear first in the file.
session_id	REQUIRED	string	A session identifier of the form `ses-<label>`, matching a session found in the dataset. The combination of `participant_id`, `session_id` and `run_id` MUST be unique. This column must appear second in the file.
run_id	OPTIONAL	string	A run identifier that corresponds to an existing `run-<index>` entity used in a filename(s). The combination of `participant_id`, `session_id` and `run_id` MUST be unique. This column must appear third in the file.
acq_time	RECOMMENDED	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) tags. See the HED Appendix for details. This column may appear anywhere in the file.
Additional Columns	OPTIONAL	`n/a`	Additional columns are allowed.

sessions.json example:

{
    "participant_id": {
        "Description": "Participant identifier"
    },
    "session_id": {
        "Description": "Session identifier for the session",
        "Levels": {
            "ses-predrug": "session before drug administration",
            "ses-postdrug": "session after drug administration",
            "ses-followup": "follow-up session"
        }
    },
    "acq_time": {
        "Description": "Acquisition time of the session"
    },
    "systolic_blood_pressure": {
        "Description": "Systolic blood pressure measured at the beginning of the session in mmHg"
    }
}

RECOMMENDED: Root-level sessions file

├─ sessions.tsv 
└─ [sessions.json]

Optional: Yes

An aggregated sessions file is RECOMMENDED to be provided at the dataset root. If a root-level sessions file is provided, then it MUST begin with a participant_id column followed immediately after by a session_id column.

sessions.tsv example:

participant_id	session_id	acq_time	systolic_blood_pressure
sub-01	ses-predrug	2009-06-15T13:45:30	120
sub-01	ses-postdrug	2009-06-16T13:45:30	100
sub-01	ses-followup	2009-06-17T13:45:30	110
sub-02	ses-predrug	2009-06-22T12:22:05	105
sub-02	ses-postdrug	2009-06-23T12:22:05	95
sub-03	ses-postdrug	2009-06-30T14:06:40	115
sub-03	ses-followup	2009-07-01T14:06:40	120

OPTIONAL: Participant-level sessions files

└─ sub-<label>/
   ├─ sub-<label>_sessions.tsv 
   └─ [sub-<label>_sessions.json]

Optional: Yes

When one sessions file per participant is used, these files MUST include a session_id column and describe each session by one and only one row. sub-<label>/sub-<label>_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

Additional validation

When the AdditionalValidation key contains "Phenotype" in the dataset_description.json, the following tabular phenotypic data guidelines apply to sessions files:

6. Record participant properties in the participants file and session properties in the sessions file
7. Use the sessions file at the root-level
8. Use either root-level sessions file or participant-level sessions files, but not both
9. Record acquisition time of all sessions with acq_time
10. Respect participant privacy when recording acquisition times

To read more about the guidelines for tabular phenotypic data and examples, see the tabular phenotypic data guidelines appendix.