From 154e9384052ed81df3755b63d912dc6fef7acfbe Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Thu, 20 Oct 2022 16:59:53 -0400
Subject: [PATCH] ENH: Introduce GIFTI and CIFTI-2 formats in derivatives

---
 src/02-common-principles.md           |  2 +-
 src/05-derivatives/01-introduction.md | 68 +++++++++++++++++++++++++++
 2 files changed, 69 insertions(+), 1 deletion(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 8fb609a526..67e9bc287c 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -363,7 +363,7 @@ In particular, if a BIDS dataset contains a `derivatives/` subdirectory,
 the contents of that directory may be a heterogeneous mix of BIDS Derivatives
 datasets and non-compliant derivatives.
 
-## File Formation specification
+## File format specification
 
 ### Imaging files
 
diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index 195422f9e0..ddd2ecb51c 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -70,6 +70,68 @@ in [Derived dataset and pipeline description][derived-dataset-description].
     For example, if a summary statistic is derived from a given task, the file
     name SHOULD contain [`_task-<label>`](../appendices/entities.md#task).
 
+## File format specification
+
+Derived data may be resampled into structures that are not well-handled by the
+raw data formats.
+In this section, we describe standard formats that SHOULD be adhered to when
+appropriate, and the extensions they should have.
+
+### GIFTI Surface Data Format
+
+The [GIFTI][] format is an XML-based structure containing one or more data arrays,
+and is well-suited to describing surface geometry and parcellations.
+
+The following extension table is reproduced in part from Section 9.0 of the
+[GIFTI specification][], indicating the expected extensions of different data arrays
+or combinations of data arrays.
+
+| Intent             | Extension     |
+|--------------------|---------------|
+| Coordinates        | `.coord.gii`  |
+| Functional         | `.func.gii`   |
+| Labels             | `.label.gii`  |
+| RGB or RGBA        | `.rgba.gii`   |
+| Shape              | `.shape.gii`  |
+| Surface            | `.surf.gii`   |
+| Tensors            | `.tensor.gii` |
+| Time Series        | `.time.gii`   |
+| Topology           | `.topo.gii`   |
+| Vector             | `.vector.gii` |
+
+Unless otherwise stated, bare `.gii` extensions SHOULD NOT be used
+for GIFTI files.
+
+### CIFTI-2 Connectivity File Formats
+
+The [CIFTI-2][] family of connectivity file formats are NIfTI-2 files with an
+XML header extension describing up to three axes in the NIfTI data array.
+The NIfTI intent code indicates the type of data indicated in the array,
+and corresponds to a sequence of axes.
+
+For example, the `NIFTI_INTENT_CONNECTIVITY_DENSE_SERIES` indicates that
+the first axis has type `CIFTI_INDEX_TYPE_SERIES` and the second axis has
+type `CIFTI_INDEX_TYPE_BRAIN_MODELS`.
+The corresponding file extension is `.dtseries.nii`.
+
+The following tables is reproduced in part from Appendix A of the
+[CIFTI-2 Connectivity File Formats Appendices][].
+
+| NIfTI Intent Code                              | Extension       |
+|------------------------------------------------|-----------------|
+| `NIFTI_INTENT_CONNECTIVITY_DENSE`              | `.dconn.nii`    |
+| `NIFTI_INTENT_CONNECTIVITY_DENSE_SERIES`       | `.dtseries.nii` |
+| `NIFTI_INTENT_CONNECTIVITY_PARCELLATED`        | `.pconn.nii`    |
+| `NIFTI_INTENT_CONNECTIVITY_PARCELLATED_SERIES` | `.ptseries.nii` |
+| `NIFTI_INTENT_CONNECTIVITY_DENSE_TRAJECTORY`   | `.dtraj.nii`    |
+| `NIFTI_INTENT_CONNECTIVITY_DENSE_SCALARS`      | `.dscalar.nii`  |
+| `NIFTI_INTENT_CONNECTIVITY_DENSE_LABELS`       | `.dlabel.nii`   |
+| `NIFTI_INTENT_CONNECTIVITY_PARCELLATED_SCALAR` | `.pscalar.nii`  |
+
+Unless otherwise stated, bare `.nii` extensions SHOULD NOT be used
+for CIFTI-2 files.
+
+
 <!-- Link Definitions -->
 
 [definitions]: ../02-common-principles.md#definitions
@@ -77,3 +139,9 @@ in [Derived dataset and pipeline description][derived-dataset-description].
 [storage]: ../02-common-principles.md#storage-of-derived-datasets
 
 [derived-dataset-description]: ../03-modality-agnostic-files.md#derived-dataset-and-pipeline-description
+
+[GIFTI]: https://www.nitrc.org/projects/gifti/
+[CIFTI-2]: https://www.nitrc.org/projects/cifti/
+
+[GIFTI specification]: https://www.nitrc.org/frs/download.php/2871/GIFTI_Surface_Format.pdf
+[CIFTI-2 Connectivity File Formats Appendices]: https://www.nitrc.org/forum/attachment.php?attachid=342&group_id=454&forum_id=1955