Phenotypic and assessment data

Template:

phenotype/
    [tool-]<MeasurementToolName>[_phenotype].tsv
    [tool-]<MeasurementToolName>[_phenotype].json

Optional: Yes

If the dataset includes multiple sets of participant level measurements (for example responses from multiple questionnaires) they can be split into individual files separate from participants.tsv.

Each of the measurement tool files MUST be kept in a /phenotype directory placed at the root of the BIDS dataset and MUST end with the .tsv extension. Filenames SHOULD be chosen to reflect the contents of the file. For example, the "Adult ADHD Clinical Diagnostic Scale" could be saved in a file called /phenotype/acds_adult.tsv.

The files can include an arbitrary set of columns, but one of them MUST be participant_id and the entries of that column MUST correspond to the subjects in the BIDS dataset and participants.tsv file.

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. If `IndexColumns` is in use, then `participant_id` MAY appear on more than one row. The combination of `IndexColumns` on rows MUST be unique. Values in `participant_id` MUST be unique. This column must appear first in the file.
session_id	OPTIONAL	string	A session identifier of the form `ses-<label>`, matching a session found in the dataset. This column may appear anywhere in the file.
run_id	OPTIONAL	string	A run identifier of the form `run-<index>`, used to distinguish separate acquisitions with the otherwise same properties. 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.

As with all other tabular data, the additional tabular phenotypic data MAY be accompanied by a JSON data dictionary file describing the columns in detail (see Tabular files). When the AdditionalValidation key contains "Phenotype" in the dataset_description.json, then the additional tabular phenotypic data MUST be accompanied by a JSON data dictionary file.

In addition to the column descriptions, the JSON file MAY contain the following fields:

Key name	Requirement Level	Data type	Description
IndexColumns	OPTIONAL	array of strings	A list of column names to be used as joint indices in their corresponding tabular phenotypic data file.
MeasurementToolMetadata	OPTIONAL, but RECOMMENDED by phenotype guidelines	object	A description of the measurement tool as a whole. Contains two fields: `"Description"` and `"TermURL"`. `"Description"` is a free text description of the measurement tool. `"TermURL"` is a URL to an entity in an ontology corresponding to this tool. RECOMMENDED by `AdditionalValidation` containing `"Phenotype"` in `dataset_description.json`.
Derivative	OPTIONAL	boolean	Indicates that values in the corresponding column are transformations of values from other columns (for example a summary score based on a subset of items in a questionnaire). Must be one of: `"true"`, `"false"`.

The "IndexColumns" field defines a list of column names to be used as a "joint index". This means, for the relevant tabular data file, each row must have a unique combination of values for the columns specified by "IndexColumns". This replaces the implicit constraint on the participant_id column that its values MUST be unique.

As an example, consider the contents of a file called phenotype/tool-ACDSAdult_phenotype.json in a multi-session dataset:

{
  "IndexColumns": [
    "participant_id",
    "session_id"
  ],
  "MeasurementToolMetadata": {
    "Description": "Adult ADHD Clinical Diagnostic Scale V1.2",
    "TermURL": "https://www.cognitiveatlas.org/task/id/trm_5586ff878155d"
  },
  "participant_id": {
    "Description": "BIDS participant identifier, of the format sub-<label>"
  },
  "session_id": {
    "Description": "BIDS session identifier, of the format ses-<label>"
  },
  "adhd_b": {
    "Description": "B. CHILDHOOD ONSET OF ADHD (PRIOR TO AGE 7)",
    "Levels": {
      "1": "YES",
      "2": "NO"
    }
  },
  "adhd_c_dx": {
    "Description": "As child met A, B, C, D, E and F diagnostic criteria",
    "Levels": {
      "1": "YES",
      "2": "NO"
    }
  }
}

Note in this example there MUST be no more than one unique combination of the joint indices of participant_id and session_id. Also in the above example, MeasurementToolMetadata includes information about the questionnaire, and participant_id, session_id, adhd_b, and adhd_c_dx correspond to individual columns in the TSV data.

For TSV examples, read the tabular phenotypic data guidelines appendix.

In addition to the keys available to describe columns in all tabular files (LongName, Description, Levels, Units, and TermURL) the participants.json file as well as phenotypic files can also include column descriptions with a Derivative field that, when set to true, indicates that values in the corresponding column are a transformation of values from other columns (for example a summary score based on a subset of items in a questionnaire).

Additional validation

When the AdditionalValidation key contains "Phenotype" in the dataset_description.json, the tabular phenotypic data guidelines become REQUIRED.

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