From bae27717de5941282b9386807e6b392cded55398 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Tue, 23 Jun 2020 15:54:34 -0400
Subject: [PATCH 01/13] Import functional derivatives from gh-207

---
 mkdocs.yml                                   |   1 +
 src/derivatives/05-functional-derivatives.md | 386 +++++++++++++++++++
 2 files changed, 387 insertions(+)
 create mode 100644 src/derivatives/05-functional-derivatives.md

diff --git a/mkdocs.yml b/mkdocs.yml
index 1a24697360..9702b562e2 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -22,6 +22,7 @@ nav:
         - BIDS Derivatives: derivatives/introduction.md
         - Common data types and metadata: derivatives/common-data-types.md
         - Imaging data types: derivatives/imaging.md
+        - Functional derivatives: derivatives/05-functional-derivatives.md
       - Longitudinal and multi-site studies: longitudinal-and-multi-site-studies.md
       - Glossary: glossary.md
       - BIDS Extension Proposals: extensions.md
diff --git a/src/derivatives/05-functional-derivatives.md b/src/derivatives/05-functional-derivatives.md
new file mode 100644
index 0000000000..d3748f84eb
--- /dev/null
+++ b/src/derivatives/05-functional-derivatives.md
@@ -0,0 +1,386 @@
+# Functional derivatives
+
+## Functional derivatives maps
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+            <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.nii[.gz]
+            <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.json
+```
+
+for example:
+
+```Text
+pipeline1/
+    sub-001/
+        func/
+            sub-001_task-rest_run-1_space-MNI305_mean.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_mean.json
+```
+
+The following table lists allowed suffixes and their corresponding measures:
+
+| `<suffix>`       | Measure                                                          |
+| ---------------- | ---------------------------------------------------------------- |
+| `mean`           | Mean across the temporal/4th dimension of the data               |
+| `std`            | Standard deviation across the temporal/4th dimension of the data |
+| `tsnr`           | Temporal SNR (i.e. mean / std)                                   |
+| `sfs`            | Signal fluctuation sensitivity                                   |
+| `alff`           | Amplitude low frequency fluctuations                             |
+| `falff`          | Fractional amplitude of low frequency fluctuations               |
+| `reho`           | Regional homogeneity (voxelwise only)                            |
+| `dcb`, `dcw`     | Voxelwise degree centrality binary and weighted                  |
+| `ecb`, `ecw`     | Voxelwise eigenvector centrality binary and weighted             |
+| `lfcdb`, `lfcdw` | Local functional connectivity density                            |
+| `vmhc`           | Voxel mirrored homotopic connectivity                            |
+
+The following metadata JSON fields are valid for derivative maps:
+
+| Key name       | Description                                                               | Required for suffix        |
+| -------------- | ------------------------------------------------------------------------- | -------------------------- |
+| BandpassFilter | String describing all relevant parameters of the applied bandpass filter. | `alff`, `falff`            |
+| Neighborhood   | String describing neighborhood for regional measures.                     | `reho`                     |
+| Threshold      | String describing threshold used for determining graph edges.             | `dcb`, `dcw`, `ecb`, `ecw` |
+| Method         | String describing method used to calculate measure.                       | `dcb`, `dcw`, `ecb`, `ecw` |
+
+## Time series
+
+A time series is a chronologically ordered series of numeric values.
+Time series will generally be stored as tables, with a row of column headers
+indicating the name of the series.
+In the case where every voxel has a time series, then the data should be stored
+in a 4D NIfTI file.
+
+All time series files MUST be accompanied by a data dictionary in JSON format,
+consistent with the format described in
+[Common principles](../02-common-principles.md#tabular-files), which describes
+metadata for each column name.
+In the case of NIfTI time series files, the notion of column name does not
+apply, so column-level metadata may be applied to the entire file.
+In addition, the following fields apply to the entire file in all cases:
+
+| Field name        | Definition                                                                                                                                                   |
+| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SamplingFrequency | REQUIRED. Sampling frequency (in Hz) of all columns in the file. Special value `"TR"` indicates one sample per volume of a corresponding BOLD series.        |
+| StartTime         | OPTIONAL. Start time in seconds in relation to the start of acquisition of the first volume in the corresponding imaging file (negative values are allowed). |
+
+Note that there are several differences with these fields in
+[Physiological and other continuous recordings](../04-modality-specific-files/06-physiological-and-other-continuous-recordings.md).
+The `"TR"` sampling frequency serves to indicate that no resampling is needed
+to use the series as a regressor for BOLD data, including BOLD series with
+non-uniform sampling, such as clustered sparse acquisition.
+`StartTime` is assumed to be 0 and therefore not mandatory.
+Additionally, because time series TSV files have column headers, the `Columns`
+field is omitted.
+
+### General time series
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+	        <source_keywords>[_desc-<label>]_timeseries.tsv
+	        <source_keywords>[_desc-<label>]_timeseries.json
+```
+
+for example:
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_desc-confounds_timeseries.tsv
+        sub-001_task-rest_run-1_desc-confounds_timeseries.json
+```
+
+Any time series with common timing information may be stored in a `timeseries`
+file.
+If a time series is specified in another sub-section, then any additional
+required metadata MUST be stored in the JSON description of the column.
+
+#### Column names
+
+Column names are unique alphanumeric values that are defined in a relevant JSON
+sidecar file. For a series of related columns, it is RECOMMENDED to use
+zero-based indexing as a suffix. For example, the first six aCompCor components
+may be named `a_comp_cor_00` ... `a_comp_cor_05`. Custom column names must not
+conflict with reserved names specified in this document.
+
+Reserved names are specified in the remaining subsections.
+
+#### Time series transformations
+
+Any column may have the following suffixes appended to indicate transformations
+applied to the original time series data:
+
+| Transformation | Description                                                                 |
+| -------------- | --------------------------------------------------------------------------- |
+| `_shift_back`  | The time series has been lagged by one TR. `x_shift_back[i] = x[i-1]`       |
+| `_dt`          | The discrete first derivative of the time series. `x_dt[i] = x[i+1] - x[i]` |
+| `_sq`          | The square of the time series                                               |
+| `_var_norm`    | The time series has been variance normalized                                |
+| `_centered`    | The time series has had its mean subtracted                                 |
+
+For example, `rot_z_shift_back_sq` means the square of the lagged version of the
+Z rotation (see [Motion-related time series](#motion-related-time-series)).
+
+### ROI-based time series extraction
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+            <source_keywords>[_atlas-<atlas_label>][_desc-<label>]_timeseries.<tsv|nii[.gz]>
+            <source_keywords>[_atlas-<atlas_label>][_desc-<label>]_timeseries.json
+```
+
+for example:
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_atlas-AAL_timeseries.tsv
+        sub-001_task-rest_run-1_atlas-AAL_timeseries.json
+        sub-001_task-rest_run-1_desc-anaticor_timeseries.nii.gz
+        sub-001_task-rest_run-1_desc-anaticor_timeseries.json
+```
+
+ROI-based time series will generally be stored as tables, with a row of column
+headers indicating the name of the time series.
+In the case where every voxel has a time series (i.e., voxel-wise regressors,
+as in ANATICOR), then the time series should be saved as a NIfTI file.
+
+#### Column metadata special fields
+
+Atlas (optional) - A label indicating an atlas that defines a region or set of
+regions in the volume. An atlas may be three- or four-dimensional, which affects
+the interpretation of the roi index.
+
+ROI (optional) - For 3D atlases, the ROI label should be numeric, corresponding
+to the value of the voxels in the ROI. For 4D atlases, the ROI label should be
+numeric, corresponding to the volume index containing the ROI mask. The
+following special labels correspond to common ROIs that may be defined by many
+atlases or segmentation algorithms:
+
+| ROI Value      | Description                                                                            |
+| -------------- | -------------------------------------------------------------------------------------- |
+| WhiteMatter    | Signal derived from white matter ROI.                                                  |
+| CSF            | Signal derived from cerebro-spinal fluid ROI.                                          |
+| Background     | Signal derived from background (out of brain) ROI.                                     |
+| GrayMatter     | Signal derived from gray matter ROI.                                                   |
+| Ventricles     | Signal derived from ventricles ROI.                                                    |
+| CircleOfWillis | Signal derived from circle of Willis ROI.                                              |
+| GlobalSignal   | Vector of mean values within the brain mask. Can be used for Global Signal Regression. |
+
+#### Column names
+
+Column names are unique alphanumeric values that are defined in a relevant JSON
+sidecar file. A naming convention might be to concatenate the atlas, ROI index,
+summarization method (defined below) and transformations (see [Time series
+transformations](#time-series-transformations)) using snake case. For example,
+`harvard_oxford_cortical_4_PC` could indicate ROI 4 of the Harvard-Oxford
+cortical atlas, summarized by taking the first principal component.
+
+#### Summarization methods
+
+To indicate the summarization method applied to construct a single time series
+for an ROI, the following column suffixes are defined:
+
+| Column suffix | Description of the transformation                                                                                                                       |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `_mean`       | The mean of voxel time series                                                                                                                           |
+| `_median`     | The median of voxel time series                                                                                                                         |
+| `_pc[_<x>]`   | The ith eigenvariate from principal component analysis, where `x` is 0 indexed. If `x` is not specified, the first component is implied (i.e., `pc_0`). |
+| `_spat_reg`   | Spatial regression                                                                                                                                      |
+
+Example:
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_timeseries.tsv
+```
+
+```Text
+white_matter_mean global_signal_mean ventricles_mean
+12                98                 11
+11                34                 53
+54                34                 34
+```
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_timeseries.json
+```
+
+```JSON
+{
+    "SamplingFrequency": "TR",
+    "white_matter_mean": {
+        "ROI": "WhiteMatter"
+    },
+    "global_signal_mean": {
+        "ROI": "GlobalSignal"
+    },
+    "ventricles_mean": {
+        "ROI": "Ventricles"
+    }
+}
+```
+
+### Motion-related time series
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+    func/
+        <source_keywords>[_desc-<label>]_motion.tsv
+        <source_keywords>[_desc-<label>]_motion.json
+```
+
+#### Column names
+
+The six basic motion parameters derived from motion correction have the
+following names and units:
+
+| Column name                     | Units   | Description            |
+| ------------------------------- | ------- | ---------------------- |
+| `trans_x`, `trans_y`, `trans_z` | mm      | Translation parameters |
+| `rot_x`, `rot_y`, `rot_z`       | radians | Rotation parameters    |
+
+Transformations (see [Time series
+transformations](#time-series-transformations)) of motion parameters may be
+included in the same file.
+For example, `rot_z_shift_back_sq` means square of the lagged version of Z
+rotation.
+
+The following columns indicate summarized motion, as defined in the
+corresponding references:
+
+| Column name              | Units | Description                                                         |
+| ------------------------ | ----- | ------------------------------------------------------------------- |
+| `framewise_displacement` | mm    | Framewise displacement (Power, et al., 2012)                        |
+| `rmsd`                   | mm    | Root mean square deviation (Jenkinson, 1999)                        |
+| `rms`                    | mm    | Root mean square of translation parameters (Van Dijk, et al., 2012) |
+
+### Temporal outlier masks
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+	        <source_keywords>[_desc-<label>]_outliers.tsv
+            <source_keywords>[_desc-<label>]_outliers.json
+```
+
+Outlier masks are columns of zeros (0), with ones (1) indicating volumes that
+have been identified as outliers by some method.
+
+#### Column names
+
+Column names for outliers correspond to the type of outlier or method for
+identifying the outlier. Column names should take the form `method[XX]`, where
+`XX` is an optional index.
+
+For example, if a BOLD series included two initial dummy scans,
+`non_steady_state` may be a column with a 1 for the first two volumes, or
+`non_steady_state_00` and `non_steady_state_01` may be columns with a 1 in the
+first and second position, respectively.
+
+The following methods are defined as reserved words:
+
+| Column name            | Description                                              |
+| ---------------------- | -------------------------------------------------------- |
+| `non_steady_state_<x>` | Initial non-steady-state volumes. One column per volume. |
+
+### Other time series
+
+Time series that are not otherwise specified MUST be placed in a
+`_timeseries.tsv` file (see [General time series](#general-time-series)).
+
+#### Column names
+
+The following time series are defined as reserved words:
+
+| Column name    | Description                                           |
+| -------------- | ----------------------------------------------------- |
+| `dvars`        | Change in variance (Brett, 2006, Power, et al., 2012) |
+| `std_dvars`    | Standardized DVARS (Nichols, 2013)                    |
+| `cosine_<X>`   | Discrete cosine basis vectors                         |
+| `legendre_<X>` | Legendre polynomial basis vectors                     |
+
+### Spatiotemporal decompositions
+
+Template:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        func/
+            <source_keywords>[_desc-<label>]_<mixing|components>.tsv
+            <source_keywords>[_desc-<label>]_<mixing|components>.nii.gz
+            <source_keywords>[_desc-<label>]_decomposition.json
+```
+
+for example:
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_desc-MELODIC_components.nii.gz
+        sub-001_task-rest_run-1_desc-MELODIC_mixing.tsv
+        sub-001_task-rest_run-1_desc-MELODIC_decomposition.json
+```
+
+```Text
+sub-001/
+    func/
+        sub-001_task-rest_run-1_desc-tICA_mixing.nii.gz
+        sub-001_task-rest_run-1_desc-tICA_components.tsv
+        sub-001_task-rest_run-1_desc-tICA_decomposition.json
+```
+
+Spatiotemporal decompositions produce either spatial or temporal components,
+along with conjugate mixing matrices that can be represented as time series and
+spatial maps, respectively. The combination of suffix and extension indicates
+which class of algorithm produced the outputs.
+
+Mixing matrices may be omitted for algorithms that are temporal decompositions
+with no spatial component, such as CompCor variants.
+
+Spatiotemporal decomposition files MUST be accompanied by a data dictionary in
+JSON format, consistent with Raw-BIDS section 4.2, which describes metadata for
+each column name. In addition to column names, the following MANDATORY field is
+added:
+
+| Key name | Description                                           |
+| -------- | ----------------------------------------------------- |
+| Method   | REQUIRED. Algorithm name and (if applicable) version. |
+
+#### Column names
+
+Column names in spatiotemporal decompositions take the form of
+`<decomposition>_<index>`, where `<decomposition>` is the name of the
+decomposition algorithm, and `<index>` is a numeric identifier. Indices SHOULD
+start at 0. If there is a natural ordering, indices should reflect that
+ordering. For example, the aCompCor component which explains the most variance
+should be named `a_comp_cor_00`.
+
+The following reserved words indicate common algorithms:
+
+| Column name              | Description                                                                                                                                                                                                |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[a|t|w|c]_comp_cor_<x>` | CompCor (Behzadi, et al., 2007) calculated with voxels chosen based on: `a`: anatomically derived ROIs (white matter and CSF), `t`: temporal variance, `w`: white matter voxels only, `c`: CSF voxels only |
+| `melodic_<x>`            | Columns from the mixing matrix in FSL MELODIC                                                                                                                                                              |

From 78cfcfe02945be3d60e292484702005f21bf2ddb Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Tue, 30 Jun 2020 16:39:49 -0400
Subject: [PATCH 02/13] STY: Fix up template naming and spacing

---
 src/derivatives/05-functional-derivatives.md | 40 ++++++++++----------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/src/derivatives/05-functional-derivatives.md b/src/derivatives/05-functional-derivatives.md
index d3748f84eb..ce0e52bfaf 100644
--- a/src/derivatives/05-functional-derivatives.md
+++ b/src/derivatives/05-functional-derivatives.md
@@ -6,10 +6,10 @@ Template:
 
 ```Text
 <pipeline_name>/
-    sub-<participant_label>/
+    sub-<label>/
         func/
-            <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.nii[.gz]
-            <source_keywords>[_space-<space>][_desc-<label>]_<suffix>.json
+            <source_entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.{nii[.gz],gii,dscalar.nii}
+            <source_entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.json
 ```
 
 for example:
@@ -83,10 +83,10 @@ Template:
 
 ```Text
 <pipeline_name>/
-    sub-<participant_label>/
+    sub-<label>/
         func/
-	        <source_keywords>[_desc-<label>]_timeseries.tsv
-	        <source_keywords>[_desc-<label>]_timeseries.json
+            <source_entities>[_desc-<label>]_timeseries.tsv
+            <source_entities>[_desc-<label>]_timeseries.json
 ```
 
 for example:
@@ -135,10 +135,10 @@ Template:
 
 ```Text
 <pipeline_name>/
-    sub-<participant_label>/
+    sub-<label>/
         func/
-            <source_keywords>[_atlas-<atlas_label>][_desc-<label>]_timeseries.<tsv|nii[.gz]>
-            <source_keywords>[_atlas-<atlas_label>][_desc-<label>]_timeseries.json
+            <source_entities>[_atlas-<label>][_desc-<label>]_timeseries.<tsv|nii[.gz]>
+            <source_entities>[_atlas-<label>][_desc-<label>]_timeseries.json
 ```
 
 for example:
@@ -242,10 +242,10 @@ Template:
 
 ```Text
 <pipeline_name>/
-    sub-<participant_label>/
-    func/
-        <source_keywords>[_desc-<label>]_motion.tsv
-        <source_keywords>[_desc-<label>]_motion.json
+    sub-<label>/
+        func/
+            <source_entities>[_desc-<label>]_motion.tsv
+            <source_entities>[_desc-<label>]_motion.json
 ```
 
 #### Column names
@@ -279,10 +279,10 @@ Template:
 
 ```Text
 <pipeline_name>/
-    sub-<participant_label>/
+    sub-<label>/
         func/
-	        <source_keywords>[_desc-<label>]_outliers.tsv
-            <source_keywords>[_desc-<label>]_outliers.json
+            <source_entities>[_desc-<label>]_outliers.tsv
+            <source_entities>[_desc-<label>]_outliers.json
 ```
 
 Outlier masks are columns of zeros (0), with ones (1) indicating volumes that
@@ -327,11 +327,11 @@ Template:
 
 ```Text
 <pipeline_name>/
-    sub-<participant_label>/
+    sub-<label>/
         func/
-            <source_keywords>[_desc-<label>]_<mixing|components>.tsv
-            <source_keywords>[_desc-<label>]_<mixing|components>.nii.gz
-            <source_keywords>[_desc-<label>]_decomposition.json
+            <source_entities>[_desc-<label>]_<mixing|components>.tsv
+            <source_entities>[_desc-<label>]_<mixing|components>.nii.gz
+            <source_entities>[_desc-<label>]_decomposition.json
 ```
 
 for example:

From 28ca74b357ecfbc47172d05519b1446a8a1b140e Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Tue, 30 Jun 2020 16:40:02 -0400
Subject: [PATCH 03/13] Minor wording changes

---
 src/derivatives/05-functional-derivatives.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/derivatives/05-functional-derivatives.md b/src/derivatives/05-functional-derivatives.md
index ce0e52bfaf..8ff7c66931 100644
--- a/src/derivatives/05-functional-derivatives.md
+++ b/src/derivatives/05-functional-derivatives.md
@@ -2,6 +2,9 @@
 
 ## Functional derivatives maps
 
+A derivative map is a measure derived from a functional series, mapped onto spatial
+locations as defined by voxels in a volume or vertices on a surface.
+
 Template:
 
 ```Text
@@ -52,14 +55,15 @@ The following metadata JSON fields are valid for derivative maps:
 A time series is a chronologically ordered series of numeric values.
 Time series will generally be stored as tables, with a row of column headers
 indicating the name of the series.
-In the case where every voxel has a time series, then the data should be stored
-in a 4D NIfTI file.
+In the case where the time series varies spatially, the data SHOULD be stored in
+an appropriate file, such as a 4D NIfTI file, a `.time.gii` GIFTI file,
+or a `.dtseries.nii` CIFTI-2 file.
 
 All time series files MUST be accompanied by a data dictionary in JSON format,
 consistent with the format described in
 [Common principles](../02-common-principles.md#tabular-files), which describes
 metadata for each column name.
-In the case of NIfTI time series files, the notion of column name does not
+In the case of spatial time series files, the notion of column name does not
 apply, so column-level metadata may be applied to the entire file.
 In addition, the following fields apply to the entire file in all cases:
 
@@ -73,7 +77,7 @@ Note that there are several differences with these fields in
 The `"TR"` sampling frequency serves to indicate that no resampling is needed
 to use the series as a regressor for BOLD data, including BOLD series with
 non-uniform sampling, such as clustered sparse acquisition.
-`StartTime` is assumed to be 0 and therefore not mandatory.
+`StartTime` is assumed to be 0 and therefore OPTIONAL.
 Additionally, because time series TSV files have column headers, the `Columns`
 field is omitted.
 

From d3104f52b529a84a2af8322000cba67514c68ac5 Mon Sep 17 00:00:00 2001
From: Ross Blair <rosswilsonblair@gmail.com>
Date: Mon, 15 Aug 2022 14:00:21 -0500
Subject: [PATCH 04/13] Update src/05-derivatives/05-functional-derivatives.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>
---
 src/derivatives/05-functional-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/derivatives/05-functional-derivatives.md b/src/derivatives/05-functional-derivatives.md
index 8ff7c66931..d453a91c65 100644
--- a/src/derivatives/05-functional-derivatives.md
+++ b/src/derivatives/05-functional-derivatives.md
@@ -70,7 +70,7 @@ In addition, the following fields apply to the entire file in all cases:
 | Field name        | Definition                                                                                                                                                   |
 | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | SamplingFrequency | REQUIRED. Sampling frequency (in Hz) of all columns in the file. Special value `"TR"` indicates one sample per volume of a corresponding BOLD series.        |
-| StartTime         | OPTIONAL. Start time in seconds in relation to the start of acquisition of the first volume in the corresponding imaging file (negative values are allowed). |
+| StartTime         | OPTIONAL. Start time (in seconds) in relation to the start of acquisition of the first volume in the corresponding imaging file (negative values are allowed). |
 
 Note that there are several differences with these fields in
 [Physiological and other continuous recordings](../04-modality-specific-files/06-physiological-and-other-continuous-recordings.md).

From bc74a6b4b88b344fee101fea1e3381a08189e598 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 28 Jun 2023 10:25:15 -0400
Subject: [PATCH 05/13] Apply non-numbered file naming scheme

---
 mkdocs.yml                                                    | 2 +-
 ...05-functional-derivatives.md => functional-derivatives.md} | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)
 rename src/derivatives/{05-functional-derivatives.md => functional-derivatives.md} (98%)

diff --git a/mkdocs.yml b/mkdocs.yml
index 9702b562e2..9d0b1eff25 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -22,7 +22,7 @@ nav:
         - BIDS Derivatives: derivatives/introduction.md
         - Common data types and metadata: derivatives/common-data-types.md
         - Imaging data types: derivatives/imaging.md
-        - Functional derivatives: derivatives/05-functional-derivatives.md
+        - Functional derivatives: derivatives/functional-derivatives.md
       - Longitudinal and multi-site studies: longitudinal-and-multi-site-studies.md
       - Glossary: glossary.md
       - BIDS Extension Proposals: extensions.md
diff --git a/src/derivatives/05-functional-derivatives.md b/src/derivatives/functional-derivatives.md
similarity index 98%
rename from src/derivatives/05-functional-derivatives.md
rename to src/derivatives/functional-derivatives.md
index d453a91c65..0253b580f1 100644
--- a/src/derivatives/05-functional-derivatives.md
+++ b/src/derivatives/functional-derivatives.md
@@ -61,7 +61,7 @@ or a `.dtseries.nii` CIFTI-2 file.
 
 All time series files MUST be accompanied by a data dictionary in JSON format,
 consistent with the format described in
-[Common principles](../02-common-principles.md#tabular-files), which describes
+[Common principles](../common-principles.md#tabular-files), which describes
 metadata for each column name.
 In the case of spatial time series files, the notion of column name does not
 apply, so column-level metadata may be applied to the entire file.
@@ -73,7 +73,7 @@ In addition, the following fields apply to the entire file in all cases:
 | StartTime         | OPTIONAL. Start time (in seconds) in relation to the start of acquisition of the first volume in the corresponding imaging file (negative values are allowed). |
 
 Note that there are several differences with these fields in
-[Physiological and other continuous recordings](../04-modality-specific-files/06-physiological-and-other-continuous-recordings.md).
+[Physiological and other continuous recordings](../modality-specific-files/physiological-and-other-continuous-recordings.md).
 The `"TR"` sampling frequency serves to indicate that no resampling is needed
 to use the series as a regressor for BOLD data, including BOLD series with
 non-uniform sampling, such as clustered sparse acquisition.

From 1e363e9fa7725b8b6dd961311fc64ecc12769774 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 28 Jun 2023 11:33:45 -0400
Subject: [PATCH 06/13] Update functional maps to take the form
 `stat-<label>_<source_suffix>map`

---
 src/derivatives/functional-derivatives.md     | 42 +++++++++++++------
 src/schema/objects/metadata.yaml              | 21 ++++++++++
 src/schema/objects/suffixes.yaml              | 11 +++++
 .../rules/sidecars/derivatives/fmri.yaml      | 41 ++++++++++++++++++
 4 files changed, 102 insertions(+), 13 deletions(-)
 create mode 100644 src/schema/rules/sidecars/derivatives/fmri.yaml

diff --git a/src/derivatives/functional-derivatives.md b/src/derivatives/functional-derivatives.md
index 0253b580f1..8c5422c618 100644
--- a/src/derivatives/functional-derivatives.md
+++ b/src/derivatives/functional-derivatives.md
@@ -1,4 +1,7 @@
-# Functional derivatives
+# Functional MRI derivatives
+
+This section describes files deriving from functional MRI (fMRI) recordings,
+namely BOLD and CBV series.
 
 ## Functional derivatives maps
 
@@ -11,8 +14,8 @@ Template:
 <pipeline_name>/
     sub-<label>/
         func/
-            <source_entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.{nii[.gz],gii,dscalar.nii}
-            <source_entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.json
+            <source_entities>[_space-<space>][_res-<label>][_den-<label>][_stat-<label>][_desc-<label>]_<suffix>.{nii[.gz],func.gii,dscalar.nii}
+            <source_entities>[_space-<space>][_res-<label>][_den-<label>][_stat-<label>][_desc-<label>]_<suffix>.json
 ```
 
 for example:
@@ -21,13 +24,20 @@ for example:
 pipeline1/
     sub-001/
         func/
-            sub-001_task-rest_run-1_space-MNI305_mean.nii.gz
-            sub-001_task-rest_run-1_space-MNI305_mean.json
+            sub-001_task-rest_run-1_space-MNI305_stat-mean_boldmap.nii.gz
+            sub-001_task-rest_run-1_space-MNI305_stat-mean_boldmap.json
 ```
 
-The following table lists allowed suffixes and their corresponding measures:
+Suffixes take the form `<source_suffix>map`:
+
+| Original suffix | Derivative map suffix |
+| --------------- | --------------------- |
+| `bold`          | `boldmap`             |
+| `cbv`           | `cbvmap`              |
+
+The following table lists allowed labels for the `stat` entity and their corresponding measures:
 
-| `<suffix>`       | Measure                                                          |
+| `stat-<label>`   | Measure                                                          |
 | ---------------- | ---------------------------------------------------------------- |
 | `mean`           | Mean across the temporal/4th dimension of the data               |
 | `std`            | Standard deviation across the temporal/4th dimension of the data |
@@ -41,14 +51,20 @@ The following table lists allowed suffixes and their corresponding measures:
 | `lfcdb`, `lfcdw` | Local functional connectivity density                            |
 | `vmhc`           | Voxel mirrored homotopic connectivity                            |
 
+### Sidecar JSON (`*_boldmap.json`/`*_cbvmap.json`)
+
 The following metadata JSON fields are valid for derivative maps:
 
-| Key name       | Description                                                               | Required for suffix        |
-| -------------- | ------------------------------------------------------------------------- | -------------------------- |
-| BandpassFilter | String describing all relevant parameters of the applied bandpass filter. | `alff`, `falff`            |
-| Neighborhood   | String describing neighborhood for regional measures.                     | `reho`                     |
-| Threshold      | String describing threshold used for determining graph edges.             | `dcb`, `dcw`, `ecb`, `ecw` |
-| Method         | String describing method used to calculate measure.                       | `dcb`, `dcw`, `ecb`, `ecw` |
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table("derivatives.fmri.FunctionalMapFields") }}
+
 
 ## Time series
 
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index ea6e2fb5eb..c6a5bb0c49 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -1986,6 +1986,12 @@ MetaboliteRecoveryCorrectionApplied:
     If `true`, the `hplc_recovery_fractions` column MUST be present in the
     corresponding `*_blood.tsv` file.
   type: boolean
+Method:
+  name: Method
+  display_name: Method
+  description: |
+    Description of method used to calculate the measure contained in a file.
+  type: string
 MiscChannelCount:
   name: MiscChannelCount
   display_name: Misc Channel Count
@@ -2070,6 +2076,12 @@ NegativeContrast:
     usage of a contrast agent in conjunction with a T2\* weighted acquisition
     protocol.
   type: boolean
+Neighborhood:
+  name: Neighborhood
+  display_name: Neighborhood
+  description: |
+    A description of the neighborhood used for calculating regional measures.
+  type: string
 NIRSChannelCount:
   name: NIRSChannelCount
   display_name: NIRS Channel Count
@@ -3363,6 +3375,15 @@ TermURL:
     URL pointing to a formal definition of this type of data in an ontology
     available on the web.
   type: string
+Threshold:
+  name: Threshold
+  display_name: Threshold
+  description: |
+    String or number describing a threshold used to calculate the measure
+    contained in a file.
+  anyOf:
+    - type: number
+    - type: string
 TimeZero:
   name: TimeZero
   display_name: Time Zero
diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml
index caa943ee7c..aef736b201 100644
--- a/src/schema/objects/suffixes.yaml
+++ b/src/schema/objects/suffixes.yaml
@@ -529,11 +529,22 @@ bold:
   display_name: Blood-Oxygen-Level Dependent image
   description: |
     Blood-Oxygen-Level Dependent contrast (specialized T2\* weighting)
+boldmap:
+  value: boldmap
+  display_name: BOLD-derived map
+  description: |
+    Summary image derived from a blood-oxygenation-level-dependent (BOLD)
+    time series.
 cbv:
   value: cbv
   display_name: Cerebral blood volume image
   description: |
     Cerebral Blood Volume contrast (specialized T2\* weighting or difference between T1 weighted images)
+cbvmap:
+  value: cbvmap
+  display_name: CBV-derived map
+  description: |
+    Summary image derived from a cerebral blood volume (CBV) time series.
 channels:
   value: channels
   display_name: Channels File
diff --git a/src/schema/rules/sidecars/derivatives/fmri.yaml b/src/schema/rules/sidecars/derivatives/fmri.yaml
new file mode 100644
index 0000000000..dcec1ff312
--- /dev/null
+++ b/src/schema/rules/sidecars/derivatives/fmri.yaml
@@ -0,0 +1,41 @@
+---
+FunctionalMapFields:
+  selectors:
+    - dataset.dataset_description.DatasetType == "derivative"
+    - intersects([suffix], ["boldmap", "cbfmap"])
+    - intersects([extension], [".nii", ".nii.gz", ".func.gii", ".dscalar.nii"])
+  fields:
+    SoftwareFilters:
+      level: optional
+      level_addendum: required for `stat-alff` and `stat-falff`
+    Neighborhood:
+      level: optional
+      level_addendum: required for `stat-reho`
+    Threshold:
+      level: optional
+      level_addendum: required for `stat-{dcb,dcw,ecb,ecw}`
+    Method:
+      level: optional
+      level_addendum: required for `stat-{dcb,dcw,ecb,ecw}`
+
+ALFFFields:
+  selectors:
+    - $ref: rules.sidecars.derivatives.fmri.FunctionalMapFields
+    - intersects([entities.stat], ["alff", "falff"])
+  fields:
+    SoftwareFilters: required
+
+ReHoFields:
+  selectors:
+    - $ref: rules.sidecars.derivatives.fmri.FunctionalMapFields
+    - entities.stat == "reho"
+  fields:
+    Neighborhood: required
+
+CentralityFields:
+  selectors:
+    - $ref: rules.sidecars.derivatives.fmri.FunctionalMapFields
+    - intersects([entities.stat], ["dcb", "dcw", "ecb", "ecw"])
+  fields:
+    Threshold: required
+    Method: required

From 6fdc116e83c9578b0ba57a4140f2874e9a804d52 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 28 Jun 2023 11:37:37 -0400
Subject: [PATCH 07/13] .time.gii -> .func.gii, in keeping with common practice

---
 src/derivatives/functional-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/derivatives/functional-derivatives.md b/src/derivatives/functional-derivatives.md
index 8c5422c618..c0d5bf6193 100644
--- a/src/derivatives/functional-derivatives.md
+++ b/src/derivatives/functional-derivatives.md
@@ -72,7 +72,7 @@ A time series is a chronologically ordered series of numeric values.
 Time series will generally be stored as tables, with a row of column headers
 indicating the name of the series.
 In the case where the time series varies spatially, the data SHOULD be stored in
-an appropriate file, such as a 4D NIfTI file, a `.time.gii` GIFTI file,
+an appropriate file, such as a 4D NIfTI file, a `.func.gii` GIFTI file,
 or a `.dtseries.nii` CIFTI-2 file.
 
 All time series files MUST be accompanied by a data dictionary in JSON format,

From d82a2a856c56ce85eabc3be2591e6711828e4ab9 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 28 Jun 2023 11:41:42 -0400
Subject: [PATCH 08/13] STY: Remove latin abbreviation

---
 src/derivatives/functional-derivatives.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/derivatives/functional-derivatives.md b/src/derivatives/functional-derivatives.md
index c0d5bf6193..4f8f4e99e0 100644
--- a/src/derivatives/functional-derivatives.md
+++ b/src/derivatives/functional-derivatives.md
@@ -41,7 +41,7 @@ The following table lists allowed labels for the `stat` entity and their corresp
 | ---------------- | ---------------------------------------------------------------- |
 | `mean`           | Mean across the temporal/4th dimension of the data               |
 | `std`            | Standard deviation across the temporal/4th dimension of the data |
-| `tsnr`           | Temporal SNR (i.e. mean / std)                                   |
+| `tsnr`           | Temporal SNR (`mean / std`)                                      |
 | `sfs`            | Signal fluctuation sensitivity                                   |
 | `alff`           | Amplitude low frequency fluctuations                             |
 | `falff`          | Fractional amplitude of low frequency fluctuations               |
@@ -174,7 +174,7 @@ sub-001/
 
 ROI-based time series will generally be stored as tables, with a row of column
 headers indicating the name of the time series.
-In the case where every voxel has a time series (i.e., voxel-wise regressors,
+In the case where every voxel has a time series (that is, voxel-wise regressors,
 as in ANATICOR), then the time series should be saved as a NIfTI file.
 
 #### Column metadata special fields

From 707ee068f2661679af00c7cbc0bbf321e3aa2621 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 28 Jun 2023 11:53:05 -0400
Subject: [PATCH 09/13] STY: Fix remark complaints

---
 src/derivatives/functional-derivatives.md | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/src/derivatives/functional-derivatives.md b/src/derivatives/functional-derivatives.md
index 4f8f4e99e0..1c984fc1c1 100644
--- a/src/derivatives/functional-derivatives.md
+++ b/src/derivatives/functional-derivatives.md
@@ -65,7 +65,6 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_sidecar_table("derivatives.fmri.FunctionalMapFields") }}
 
-
 ## Time series
 
 A time series is a chronologically ordered series of numeric values.
@@ -83,9 +82,9 @@ In the case of spatial time series files, the notion of column name does not
 apply, so column-level metadata may be applied to the entire file.
 In addition, the following fields apply to the entire file in all cases:
 
-| Field name        | Definition                                                                                                                                                   |
-| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| SamplingFrequency | REQUIRED. Sampling frequency (in Hz) of all columns in the file. Special value `"TR"` indicates one sample per volume of a corresponding BOLD series.        |
+| Field name        | Definition                                                                                                                                                     |
+| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SamplingFrequency | REQUIRED. Sampling frequency (in Hz) of all columns in the file. Special value `"TR"` indicates one sample per volume of a corresponding BOLD series.          |
 | StartTime         | OPTIONAL. Start time (in seconds) in relation to the start of acquisition of the first volume in the corresponding imaging file (negative values are allowed). |
 
 Note that there are several differences with these fields in
@@ -400,7 +399,7 @@ should be named `a_comp_cor_00`.
 
 The following reserved words indicate common algorithms:
 
-| Column name              | Description                                                                                                                                                                                                |
-| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `[a|t|w|c]_comp_cor_<x>` | CompCor (Behzadi, et al., 2007) calculated with voxels chosen based on: `a`: anatomically derived ROIs (white matter and CSF), `t`: temporal variance, `w`: white matter voxels only, `c`: CSF voxels only |
-| `melodic_<x>`            | Columns from the mixing matrix in FSL MELODIC                                                                                                                                                              |
+| Column name                 | Description                                                                                                                                                                                                |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[a\|t\|w\|c]_comp_cor_<x>` | CompCor (Behzadi, et al., 2007) calculated with voxels chosen based on: `a`: anatomically derived ROIs (white matter and CSF), `t`: temporal variance, `w`: white matter voxels only, `c`: CSF voxels only |
+| `melodic_<x>`               | Columns from the mixing matrix in FSL MELODIC                                                                                                                                                              |

From 66e2baf107b61f1bad0b2ea62c7c474613ae2d84 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 28 Jun 2023 12:02:54 -0400
Subject: [PATCH 10/13] STY: Remove Latin, make _pc suffix clearer

---
 src/derivatives/functional-derivatives.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/derivatives/functional-derivatives.md b/src/derivatives/functional-derivatives.md
index 1c984fc1c1..8ff336b5b8 100644
--- a/src/derivatives/functional-derivatives.md
+++ b/src/derivatives/functional-derivatives.md
@@ -212,12 +212,12 @@ cortical atlas, summarized by taking the first principal component.
 To indicate the summarization method applied to construct a single time series
 for an ROI, the following column suffixes are defined:
 
-| Column suffix | Description of the transformation                                                                                                                       |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `_mean`       | The mean of voxel time series                                                                                                                           |
-| `_median`     | The median of voxel time series                                                                                                                         |
-| `_pc[_<x>]`   | The ith eigenvariate from principal component analysis, where `x` is 0 indexed. If `x` is not specified, the first component is implied (i.e., `pc_0`). |
-| `_spat_reg`   | Spatial regression                                                                                                                                      |
+| Column suffix | Description of the transformation                                                                                                                            |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `_mean`       | The mean of voxel time series                                                                                                                                |
+| `_median`     | The median of voxel time series                                                                                                                              |
+| `_pc[_<i>]`   | The `i`th eigenvariate from principal component analysis, where `i` is 0 indexed. If `i` is not specified, the first component is implied (that is, `pc_0`). |
+| `_spat_reg`   | Spatial regression                                                                                                                                           |
 
 Example:
 

From 3ab467abd2ef2d5f0128d80a2fec60cf1ddac28c Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 28 Jun 2023 12:41:19 -0400
Subject: [PATCH 11/13] FIX: Broken links break PDF builds

---
 src/derivatives/functional-derivatives.md | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/src/derivatives/functional-derivatives.md b/src/derivatives/functional-derivatives.md
index 8ff336b5b8..8b25d4bd9e 100644
--- a/src/derivatives/functional-derivatives.md
+++ b/src/derivatives/functional-derivatives.md
@@ -202,9 +202,9 @@ atlases or segmentation algorithms:
 
 Column names are unique alphanumeric values that are defined in a relevant JSON
 sidecar file. A naming convention might be to concatenate the atlas, ROI index,
-summarization method (defined below) and transformations (see [Time series
-transformations](#time-series-transformations)) using snake case. For example,
-`harvard_oxford_cortical_4_PC` could indicate ROI 4 of the Harvard-Oxford
+summarization method (defined below) and transformations
+(see [Time series transformations](#time-series-transformations)) using snake case.
+For example, `harvard_oxford_cortical_4_PC` could indicate ROI 4 of the Harvard-Oxford
 cortical atlas, summarized by taking the first principal component.
 
 #### Summarization methods
@@ -277,9 +277,8 @@ following names and units:
 | `trans_x`, `trans_y`, `trans_z` | mm      | Translation parameters |
 | `rot_x`, `rot_y`, `rot_z`       | radians | Rotation parameters    |
 
-Transformations (see [Time series
-transformations](#time-series-transformations)) of motion parameters may be
-included in the same file.
+Transformations (see [Time series transformations](#time-series-transformations))
+of motion parameters may be included in the same file.
 For example, `rot_z_shift_back_sq` means square of the lagged version of Z
 rotation.
 

From 94b946775f1f139288ce2efbe60b7fe65b8c8e05 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 28 Jun 2023 12:45:29 -0400
Subject: [PATCH 12/13] FIX: Lowercase pc

---
 src/derivatives/functional-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/derivatives/functional-derivatives.md b/src/derivatives/functional-derivatives.md
index 8b25d4bd9e..b4a5fd2883 100644
--- a/src/derivatives/functional-derivatives.md
+++ b/src/derivatives/functional-derivatives.md
@@ -204,7 +204,7 @@ Column names are unique alphanumeric values that are defined in a relevant JSON
 sidecar file. A naming convention might be to concatenate the atlas, ROI index,
 summarization method (defined below) and transformations
 (see [Time series transformations](#time-series-transformations)) using snake case.
-For example, `harvard_oxford_cortical_4_PC` could indicate ROI 4 of the Harvard-Oxford
+For example, `harvard_oxford_cortical_4_pc` could indicate ROI 4 of the Harvard-Oxford
 cortical atlas, summarized by taking the first principal component.
 
 #### Summarization methods

From 1c79cbc19f7ab9b99f38376978b37d78c8ce5759 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Mon, 21 Aug 2023 13:16:43 -0400
Subject: [PATCH 13/13] Update src/schema/rules/sidecars/derivatives/fmri.yaml

Co-authored-by: Remi Gau <remi_gau@hotmail.com>
---
 src/schema/rules/sidecars/derivatives/fmri.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/schema/rules/sidecars/derivatives/fmri.yaml b/src/schema/rules/sidecars/derivatives/fmri.yaml
index dcec1ff312..deda15d138 100644
--- a/src/schema/rules/sidecars/derivatives/fmri.yaml
+++ b/src/schema/rules/sidecars/derivatives/fmri.yaml
@@ -2,7 +2,7 @@
 FunctionalMapFields:
   selectors:
     - dataset.dataset_description.DatasetType == "derivative"
-    - intersects([suffix], ["boldmap", "cbfmap"])
+    - intersects([suffix], ["boldmap", "cbvmap"])
     - intersects([extension], [".nii", ".nii.gz", ".func.gii", ".dscalar.nii"])
   fields:
     SoftwareFilters: