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. 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 (float or integer value). By default expressed using "year" as the unit. Other possible "Units" are described in Units. For privacy purposes, participant ages should be capped at 89 years. 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. 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.

There are two methods to record age in longitudinal or multi-session data sets. Choose what makes the most sense for your dataset's expected users. The first method is to aggregate into a single file in the phenotypic and assessment data directory using the "IndexColumns" field in the sidecar JSON. Read the tabular phenotypic data guidelines appendix or the phenotypic and assessment data section for an explanation of how to use "IndexColumns" to aggregate longitudinal or multi-session tabular phenotypic data. The second method is to segregate age into participant's session files. Read the sessions file section below for further explanation.

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

Template:

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

Optional: Yes

In case of multiple sessions there is an option of adding an additional sessions file describing each session and variables changing between sessions. Column names in sessions files MUST be different from participant key column names in the participants file.

These files MUST start with 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

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) tags. 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.json example:

{
    "session_id": {
        "Description": "Session identifier",
        "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"
    }
}

Read the tabular phenotypic data guidelines appendix or the phenotypic and assessment data section for an explanation of how to use "IndexColumns" to aggregate longitudinal or multi-session tabular phenotypic data.

Additional validation

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

5. Use a demographics file for multi-session data
6. Record acquisition time of all sessions with acq_time

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