[SCHEMA] Add TSV column files

src/03-modality-agnostic-files.md

@@ -175,31 +175,15 @@ Each participant MUST be described by one and only one row.
 Commonly used *optional* columns in `participant.tsv` files are `age`, `sex`,
 and `handedness`. 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:
+for them.
 
--   `age`: numeric value in years (float or integer value)
-
--   `sex`: 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`
-
--   `handedness`: 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`
+{{ MACROS___make_columns_table(
+   {
+      "age": "RECOMMENDED",
+      "sex": "RECOMMENDED",
+      "handedness": "RECOMMENDED",
+   }
+) }}
 
 Throughout BIDS you can indicate missing values with `n/a` (for "not
 available").
@@ -266,6 +250,18 @@ 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 file name within the dataset.
+Each sample MUST be described by one and only one row.
+
+{{ MACROS___make_columns_table(
+   {
+      "sample_id": "REQUIRED",
+      "participant_id": "REQUIRED",
+      "sample_type": "REQUIRED",
+      "pathology": "RECOMMENDED",
+      "derived_from": "RECOMMENDED",
+   }
+) }}
+
 If this file exists, it MUST contain the three following columns:
 
 -   `sample_id`: MUST consist of `sample-<label>` values identifying one row
@@ -278,7 +274,6 @@ If this file exists, it MUST contain the three following columns:
     `technical sample` from [ENCODE Biosample Type](https://www.encodeproject.org/profiles/biosample_type)
 
 Other optional columns MAY be used to describe the samples.
-Each sample MUST be described by one and only one row.
 
 Commonly used *optional* columns in `samples.tsv` files are `pathology` and
 `derived_from`. We RECOMMEND to make use of these columns, and in case that
@@ -416,22 +411,12 @@ Some recordings consist of multiple parts, that span several files,
 for example through `echo-`, `part-`, or `split-` entities.
 Such recordings MUST be documented with one row per file.
 
-Relative paths to files should be used under a compulsory `filename` header.
-
-If acquisition time is included it should be listed under the `acq_time` header.
-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 that
-belong to a recording MUST be identical.
-
-Datetime should be expressed as described in [Units](./02-common-principles.md#units).
-
-For anonymization purposes all dates within one subject should be shifted by a
-randomly chosen (but consistent across all recordings) number of days.
-This way relative timing would be preserved, but chances of identifying a
-person based on the date and time of their scan would be decreased.
-Dates that are shifted for anonymization purposes SHOULD be set to the year 1925
-or earlier to clearly distinguish them from unmodified data.
-Shifting dates is RECOMMENDED, but not required.
+{{ MACROS___make_columns_table(
+   {
+      "filename": "REQUIRED",
+      "acq_time": "OPTIONAL",
+   }
+) }}
 
 Additional fields can include external behavioral measures relevant to the
 scan.
@@ -469,6 +454,13 @@ These files MUST include a `session_id` column and describe each session by one
 Column names in `sessions.tsv` files MUST be different from group level participant key column names in the
 [`participants.tsv` file](./03-modality-agnostic-files.md#participants-file).
 
+{{ MACROS___make_columns_table(
+   {
+      "session_id": "REQUIRED",
+      "acq_time": "OPTIONAL",
+   }
+) }}
+
 `_sessions.tsv` example:
 
 ```Text

src/04-modality-specific-files/02-magnetoencephalography.md

@@ -227,6 +227,14 @@ MUST be present **in this specific order**:
 | type            | REQUIRED              | Type of channel; MUST use the channel types listed below. Note that the type MUST be in upper-case.                                                                           |
 | units           | REQUIRED              | Physical unit of the value represented in this channel, for example, `V` for Volt, or `fT/cm` for femto Tesla per centimeter (see [Units](../02-common-principles.md#units)). |
 
+{{ MACROS___make_columns_table(
+   {
+      "name_channels": "REQUIRED",
+      "type": "REQUIRED",
+      "units": "REQUIRED",
+   }
+) }}
+
 SHOULD be present:
 
 | **Column name**    | **Requirement level** | **Description**                                                                                                                                                                                                                                                     |
@@ -240,6 +248,19 @@ SHOULD be present:
 | status             | OPTIONAL              | Data quality observed on the channel `(good/bad)`. A channel is considered `bad` if its data quality is compromised by excessive noise. Description of noise type SHOULD be provided in `[status_description]`.                                                     |
 | status_description | OPTIONAL              | Freeform text description of noise or artifact affecting data quality on the channel. It is meant to explain why the channel was declared bad in `[status]`.                                                                                                        |
 
+{{ MACROS___make_columns_table(
+   {
+      "description": "OPTIONAL",
+      "sampling_frequency": "OPTIONAL",
+      "low_cutoff": "OPTIONAL",
+      "high_cutoff": "OPTIONAL",
+      "notch": "OPTIONAL",
+      "software_filters": "OPTIONAL",
+      "status": "OPTIONAL",
+      "status_description": "OPTIONAL",
+   }
+) }}
+
 Example:
 
 ```Text

src/04-modality-specific-files/03-electroencephalography.md

@@ -222,6 +222,14 @@ MUST be present **in this specific order**:
 | type            | REQUIRED              | Type of channel; MUST use the channel types listed below. Note that the type MUST be in upper-case.                                                                           |
 | units           | REQUIRED              | Physical unit of the value represented in this channel, for example, `V` for Volt, or `fT/cm` for femto Tesla per centimeter (see [Units](../02-common-principles.md#units)). |
 
+{{ MACROS___make_columns_table(
+   {
+      "name_channels": "REQUIRED",
+      "type": "REQUIRED",
+      "units": "REQUIRED",
+   }
+) }}
+
 SHOULD be present:
 
 | **Column name**    | **Requirement level** | **Description**                                                                                                                                                                                                                                                 |
@@ -235,6 +243,19 @@ SHOULD be present:
 | status             | OPTIONAL              | Data quality observed on the channel (`good`, `bad`). A channel is considered `bad` if its data quality is compromised by excessive noise. Description of noise type SHOULD be provided in `status_description`.                                                |
 | status_description | OPTIONAL              | Free-form text description of noise or artifact affecting data quality on the channel. It is meant to explain why the channel was declared bad in `status`.                                                                                                     |
 
+{{ MACROS___make_columns_table(
+   {
+      "description": "OPTIONAL",
+      "sampling_frequency": "OPTIONAL",
+      "reference": "OPTIONAL",
+      "low_cutoff": "OPTIONAL",
+      "high_cutoff": "OPTIONAL",
+      "notch": "OPTIONAL",
+      "status": "OPTIONAL",
+      "status_description": "OPTIONAL",
+   }
+) }}
+
 Restricted keyword list for field `type` in alphabetic order (shared with the
 MEG and iEEG modality; however, only the types that are common in EEG data are listed here).
 Note that upper-case is REQUIRED:
@@ -295,6 +316,15 @@ MUST be present **in this specific order**:
 | y               | REQUIRED              | Recorded position along the y-axis. |
 | z               | REQUIRED              | Recorded position along the z-axis. |
 
+{{ MACROS___make_columns_table(
+   {
+      "name_electrodes": "REQUIRED",
+      "x": "REQUIRED",
+      "y": "REQUIRED",
+      "z": "REQUIRED",
+   }
+) }}
+
 SHOULD be present:
 
 | **Column name** | **Requirement level** | **Description**                                                        |
@@ -303,6 +333,14 @@ SHOULD be present:
 | material        | RECOMMENDED           | Material of the electrode  (for example, Tin, Ag/AgCl, Gold).          |
 | impedance       | RECOMMENDED           | Impedance of the electrode, units MUST be in `kOhm`.                   |
 
+{{ MACROS___make_columns_table(
+   {
+      "type": "RECOMMENDED",
+      "material": "RECOMMENDED",
+      "impedance": "RECOMMENDED",
+   }
+) }}
+
 ### Example `electrodes.tsv`
 
 See also the corresponding [`electrodes.tsv` example](#example-channelstsv).

src/04-modality-specific-files/04-intracranial-electroencephalography.md

@@ -234,6 +234,16 @@ MUST be present **in this specific order**:
 | low_cutoff      | REQUIRED              | Frequencies used for the low pass filter applied to the channel in Hz. If no low pass filter was applied, use `n/a`. Note that anti-alias is a low pass filter, specify its frequencies here if applicable. |
 | high_cutoff     | REQUIRED              | Frequencies used for the high pass filter applied to the channel in Hz. If no high pass filter applied, use `n/a`.                                                                                          |
 
+{{ MACROS___make_columns_table(
+   {
+      "name_channels": "REQUIRED",
+      "type": "REQUIRED",
+      "units": "REQUIRED",
+      "low_cutoff": "REQUIRED",
+      "high_cutoff": "REQUIRED",
+   }
+) }}
+
 SHOULD be present:
 
 | **Column name**    | **Requirement level** | **Description**                                                                                                                                                                                                                                                            |
@@ -246,6 +256,18 @@ SHOULD be present:
 | status             | OPTIONAL              | Data quality observed on the channel (good/bad). A channel is considered bad if its data quality is compromised by excessive noise. Description of noise type SHOULD be provided in `[status_description]`.                                                                |
 | status_description | OPTIONAL              | Freeform text description of noise or artifact affecting data quality on the channel. It is meant to explain why the channel was declared bad in `[status]`.                                                                                                               |
 
+{{ MACROS___make_columns_table(
+   {
+      "reference": "OPTIONAL",
+      "group": "OPTIONAL",
+      "sampling_frequency": "OPTIONAL",
+      "description": "OPTIONAL",
+      "notch": "OPTIONAL",
+      "status": "OPTIONAL",
+      "status_description": "OPTIONAL",
+   }
+) }}
+
 **Example** `sub-01_channels.tsv`:
 
 ```Text
@@ -343,6 +365,16 @@ MUST be present **in this specific order**:
 | z               | REQUIRED              | Z position. If electrodes are in 2D space this should be a column of `n/a` values.                                               |
 | size            | REQUIRED              | Surface area of the electrode, units MUST be in `mm^2`.                                                                          |
 
+{{ MACROS___make_columns_table(
+   {
+      "name_electrodes": "REQUIRED",
+      "x": "REQUIRED",
+      "y": "REQUIRED",
+      "z": "REQUIRED",
+      "size": "REQUIRED",
+   }
+) }}
+
 SHOULD be present:
 
 | **Column name** | **Requirement level** | **Description**                                                                                                                  |
@@ -352,6 +384,15 @@ SHOULD be present:
 | group           | RECOMMENDED           | The group that the electrode is a part of. Note that any group specified here should match a group specified in `_channels.tsv`. |
 | hemisphere      | RECOMMENDED           | The hemisphere in which the electrode is placed, one of `['L' or 'R']` (use capital).                                            |
 
+{{ MACROS___make_columns_table(
+   {
+      "material": "RECOMMENDED",
+      "manufacturer": "RECOMMENDED",
+      "group": "RECOMMENDED",
+      "hemisphere": "RECOMMENDED",
+   }
+) }}
+
 MAY be present:
 
 | **Column name** | **Requirement level** | **Description**                                                                                                                                        |
@@ -360,6 +401,14 @@ MAY be present:
 | impedance       | OPTIONAL              | Impedance of the electrode, units MUST be in `kOhm`.                                                                                                   |
 | dimension       | OPTIONAL              | Size of the group (grid/strip/probe) that this electrode belongs to. Must be of form `[AxB]` with the smallest dimension first (for example, `[1x8]`). |
 
+{{ MACROS___make_columns_table(
+   {
+      "type": "OPTIONAL",
+      "impedance": "OPTIONAL",
+      "dimension": "OPTIONAL",
+   }
+) }}
+
 Example:
 
 ```Text

src/04-modality-specific-files/05-task-events.md

@@ -44,6 +44,18 @@ and OPTIONAL columns:
 | value           | OPTIONAL              | [string][] or [number][] | Marker value associated with the event (for example, the value of a TTL trigger that was recorded at the onset of the event).                                                                                                                                                 |
 | HED             | OPTIONAL              | [string][]               | Hierarchical Event Descriptor (HED) tag. See [Appendix III](../99-appendices/03-hed.md) for details.                                                                                                                                                                          |
 
+{{ MACROS___make_columns_table(
+   {
+      "onset": "REQUIRED",
+      "duration": "REQUIRED",
+      "sample": "OPTIONAL",
+      "trial_type": "OPTIONAL",
+      "response_time": "OPTIONAL",
+      "value": "OPTIONAL",
+      "HED": "OPTIONAL",
+   }
+) }}
+
 <sup>5</sup> Note for MRI data:
 If any acquired scans have been discarded before forming the imaging data file,
 ensure that an `onset` of 0 corresponds to the time the first image was stored.
@@ -141,6 +153,12 @@ but they should be stored in the `/stimuli` folder.
 | --------------- | --------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | stim_file       | OPTIONAL              | [string][]    | Represents the location of the stimulus file (such as an image, video, or audio file) presented at the given onset time. The values under the `stim_file` column correspond to a path relative to the folder `/stimuli`. For example `images/cat03.jpg` will be translated to `/stimuli/images/cat03.jpg`. |
 
+{{ MACROS___make_columns_table(
+   {
+      "stim_file": "OPTIONAL",
+   }
+) }}
+
 ### Stimuli databases
 
 References to existing databases can also be encoded using additional columns.

src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md

@@ -113,6 +113,14 @@ following naming conventions SHOULD be used for the column names:
 | respiratory     | continuous breathing measurement                     |
 | trigger         | continuous measurement of the scanner trigger signal |
 
+{{ MACROS___make_columns_table(
+   {
+      "cardiac": "OPTIONAL",
+      "respiratory": "OPTIONAL",
+      "trigger": "OPTIONAL",
+   }
+) }}
+
 For any other data to be specified in columns, the column names can be chosen
 as deemed appropriate by the researcher.
 

src/04-modality-specific-files/09-positron-emission-tomography.md

@@ -364,6 +364,17 @@ The `time` column MUST always be the first column.
 | `hplc_recovery_fractions`    | REQUIRED if `MetaboliteRecoveryCorrectionApplied` is `true` | HPLC recovery fractions (the fraction of activity that gets loaded onto the HPLC) | Unit of recovery fractions (for example, `"unitless"`)                              |
 | `whole_blood_radioactivity`  | REQUIRED if `WholeBloodAvail` is `true`                     | Radioactivity in whole blood samples                                              | Unit of radioactivity measurements in whole blood samples (for example, `"kBq/mL"`) |
 
+{{ MACROS___make_columns_table(
+   {
+      "time": "REQUIRED",
+      "plasma_radioactivity": "REQUIRED if `PlasmaAvail` is `true`",
+      "metabolite_parent_fraction": "REQUIRED if `MetaboliteAvail` is `true`",
+      "metabolite_polar_fraction": "RECOMMENDED if `MetaboliteAvail` is `true`",
+      "hplc_recovery_fractions": "REQUIRED if `MetaboliteRecoveryCorrectionApplied` is `true`",
+      "whole_blood_radioactivity": "REQUIRED if `WholeBloodAvail` is `true`",
+   }
+) }}
+
 As with all [tabular files](../02-common-principles.md#tabular-files),
 additional columns MAY be defined in `_blood.json`.
 For clarity, it is RECOMMENDED to include the above column definitions in `_blood.json`,

src/05-derivatives/03-imaging.md

@@ -448,6 +448,16 @@ These TSV lookup tables contain the following columns:
 | color           | OPTIONAL              | Hexadecimal. Label color for visualization                    |
 | mapping         | OPTIONAL              | Corresponding integer label in the standard BIDS label lookup |
 
+{{ MACROS___make_columns_table(
+   {
+      "index": "REQUIRED",
+      "name_segmentations": "REQUIRED",
+      "abbreviation": "OPTIONAL",
+      "color": "OPTIONAL",
+      "mapping": "OPTIONAL",
+   }
+) }}
+
 An example, custom `dseg.tsv` that defines three labels:
 
 ```Text