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. Values in participant_id MUST be unique. This column must appear first 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	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 "joint index". This means there MAY be more than one row per participant_id, but there MUST be no more than one unique combination of the joint indices defined in the list among all rows.

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"
    }
  }
}

Please 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 following tabular phenotypic data guidelines apply to phenotypic and assessment data.

• 1. Aggregate data across sessions using "IndexColumns"

• 2. Always pair tabular data with data dictionaries

• 3. Add MeasurementToolMetadata to each tabular phenotypic measurement tool

• 4. Ensure minimal annotation for phenotypic and assessment data

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