Data summary files

Participants file

Template:

participants.tsv
participants.json

The purpose of this RECOMMENDED file is to describe unchanging properties of participants such as sex, 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. For participants with multiple sessions, see the sessions file and demographics file sections.

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). It is RECOMMENDED to tag participant ages that are 89 or higher as 89+, for privacy purposes. 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"
    }
}

Demographics file

Template:

phenotype/
    demographics.tsv
    demographics.json

The demographics file is an OPTIONAL tabular phenotypic file in the phenotype/ directory meant to house common subject demographics. For example demographics like age, gender, race, and household income. A demographics file is RECOMMENDED to use when any participant has more than one session of any type. It does not replace the participants file, which is meant for unchanging data about each participant in the data set. It is instead a superset of the participants file, centralizing demographics across as many sessions as are available.

Guideline 5

For best tabular phenotypic data: Some studies collect demographics into their own tabular phenotypic data file already. In these cases, it is RECOMMENDED to house this data also in the demographics file.

Guideline 6

For best tabular phenotypic data: 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 phenotype/demographics.json. Consider participant privacy or study objectives when selecting the Units of age or the accuracy of age data.

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 A (segregated sessions files):

[sessions.json]
sub-<label>/
    sub-<label>_sessions.tsv

Optional: Yes

In case of multiple sessions there is an option of adding additional sessions.tsv files describing each session and 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.

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

Template B (aggregated sessions file):

sessions.tsv
sessions.json

Optional: Yes

An aggregated sessions file CAN 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. The intent of this root-level sessions file is to describe the sessions in a data set and non-demographic variables changing between sessions. Participant's demographic variables should be added to a demographics file, as described above.

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

Guideline 7

For best tabular phenotypic data: If there is more than one session for any one participant, then it is REQUIRED to provide a sessions file at the dataset root. The sessions file MUST list all sessions for all subjects across imaging and tabular phenotypic data.

When a sessions file is in use, you MUST NOT provide additional sessions files at the participant-level which would otherwise use the inheritance principle. If a sessions file is provided, then it MUST begin with a participant_id column followed immediately by a session_id column. The data dictionary JSON file's session_id field MUST include Levels with the description of each session_id.

Guideline 8

For best tabular phenotypic data: Whenever possible, it is RECOMMENDED to also collect acquisition time for tabular phenotypic data and store the time of acquisition of each row inside a column named acq_time in the sessions file. This is consistent with how acquisition time is recorded for MRI data and other time-sensitive measurements (for example systolic blood pressure).

When it is needed to preserve participant privacy, you SHOULD record relative acquisition times with respect to the earliest session. Relative session acquisition times MAY be listed as durations from the earliest session (baseline) in days, months, or years using the acq_time column.