diff --git a/mkdocs.yml b/mkdocs.yml index 2e5c7b3576..c21722567c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,6 +46,7 @@ nav: - Quantitative MRI: appendices/qmri.md - Arterial Spin Labeling: appendices/arterial-spin-labeling.md - Cross modality correspondence: appendices/cross-modality-correspondence.md + - Phenotypic data guidelines: appendices/phenotype.md - Changelog: CHANGES.md - The BIDS Starter Kit: - Website: https://bids-standard.github.io/bids-starter-kit/ diff --git a/src/appendices/phenotype.md b/src/appendices/phenotype.md new file mode 100644 index 0000000000..66a96cd6b4 --- /dev/null +++ b/src/appendices/phenotype.md @@ -0,0 +1,335 @@ +# Tabular phenotypic data guidelines + +This appendix is a collection of guidelines and examples for creating well-organized aggregated tabular phenotypic data. + +## Guidelines + +These guidelines are all **RECOMMENDED** when preparing +tabular phenotypic data like the +participants file, sessions file, demographics file, +or phenotypic and assessment data. +The language below uses REQUIRED, MUST, and others to imply +these are the requirements for these **RECOMMENDED** guidelines. + +### 1. Always pair tabular data with data dictionaries + +Tabular phenotypic data MUST be prepared as one pair of a tabular file +in tab-separated value (TSV) format and a corresponding data dictionary +in JavaScript Object Notation (JSON) format. + +### 2. Aggregate data across sessions + +Aggregation refers to the contents of the TSV file. It is REQUIRED +to collect all participant data into one TSV per tabular phenotypic file. + +### 3. Ensure minimal annotation for phenotypic and assessment data + +In phenotypic and assessment data each measurement tool has an independent +aggregated data TSV file in which the user collects all subjects, sessions, +and/or runs of data as one entry per row (with a row defined by +the smallest unit of acquisition). In other words: + +1. Each row MUST start with `participant_id`. + +1. Each TSV file MUST contain a `session_id` column when + multiple [sessions](../glossary.md#session-entities)[^1] are present + in the data set regardless of whether those sessions are in + the `phenotype/` data, `sub-