From 17103abf2fdc466035113d529b0237c59d0b6653 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Boris=20Cl=C3=A9net?= <boris.clenet@inria.fr>
Date: Wed, 23 Apr 2025 09:40:21 +0200
Subject: [PATCH 01/11] Split modality agnostic files content into separate
 sections

---
 mkdocs.yml                                    |  15 +-
 src/modality-agnostic-files/code.md           |  16 ++
 .../data-description.md}                      | 233 +-----------------
 .../dataset-description.md                    | 213 ++++++++++++++++
 4 files changed, 237 insertions(+), 240 deletions(-)
 create mode 100644 src/modality-agnostic-files/code.md
 rename src/{modality-agnostic-files.md => modality-agnostic-files/data-description.md} (57%)
 create mode 100644 src/modality-agnostic-files/dataset-description.md

diff --git a/mkdocs.yml b/mkdocs.yml
index 1ec59b49f7..a19b5d5331 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -5,7 +5,10 @@ nav:
   - The BIDS Specification:
       - Introduction: introduction.md
       - Common principles: common-principles.md
-      - Modality agnostic files: modality-agnostic-files.md
+      - Modality agnostic files:
+          - Dataset description: modality-agnostic-files/dataset-description.md
+          - Data description: modality-agnostic-files/data-description.md
+          - Code: modality-agnostic-files/code.md
       - Modality specific files:
           - Magnetic Resonance Imaging: modality-specific-files/magnetic-resonance-imaging-data.md
           - Magnetoencephalography: modality-specific-files/magnetoencephalography.md
@@ -101,21 +104,15 @@ extra:
 
 extra_javascript:
   - js/jquery-3.6.0.min.js
-extra_css:
-  - css/tsv.css
 markdown_extensions:
   - toc:
       anchorlink: true
-  - attr_list
   - pymdownx.superfences:
       preserve_tabs: true
       custom_fences:
         - name: tsv
           class: tsv
           format: !!python/name:bidsschematools.render.tsv.fence
-        - name: tsvgz
-          class: tsv
-          format: !!python/name:bidsschematools.render.tsv.fence
   - admonition
   - pymdownx.details
 plugins:
@@ -132,7 +129,9 @@ plugins:
       redirect_maps:
         "01-introduction.md": "introduction.md"
         "02-common-principles.md": "common-principles.md"
-        "03-modality-agnostic-files.md": "modality-agnostic-files.md"
+        "03-modality-agnostic-files/01-modality-agnostic-files.md": "modality-agnostic-files/dataset-description.md"
+        "03-modality-agnostic-files/02-modality-agnostic-files.md": "modality-agnostic-files/data-description.md"
+        "03-modality-agnostic-files/03-modality-agnostic-files.md": "modality-agnostic-files/code.md"
         "04-modality-specific-files/01-magnetic-resonance-imaging-data.md": "modality-specific-files/magnetic-resonance-imaging-data.md"
         "04-modality-specific-files/02-magnetoencephalography.md": "modality-specific-files/magnetoencephalography.md"
         "04-modality-specific-files/03-electroencephalography.md": "modality-specific-files/electroencephalography.md"
diff --git a/src/modality-agnostic-files/code.md b/src/modality-agnostic-files/code.md
new file mode 100644
index 0000000000..0e894d06a7
--- /dev/null
+++ b/src/modality-agnostic-files/code.md
@@ -0,0 +1,16 @@
+# Code
+
+Template: `code/*`
+
+Source code of scripts that were used to prepare the dataset MAY be stored here.
+Examples include deidentification or defacing of the data, or
+the conversion from the format of the source data to the BIDS format
+(see [source vs. raw vs. derived data](./common-principles.md#source-vs-raw-vs-derived-data)).
+Extra care should be taken to avoid including original IDs or
+any identifiable information with the source code.
+There are no limitations or recommendations on the language and/or
+code organization of these scripts at the moment.
+
+<!-- Link Definitions -->
+
+[bids uris]: ./common-principles.md#bids-uri
diff --git a/src/modality-agnostic-files.md b/src/modality-agnostic-files/data-description.md
similarity index 57%
rename from src/modality-agnostic-files.md
rename to src/modality-agnostic-files/data-description.md
index 84df1a2dca..57fa736ceb 100644
--- a/src/modality-agnostic-files.md
+++ b/src/modality-agnostic-files/data-description.md
@@ -1,218 +1,4 @@
-# Modality agnostic files
-
-## Dataset description
-
-Templates:
-
--   `dataset_description.json`
--   `README[.md|.rst|.txt]`
--   `CITATION.cff`
--   `CHANGES`
--   `LICENSE[.md|.rst|.txt]`
-
-### `dataset_description.json`
-
-<!-- This block generates a description.
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___render_text("objects.files.dataset_description.description") }}
-
-Every dataset MUST include this file with the following fields:
-
-<!-- This block generates a metadata table.
-The definitions of these fields can be found in
-  src/schema/objects/metadata.yaml
-and a guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___make_metadata_table(
-   {
-      "Name": "REQUIRED",
-      "BIDSVersion": "REQUIRED",
-      "HEDVersion": "RECOMMENDED",
-      "DatasetLinks": "REQUIRED if [BIDS URIs][] are used",
-      "DatasetType": "RECOMMENDED",
-      "License": "RECOMMENDED",
-      "Authors": "RECOMMENDED if CITATION.cff is not present",
-      "Acknowledgements": "OPTIONAL",
-      "HowToAcknowledge": "OPTIONAL",
-      "Funding": "OPTIONAL",
-      "EthicsApprovals": "OPTIONAL",
-      "ReferencesAndLinks": "OPTIONAL",
-      "DatasetDOI": "OPTIONAL",
-      "GeneratedBy": "RECOMMENDED",
-      "SourceDatasets": "RECOMMENDED",
-   }
-) }}
-
-Each object in the `GeneratedBy` array includes the following REQUIRED, RECOMMENDED
-and OPTIONAL keys:
-
-<!-- This block generates a table describing subfields within a metadata field.
-The definitions of these fields can be found in
-  src/schema/objects/metadata.yaml
-and a guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___make_subobject_table("metadata.GeneratedBy.items") }}
-
-Example:
-
-```JSON
-{
-  "Name": "The mother of all experiments",
-  "BIDSVersion": "1.6.0",
-  "DatasetType": "raw",
-  "License": "CC0",
-  "Authors": [
-    "Paul Broca",
-    "Carl Wernicke"
-  ],
-  "Acknowledgements": "Special thanks to Korbinian Brodmann for help in formatting this dataset in BIDS. We thank Alan Lloyd Hodgkin and Andrew Huxley for helpful comments and discussions about the experiment and manuscript; Hermann Ludwig Helmholtz for administrative support; and Claudius Galenus for providing data for the medial-to-lateral index analysis.",
-  "HowToAcknowledge": "Please cite this paper: https://www.ncbi.nlm.nih.gov/pubmed/001012092119281",
-  "Funding": [
-    "National Institute of Neuroscience Grant F378236MFH1",
-    "National Institute of Neuroscience Grant 5RMZ0023106"
-  ],
-  "EthicsApprovals": [
-    "Army Human Research Protections Office (Protocol ARL-20098-10051, ARL 12-040, and ARL 12-041)"
-  ],
-  "ReferencesAndLinks": [
-    "https://www.ncbi.nlm.nih.gov/pubmed/001012092119281",
-    "Alzheimer A., & Kraepelin, E. (2015). Neural correlates of presenile dementia in humans. Journal of Neuroscientific Data, 2, 234001. doi:1920.8/jndata.2015.7"
-  ],
-  "DatasetDOI": "doi:10.0.2.3/dfjj.10",
-  "HEDVersion": "8.0.0",
-  "GeneratedBy": [
-    {
-      "Name": "reproin",
-      "Version": "0.6.0",
-      "Container": {
-        "Type": "docker",
-        "Tag": "repronim/reproin:0.6.0"
-      }
-    }
-  ],
-  "SourceDatasets": [
-    {
-      "URL": "s3://dicoms/studies/correlates",
-      "Version": "April 11 2011"
-    }
-  ]
-}
-```
-
-#### Derived dataset and pipeline description
-
-As for any BIDS dataset, a `dataset_description.json` file MUST be found at the
-top level of every derived dataset:
-`<dataset>/derivatives/<pipeline_name>/dataset_description.json`.
-
-In contrast to raw BIDS datasets, derived BIDS datasets MUST include a
-`GeneratedBy` key:
-
-<!-- This block generates a metadata table.
-The definitions of these fields can be found in
-  src/schema/objects/metadata.yaml
-and a guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___make_metadata_table(
-   {
-      "GeneratedBy": "REQUIRED"
-   }
-) }}
-
-If a derived dataset is stored as a subdirectory of the raw dataset, then the `Name` field
-of the first `GeneratedBy` object MUST be a substring of the derived dataset directory name.
-That is, in a directory `<dataset>/derivatives/<pipeline>[-<variant>]/`, the first
-`GeneratedBy` object should have a `Name` of `<pipeline>`.
-
-Example:
-
-```JSON
-{
-  "Name": "FMRIPREP Outputs",
-  "BIDSVersion": "1.6.0",
-  "DatasetType": "derivative",
-  "GeneratedBy": [
-    {
-      "Name": "fmriprep",
-      "Version": "1.4.1",
-      "Container": {
-        "Type": "docker",
-        "Tag": "poldracklab/fmriprep:1.4.1"
-        }
-    },
-    {
-      "Name": "Manual",
-      "Description": "Re-added RepetitionTime metadata to bold.json files"
-    }
-  ],
-  "SourceDatasets": [
-    {
-      "DOI": "doi:10.18112/openneuro.ds000114.v1.0.1",
-      "URL": "https://openneuro.org/datasets/ds000114/versions/1.0.1",
-      "Version": "1.0.1"
-    }
-  ]
-}
-```
-
-### `README`
-
-<!-- This block generates a file tree.
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___render_text("objects.files.README.description") }}
-
-### `CITATION.cff`
-
-<!-- This block generates a file tree.
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___render_text("objects.files.CITATION.description") }}
-
-For most redundant fields between `CITATION.cff` and `dataset_description.json`,
-the `CITATION.cff` SHOULD take precedence.
-To avoid inconsistency, metadata present in `CITATION.cff` SHOULD NOT be
-be included in `dataset_description.json`, with the exception of `Name` and
-`DatasetDOI`, to ensure that `CITATION.cff`-unaware tools can generate
-references to the dataset.
-In particular, if `CITATION.cff` is present,
-the `"Authors"` field of `dataset_description.json` MUST be omitted,
-and the `"HowToAcknowledge"`, `"License"` and `"ReferencesAndLinks"` SHOULD be omitted
-in favor of the `CITATION.cff` fields `message`/`preferred-citation`, `license` and
-`references`.
-
-### `CHANGES`
-
-<!-- This block generates a description.
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___render_text("objects.files.CHANGES.description") }}
-
-Example:
-
-```Text
-1.0.1 2015-08-27
-  - Fixed slice timing information.
-
-1.0.0 2015-08-17
-  - Initial release.
-```
-
-### `LICENSE`
-
-<!-- This block generates a description.
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___render_text("objects.files.LICENSE.description") }}
+# Data description
 
 ## Participants file
 
@@ -528,20 +314,3 @@ ses-predrug	2009-06-15T13:45:30	120
 ses-postdrug	2009-06-16T13:45:30	100
 ses-followup	2009-06-17T13:45:30	110
 ```
-
-## Code
-
-Template: `code/*`
-
-Source code of scripts that were used to prepare the dataset MAY be stored here.
-Examples include deidentification or defacing of the data, or
-the conversion from the format of the source data to the BIDS format
-(see [source vs. raw vs. derived data](./common-principles.md#source-vs-raw-vs-derived-data)).
-Extra care should be taken to avoid including original IDs or
-any identifiable information with the source code.
-There are no limitations or recommendations on the language and/or
-code organization of these scripts at the moment.
-
-<!-- Link Definitions -->
-
-[bids uris]: ./common-principles.md#bids-uri
diff --git a/src/modality-agnostic-files/dataset-description.md b/src/modality-agnostic-files/dataset-description.md
new file mode 100644
index 0000000000..a4c36a7207
--- /dev/null
+++ b/src/modality-agnostic-files/dataset-description.md
@@ -0,0 +1,213 @@
+# Dataset description
+
+Templates:
+
+-   `dataset_description.json`
+-   `README[.md|.rst|.txt]`
+-   `CITATION.cff`
+-   `CHANGES`
+-   `LICENSE[.md|.rst|.txt]`
+
+## `dataset_description.json`
+
+<!-- This block generates a description.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___render_text("objects.files.dataset_description.description") }}
+
+Every dataset MUST include this file with the following fields:
+
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_metadata_table(
+   {
+      "Name": "REQUIRED",
+      "BIDSVersion": "REQUIRED",
+      "HEDVersion": "RECOMMENDED",
+      "DatasetLinks": "REQUIRED if [BIDS URIs][] are used",
+      "DatasetType": "RECOMMENDED",
+      "License": "RECOMMENDED",
+      "Authors": "RECOMMENDED if CITATION.cff is not present",
+      "Acknowledgements": "OPTIONAL",
+      "HowToAcknowledge": "OPTIONAL",
+      "Funding": "OPTIONAL",
+      "EthicsApprovals": "OPTIONAL",
+      "ReferencesAndLinks": "OPTIONAL",
+      "DatasetDOI": "OPTIONAL",
+      "GeneratedBy": "RECOMMENDED",
+      "SourceDatasets": "RECOMMENDED",
+   }
+) }}
+
+Each object in the `GeneratedBy` array includes the following REQUIRED, RECOMMENDED
+and OPTIONAL keys:
+
+<!-- This block generates a table describing subfields within a metadata field.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_subobject_table("metadata.GeneratedBy.items") }}
+
+Example:
+
+```JSON
+{
+  "Name": "The mother of all experiments",
+  "BIDSVersion": "1.6.0",
+  "DatasetType": "raw",
+  "License": "CC0",
+  "Authors": [
+    "Paul Broca",
+    "Carl Wernicke"
+  ],
+  "Acknowledgements": "Special thanks to Korbinian Brodmann for help in formatting this dataset in BIDS. We thank Alan Lloyd Hodgkin and Andrew Huxley for helpful comments and discussions about the experiment and manuscript; Hermann Ludwig Helmholtz for administrative support; and Claudius Galenus for providing data for the medial-to-lateral index analysis.",
+  "HowToAcknowledge": "Please cite this paper: https://www.ncbi.nlm.nih.gov/pubmed/001012092119281",
+  "Funding": [
+    "National Institute of Neuroscience Grant F378236MFH1",
+    "National Institute of Neuroscience Grant 5RMZ0023106"
+  ],
+  "EthicsApprovals": [
+    "Army Human Research Protections Office (Protocol ARL-20098-10051, ARL 12-040, and ARL 12-041)"
+  ],
+  "ReferencesAndLinks": [
+    "https://www.ncbi.nlm.nih.gov/pubmed/001012092119281",
+    "Alzheimer A., & Kraepelin, E. (2015). Neural correlates of presenile dementia in humans. Journal of Neuroscientific Data, 2, 234001. doi:1920.8/jndata.2015.7"
+  ],
+  "DatasetDOI": "doi:10.0.2.3/dfjj.10",
+  "HEDVersion": "8.0.0",
+  "GeneratedBy": [
+    {
+      "Name": "reproin",
+      "Version": "0.6.0",
+      "Container": {
+        "Type": "docker",
+        "Tag": "repronim/reproin:0.6.0"
+      }
+    }
+  ],
+  "SourceDatasets": [
+    {
+      "URL": "s3://dicoms/studies/correlates",
+      "Version": "April 11 2011"
+    }
+  ]
+}
+```
+
+#### Derived dataset and pipeline description
+
+As for any BIDS dataset, a `dataset_description.json` file MUST be found at the
+top level of every derived dataset:
+`<dataset>/derivatives/<pipeline_name>/dataset_description.json`.
+
+In contrast to raw BIDS datasets, derived BIDS datasets MUST include a
+`GeneratedBy` key:
+
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_metadata_table(
+   {
+      "GeneratedBy": "REQUIRED"
+   }
+) }}
+
+If a derived dataset is stored as a subdirectory of the raw dataset, then the `Name` field
+of the first `GeneratedBy` object MUST be a substring of the derived dataset directory name.
+That is, in a directory `<dataset>/derivatives/<pipeline>[-<variant>]/`, the first
+`GeneratedBy` object should have a `Name` of `<pipeline>`.
+
+Example:
+
+```JSON
+{
+  "Name": "FMRIPREP Outputs",
+  "BIDSVersion": "1.6.0",
+  "DatasetType": "derivative",
+  "GeneratedBy": [
+    {
+      "Name": "fmriprep",
+      "Version": "1.4.1",
+      "Container": {
+        "Type": "docker",
+        "Tag": "poldracklab/fmriprep:1.4.1"
+        }
+    },
+    {
+      "Name": "Manual",
+      "Description": "Re-added RepetitionTime metadata to bold.json files"
+    }
+  ],
+  "SourceDatasets": [
+    {
+      "DOI": "doi:10.18112/openneuro.ds000114.v1.0.1",
+      "URL": "https://openneuro.org/datasets/ds000114/versions/1.0.1",
+      "Version": "1.0.1"
+    }
+  ]
+}
+```
+
+## `README`
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___render_text("objects.files.README.description") }}
+
+## `CITATION.cff`
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___render_text("objects.files.CITATION.description") }}
+
+For most redundant fields between `CITATION.cff` and `dataset_description.json`,
+the `CITATION.cff` SHOULD take precedence.
+To avoid inconsistency, metadata present in `CITATION.cff` SHOULD NOT be
+be included in `dataset_description.json`, with the exception of `Name` and
+`DatasetDOI`, to ensure that `CITATION.cff`-unaware tools can generate
+references to the dataset.
+In particular, if `CITATION.cff` is present,
+the `"Authors"` field of `dataset_description.json` MUST be omitted,
+and the `"HowToAcknowledge"`, `"License"` and `"ReferencesAndLinks"` SHOULD be omitted
+in favor of the `CITATION.cff` fields `message`/`preferred-citation`, `license` and
+`references`.
+
+## `CHANGES`
+
+<!-- This block generates a description.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___render_text("objects.files.CHANGES.description") }}
+
+Example:
+
+```Text
+1.0.1 2015-08-27
+  - Fixed slice timing information.
+
+1.0.0 2015-08-17
+  - Initial release.
+```
+
+## `LICENSE`
+
+<!-- This block generates a description.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___render_text("objects.files.LICENSE.description") }}

From 3165456176b08b76e4bfaab82b2318280f5dc54a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Boris=20Cl=C3=A9net?= <boris.clenet@inria.fr>
Date: Wed, 23 Apr 2025 10:36:58 +0200
Subject: [PATCH 02/11] Update links to modality-agnostic-files section

---
 src/appendices/meg-file-formats.md                 |  2 +-
 src/appendices/qmri.md                             |  2 +-
 src/common-principles.md                           | 10 +++++-----
 src/derivatives/introduction.md                    |  2 +-
 src/longitudinal-and-multi-site-studies.md         |  2 +-
 src/modality-agnostic-files/code.md                |  4 ++--
 src/modality-agnostic-files/data-description.md    | 14 +++++++-------
 src/modality-agnostic-files/dataset-description.md |  2 +-
 .../electroencephalography.md                      |  2 +-
 src/modality-specific-files/genetic-descriptor.md  |  2 +-
 .../intracranial-electroencephalography.md         |  2 +-
 .../magnetoencephalography.md                      |  4 ++--
 src/modality-specific-files/microscopy.md          |  4 ++--
 src/modality-specific-files/motion.md              |  6 +++---
 .../positron-emission-tomography.md                |  6 +++---
 src/schema/objects/entities.yaml                   |  2 +-
 src/schema/objects/files.yaml                      |  4 ++--
 17 files changed, 35 insertions(+), 35 deletions(-)

diff --git a/src/appendices/meg-file-formats.md b/src/appendices/meg-file-formats.md
index 81b640b517..615c62fe80 100644
--- a/src/appendices/meg-file-formats.md
+++ b/src/appendices/meg-file-formats.md
@@ -212,7 +212,7 @@ entity to indicate each part.
 If there are multiple parts of a recording and the optional `scans.tsv` is provided,
 remember to list all files separately in `scans.tsv` and that the entries
 for the `acq_time` column in `scans.tsv` MUST all be identical, as described in
-[Scans file](../modality-agnostic-files.md#scans-file).
+[Scans file](../modality-agnostic-files/data-description.md#scans-file).
 
 Example:
 
diff --git a/src/appendices/qmri.md b/src/appendices/qmri.md
index 83247c119b..3ca687e028 100644
--- a/src/appendices/qmri.md
+++ b/src/appendices/qmri.md
@@ -314,7 +314,7 @@ and a guide for using macros can be found at
 ### Metadata requirements for qMRI maps
 
 As qMRI maps are stored as derivatives, they are subjected to the metadata requirements of
-[derived datasets](../modality-agnostic-files.md#derived-dataset-and-pipeline-description).
+[derived datasets](../modality-agnostic-files/dataset-description.md#derived-dataset-and-pipeline-description).
 
 An example `dataset_description.json` for a qMRI map derivatives directory:
 
diff --git a/src/common-principles.md b/src/common-principles.md
index ba9afc1706..b100d1ef17 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -109,7 +109,7 @@ Data for each subject are placed in subdirectories named "`sub-<label>`",
 where string "`<label>`" is substituted with the unique identification
 label of each subject.
 Additional information on each participant MAY be provided in a
-[participants file](modality-agnostic-files.md#participants-file)
+[participants file](modality-agnostic-files/data-description.md#participants-file)
 in the root directory of the dataset.
 
 If data for the subject were acquired across multiple sessions, then within
@@ -119,7 +119,7 @@ label for each session.
 In datasets where at least one subject has more than one session, this
 additional subdirectory later SHOULD be added for all subjects in the dataset.
 Additional information on each session MAY be provided in a
-[sessions file](modality-agnostic-files.md#sessions-file)
+[sessions file](modality-agnostic-files/data-description.md#sessions-file)
 within the subject directory.
 
 Within the session subdirectory (or the subject subdirectory if no
@@ -1143,8 +1143,8 @@ to suppress warnings or provide interpretations of your filenames.
 
 <!-- Link Definitions -->
 
-[dataset-description]: modality-agnostic-files.md#dataset-description
-[dataset_description.json]: modality-agnostic-files.md#dataset_descriptionjson
-[derived-dataset-description]: modality-agnostic-files.md#derived-dataset-and-pipeline-description
+[dataset-description]: modality-agnostic-files/data-description.md
+[dataset_description.json]: modality-agnostic-files/data-description.md#dataset_descriptionjson
+[derived-dataset-description]: modality-agnostic-files/data-description.md#derived-dataset-and-pipeline-description
 [deprecated]: #definitions
 [uris]: #uniform-resource-indicator
diff --git a/src/derivatives/introduction.md b/src/derivatives/introduction.md
index af798f38bd..9878c239f9 100644
--- a/src/derivatives/introduction.md
+++ b/src/derivatives/introduction.md
@@ -129,7 +129,7 @@ for GIFTI files.
 
 [storage]: ../common-principles.md#storage-of-derived-datasets
 
-[derived-dataset-description]: ../modality-agnostic-files.md#derived-dataset-and-pipeline-description
+[derived-dataset-description]: ../modality-agnostic-files/dataset-description.md#derived-dataset-and-pipeline-description
 
 [gifti]: https://www.nitrc.org/projects/gifti/
 
diff --git a/src/longitudinal-and-multi-site-studies.md b/src/longitudinal-and-multi-site-studies.md
index 6fe102cb1a..66cc636c9c 100644
--- a/src/longitudinal-and-multi-site-studies.md
+++ b/src/longitudinal-and-multi-site-studies.md
@@ -3,7 +3,7 @@
 Multiple sessions (visits) are encoded by adding an extra layer of directories
 and [filenames](common-principles.md#filenames)
 in the form of a session (for example `ses-<label>`) and
-with a [`*_sessions.tsv` file](modality-agnostic-files.md#sessions-file).
+with a [`*_sessions.tsv` file](modality-agnostic-files/data-description.md#sessions-file).
 
 <!-- This block generates a file tree.
 A guide for using macros can be found at
diff --git a/src/modality-agnostic-files/code.md b/src/modality-agnostic-files/code.md
index 0e894d06a7..decd3cf87c 100644
--- a/src/modality-agnostic-files/code.md
+++ b/src/modality-agnostic-files/code.md
@@ -5,7 +5,7 @@ Template: `code/*`
 Source code of scripts that were used to prepare the dataset MAY be stored here.
 Examples include deidentification or defacing of the data, or
 the conversion from the format of the source data to the BIDS format
-(see [source vs. raw vs. derived data](./common-principles.md#source-vs-raw-vs-derived-data)).
+(see [source vs. raw vs. derived data](../common-principles.md#source-vs-raw-vs-derived-data)).
 Extra care should be taken to avoid including original IDs or
 any identifiable information with the source code.
 There are no limitations or recommendations on the language and/or
@@ -13,4 +13,4 @@ code organization of these scripts at the moment.
 
 <!-- Link Definitions -->
 
-[bids uris]: ./common-principles.md#bids-uri
+[bids uris]: ../common-principles.md#bids-uri
diff --git a/src/modality-agnostic-files/data-description.md b/src/modality-agnostic-files/data-description.md
index 57fa736ceb..06af9deb4f 100644
--- a/src/modality-agnostic-files/data-description.md
+++ b/src/modality-agnostic-files/data-description.md
@@ -41,7 +41,7 @@ sub-03	33	F	n/a	read
 
 It is RECOMMENDED to accompany each `participants.tsv` file with a sidecar
 `participants.json` file to describe the TSV column names and properties of their values (see also
-the [section on tabular files](common-principles.md#tabular-files)).
+the [section on tabular files](../common-principles.md#tabular-files)).
 Such sidecar files are needed to interpret the data, especially so when
 optional columns are defined beyond `age`, `sex`, `handedness`, `species`, `strain`,
 and `strain_rrid`, such as `group` in this example, or when a different
@@ -117,7 +117,7 @@ sample-05	sub-02	tissue	n/a
 
 It is RECOMMENDED to accompany each `samples.tsv` file with a sidecar
 `samples.json` file to describe the TSV column names and properties of their values
-(see also the [section on tabular files](common-principles.md#tabular-files)).
+(see also the [section on tabular files](../common-principles.md#tabular-files)).
 
 `samples.json` example:
 
@@ -160,7 +160,7 @@ in the BIDS dataset and `participants.tsv` file.
 
 As with all other tabular data, the additional phenotypic information files
 MAY be accompanied by a JSON file describing the columns in detail
-(see [Tabular files](common-principles.md#tabular-files)).
+(see [Tabular files](../common-principles.md#tabular-files)).
 
 In addition to the column descriptions, the JSON file MAY contain the following fields:
 
@@ -245,12 +245,12 @@ and not the individual files in that directory.
 Some neural recordings consist of multiple parts,
 that span several files,
 but that share the same extension.
-For example in [entity-linked file collections](./common-principles.md#entity-linked-file-collections),
+For example in [entity-linked file collections](../common-principles.md#entity-linked-file-collections),
 commonly used for qMRI,
 where recordings may be linked through entities such as `echo` and `part`
 (using `.nii` or `.nii.gz` extensions).
 For another example consider the case of large files in `.fif` format that are linked through the `split` entity
-(see [Split files](./appendices/meg-file-formats.md#split-files)).
+(see [Split files](../appendices/meg-file-formats.md#split-files)).
 Such recordings MUST be documented with one row per file
 (unlike the case of multi-file file formats described above).
 
@@ -268,7 +268,7 @@ For example vigilance questionnaire score administered after a resting
 state scan.
 All such included additional fields SHOULD be documented in an accompanying
 `_scans.json` file that describes these fields in detail
-(see [Tabular files](common-principles.md#tabular-files)).
+(see [Tabular files](../common-principles.md#tabular-files)).
 
 Example `_scans.tsv`:
 
@@ -296,7 +296,7 @@ In case of multiple sessions there is an option of adding additional
 In such case one file per participant SHOULD be added.
 These files MUST include a `session_id` column and describe each session by one and only one row.
 Column names in `sessions.tsv` files MUST be different from group level participant key column names in the
-[`participants.tsv` file](./modality-agnostic-files.md#participants-file).
+[`participants.tsv` file](./data-description.md#participants-file).
 
 <!-- This block generates a columns table.
 The definitions of these fields can be found in
diff --git a/src/modality-agnostic-files/dataset-description.md b/src/modality-agnostic-files/dataset-description.md
index a4c36a7207..e20fcf1111 100644
--- a/src/modality-agnostic-files/dataset-description.md
+++ b/src/modality-agnostic-files/dataset-description.md
@@ -101,7 +101,7 @@ Example:
 }
 ```
 
-#### Derived dataset and pipeline description
+### Derived dataset and pipeline description
 
 As for any BIDS dataset, a `dataset_description.json` file MUST be found at the
 top level of every derived dataset:
diff --git a/src/modality-specific-files/electroencephalography.md b/src/modality-specific-files/electroencephalography.md
index cb765c9549..232fbb09a1 100644
--- a/src/modality-specific-files/electroencephalography.md
+++ b/src/modality-specific-files/electroencephalography.md
@@ -200,7 +200,7 @@ A guide for using macros can be found at
 ```
 
 Note that the date and time information SHOULD be stored in the Study key file
-([`scans.tsv`](../modality-agnostic-files.md#scans-file)).
+([`scans.tsv`](../modality-agnostic-files/data-description.md#scans-file)).
 Date time information MUST be expressed as indicated in [Units](../common-principles.md#units)
 
 ## Channels description (`*_channels.tsv`)
diff --git a/src/modality-specific-files/genetic-descriptor.md b/src/modality-specific-files/genetic-descriptor.md
index 07946da5fa..462aa7db99 100644
--- a/src/modality-specific-files/genetic-descriptor.md
+++ b/src/modality-specific-files/genetic-descriptor.md
@@ -23,7 +23,7 @@ with details of where to find the genetic data and the type of data available.
 
 If information on associated genetic data is supplied as part of a BIDS dataset,
 these "genetic descriptors" are encoded as an additional, REQUIRED entry in the
-[`dataset_description.json`](../modality-agnostic-files.md#dataset_descriptionjson)
+[`dataset_description.json`](../modality-agnostic-files/dataset-description.md#dataset_descriptionjson)
 file.
 
 Datasets linked to a genetic database entry include the following REQUIRED and OPTIONAL
diff --git a/src/modality-specific-files/intracranial-electroencephalography.md b/src/modality-specific-files/intracranial-electroencephalography.md
index 1d5e146383..1fc99c3947 100644
--- a/src/modality-specific-files/intracranial-electroencephalography.md
+++ b/src/modality-specific-files/intracranial-electroencephalography.md
@@ -134,7 +134,7 @@ A guide for using macros can be found at
 {{ MACROS___make_sidecar_table("ieeg.iEEGOptional") }}
 
 Note that the date and time information SHOULD be stored in the study key file
-([`scans.tsv`](../modality-agnostic-files.md#scans-file)).
+([`scans.tsv`](../modality-agnostic-files/data-description.md#scans-file)).
 Date time information MUST be expressed as indicated in [Units](../common-principles.md#units)
 
 #### Hardware information
diff --git a/src/modality-specific-files/magnetoencephalography.md b/src/modality-specific-files/magnetoencephalography.md
index cdfeef50b7..35b4f9960a 100644
--- a/src/modality-specific-files/magnetoencephalography.md
+++ b/src/modality-specific-files/magnetoencephalography.md
@@ -66,7 +66,7 @@ with split files.
 If there are multiple parts of a recording and the optional `scans.tsv` is provided,
 remember to list all files separately in `scans.tsv` and that the entries for the
 `acq_time` column in `scans.tsv` MUST all be identical, as described in
-[Scans file](../modality-agnostic-files.md#scans-file).
+[Scans file](../modality-agnostic-files/data-description.md#scans-file).
 
 The Neuromag/Elekta/Megin system may also produce datasets that require a set of
 `crosstalk` and `calibration` files to be used properly (see also filename templates above).
@@ -234,7 +234,7 @@ A guide for using macros can be found at
 ```
 
 Note that the date and time information SHOULD be stored in the Study key file
-(`scans.tsv`), see [Scans file](../modality-agnostic-files.md#scans-file).
+(`scans.tsv`), see [Scans file](../modality-agnostic-files/data-description.md#scans-file).
 Date time information MUST be expressed as indicated in [Units](../common-principles.md#units)
 
 ## Channels description (`*_channels.tsv`)
diff --git a/src/modality-specific-files/microscopy.md b/src/modality-specific-files/microscopy.md
index 1053b2bdcc..dd9abb5802 100644
--- a/src/modality-specific-files/microscopy.md
+++ b/src/modality-specific-files/microscopy.md
@@ -404,7 +404,7 @@ A guide for using macros can be found at
 
 ## Required Samples file
 
-For Microscopy data, the [Samples file](../modality-agnostic-files.md#samples-file)
+For Microscopy data, the [Samples file](../modality-agnostic-files/data-description.md#samples-file)
 `samples.tsv` is REQUIRED and its associated sidecar `samples.json` file is RECOMMENDED.
 
 Additional optional columns MAY be used to describe other samples' attributes.
@@ -412,7 +412,7 @@ Additional optional columns MAY be used to describe other samples' attributes.
 ## Recommended Participants data
 
 For Microscopy data, we RECOMMEND to make use of the columns `species`, `strain` and
-`strain_rrid` in the [Participants file](../modality-agnostic-files.md#participants-file)
+`strain_rrid` in the [Participants file](../modality-agnostic-files/data-description.md#participants-file)
 when applicable.
 
 Additional optional columns MAY be used to describe other subjects' attributes.
diff --git a/src/modality-specific-files/motion.md b/src/modality-specific-files/motion.md
index 109a55d198..b761f78f4f 100644
--- a/src/modality-specific-files/motion.md
+++ b/src/modality-specific-files/motion.md
@@ -53,7 +53,7 @@ All relevant metadata about a tracking systems is stored in accompanying sidecar
 When multiple tracking systems are used to record motion or motion capture is used alongside the recording of other BIDS modalities and recordings should be interpreted together,
 it is advised to provide a possibility to synchronize recordings.
 The preferred way to do so is to use the acquisition time of the first data point of recordings and
-to store this information in the `acq_time` column of the [`*_scans.tsv`](../modality-agnostic-files.md#scans-file) file.
+to store this information in the `acq_time` column of the [`*_scans.tsv`](../modality-agnostic-files/data-description.md#scans-file) file.
 Note that the [BIDS date time format](../common-principles.md#units) allows optional fractional seconds, which SHOULD be used to maximize the precision of the synchronization.
 Only if the precision of the synchronization is not high enough, the `*_events.tsv` file SHOULD be used to synchronize recordings.
 In this file, the start- and stop time of the recording of a system are specified in relation to a system to synchronize with.
@@ -122,9 +122,9 @@ If there are additional tracking systems (for example [optical motion capture](h
 data from these MUST be stored as separate files like `*_tracksys-omcA_motion.tsv` and `*_tracksys-omcB_motion.tsv`.
 All specified tracking systems MAY share `tracked_point` defined in `*_channels.tsv`, when tracking devices are placed on the same object or body part.
 
-Note that the onsets of the recordings SHOULD be stored in the study key file [(`scans.tsv`)](../modality-agnostic-files.md#scans-file).
+Note that the onsets of the recordings SHOULD be stored in the study key file [(`scans.tsv`)](../modality-agnostic-files/data-description.md#scans-file).
 Here, date-time information MUST be expressed as indicated in [Units](../common-principles.md#units).
-The [`scans.tsv`](../modality-agnostic-files.md#scans-file) file contains the filename and the acquisition time of a recording,
+The [`scans.tsv`](../modality-agnostic-files/data-description.md#scans-file) file contains the filename and the acquisition time of a recording,
 which MAY be used to synchronize multiple recordings.
 
 ## Channels description (`*_channels.tsv`)
diff --git a/src/modality-specific-files/positron-emission-tomography.md b/src/modality-specific-files/positron-emission-tomography.md
index 0b992c7c25..4901f86e7d 100644
--- a/src/modality-specific-files/positron-emission-tomography.md
+++ b/src/modality-specific-files/positron-emission-tomography.md
@@ -313,8 +313,8 @@ Knudsen et al. 2020
 ([doi:10.1177/0271678X20905433](https://doi.org/10.1177/0271678X20905433))
 recommends recording participant body weight.
 If recorded once per participant, these data SHOULD be included in the
-[Participants file](../modality-agnostic-files.md#participants-file) or as
-[Phenotypic and assessment data](../modality-agnostic-files.md#phenotypic-and-assessment-data).
+[Participants file](../modality-agnostic-files/data-description.md#participants-file) or as
+[Phenotypic and assessment data](../modality-agnostic-files/data-description.md#phenotypic-and-assessment-data).
 
 For example:
 
@@ -326,7 +326,7 @@ sub-03	72
 ```
 
 If multiple measurements are made, these data SHOULD be included in the
-[Sessions file](../modality-agnostic-files.md#sessions-file).
+[Sessions file](../modality-agnostic-files/data-description.md#sessions-file).
 
 For example:
 
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index a5638bc984..5653f35b32 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -354,7 +354,7 @@ split:
     If there are multiple parts of a recording and the optional `scans.tsv` is provided,
     all files MUST be listed separately in `scans.tsv` and
     the entries for the `acq_time` column in `scans.tsv` MUST all be identical,
-    as described in [Scans file](SPEC_ROOT/modality-agnostic-files.md#scans-file).
+    as described in [Scans file](SPEC_ROOT/modality-agnostic-files/data-description.md#scans-file).
   type: string
   format: index
 stain:
diff --git a/src/schema/objects/files.yaml b/src/schema/objects/files.yaml
index d2d8761410..513eb0a68c 100644
--- a/src/schema/objects/files.yaml
+++ b/src/schema/objects/files.yaml
@@ -100,7 +100,7 @@ code:
   description: |
     A directory in which to store any code
     (for example the one used to generate the derivatives from the raw data).
-    See the [Code section](SPEC_ROOT/modality-agnostic-files.md#code)
+    See the [Code section](SPEC_ROOT/modality-agnostic-files/code.md)
     for more information.
 derivatives:
   display_name: Derivative data
@@ -116,7 +116,7 @@ phenotype:
     A directory where to store participant level measurements (for
     example responses from multiple questionnaires) split into
     individual files separate from `participants.tsv`.
-    See the [relevant section](SPEC_ROOT/modality-agnostic-files.md#phenotypic-and-assessment-data)
+    See the [relevant section](SPEC_ROOT/modality-agnostic-files/data-description.md#phenotypic-and-assessment-data)
     for more information.
 sourcedata:
   display_name: Source data

From 5e0a9adbfec800e4153b0765cb4200e3b44a6aa1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Boris=20Cl=C3=A9net?= <boris.clenet@inria.fr>
Date: Wed, 23 Apr 2025 11:56:09 +0200
Subject: [PATCH 03/11] Update links to modality-agnostic-files section

---
 src/modality-agnostic-files/code.md                | 4 ----
 src/modality-agnostic-files/dataset-description.md | 4 ++++
 src/schema/objects/metadata.yaml                   | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/modality-agnostic-files/code.md b/src/modality-agnostic-files/code.md
index decd3cf87c..f005df6a22 100644
--- a/src/modality-agnostic-files/code.md
+++ b/src/modality-agnostic-files/code.md
@@ -10,7 +10,3 @@ Extra care should be taken to avoid including original IDs or
 any identifiable information with the source code.
 There are no limitations or recommendations on the language and/or
 code organization of these scripts at the moment.
-
-<!-- Link Definitions -->
-
-[bids uris]: ../common-principles.md#bids-uri
diff --git a/src/modality-agnostic-files/dataset-description.md b/src/modality-agnostic-files/dataset-description.md
index e20fcf1111..10d61d6eab 100644
--- a/src/modality-agnostic-files/dataset-description.md
+++ b/src/modality-agnostic-files/dataset-description.md
@@ -211,3 +211,7 @@ A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
 {{ MACROS___render_text("objects.files.LICENSE.description") }}
+
+<!-- Link Definitions -->
+
+[bids uris]: ../common-principles.md#bids-uri
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 09984125ad..ad1cff2318 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -3164,7 +3164,7 @@ ScanDate:
   description: |
     Date of scan in the format `"YYYY-MM-DD[Z]"`.
     This field is DEPRECATED, and this metadata SHOULD be recorded in the `acq_time` column of the
-    corresponding [Scans file](SPEC_ROOT/modality-agnostic-files.md#scans-file).
+    corresponding [Scans file](SPEC_ROOT/modality-agnostic-files/data-description.md#scans-file).
   type: string
   format: date
 ScanOptions:

From 6507ac4fb039506132b1f318cf776e3160dbb9af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Boris=20Cl=C3=A9net?= <boris.clenet@inria.fr>
Date: Wed, 23 Apr 2025 12:00:12 +0200
Subject: [PATCH 04/11] Remove broken links in CHANGES and pregh-changes files

---
 src/CHANGES.md       | 2 +-
 src/pregh-changes.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/CHANGES.md b/src/CHANGES.md
index 6350df47e8..0334944a24 100644
--- a/src/CHANGES.md
+++ b/src/CHANGES.md
@@ -625,7 +625,7 @@
 ## 1.0.1-rc1
 
 -   Added T1 Rho maps: [4.1 Anatomy imaging data](modality-specific-files/magnetic-resonance-imaging-data.md#anatomy-imaging-data).
--   Added support for phenotypic information split into multiple files: [3.2 Participant key file](modality-agnostic-files.md#participants-file).
+-   Added support for phenotypic information split into multiple files: 3.2 Participant key file.
 -   Added recommendations for multi site datasets.
 -   Added `SoftwareVersions`.
 -   Added `run-<run_index>` to the phase encoding maps. Improved the description.
diff --git a/src/pregh-changes.md b/src/pregh-changes.md
index 2cba2a81df..5126a51f5a 100644
--- a/src/pregh-changes.md
+++ b/src/pregh-changes.md
@@ -32,7 +32,7 @@
 ## 1.0.1-rc1
 
 -   Added T1 Rho maps: [4.1 Anatomy imaging data](modality-specific-files/magnetic-resonance-imaging-data.md#anatomy-imaging-data).
--   Added support for phenotypic information split into multiple files: [3.2 Participant key file](modality-agnostic-files.md#participants-file).
+-   Added support for phenotypic information split into multiple files: 3.2 Participant key file.
 -   Added recommendations for multi site datasets.
 -   Added `SoftwareVersions`.
 -   Added `run-<run_index>` to the phase encoding maps. Improved the description.

From 579c05fadde481e6ba1f36e61217aa5091228d99 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Boris=20Cl=C3=A9net?= <boris.clenet@inria.fr>
Date: Fri, 25 Apr 2025 15:40:39 +0200
Subject: [PATCH 05/11] Issue with redirects

---
 mkdocs.yml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index a19b5d5331..ffd018d0f6 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -129,9 +129,9 @@ plugins:
       redirect_maps:
         "01-introduction.md": "introduction.md"
         "02-common-principles.md": "common-principles.md"
-        "03-modality-agnostic-files/01-modality-agnostic-files.md": "modality-agnostic-files/dataset-description.md"
-        "03-modality-agnostic-files/02-modality-agnostic-files.md": "modality-agnostic-files/data-description.md"
-        "03-modality-agnostic-files/03-modality-agnostic-files.md": "modality-agnostic-files/code.md"
+        "03-modality-agnostic-files/01-dataset-description.md": "modality-agnostic-files/dataset-description.md"
+        "03-modality-agnostic-files/02-data-description.md": "modality-agnostic-files/data-description.md"
+        "03-modality-agnostic-files/03-code.md": "modality-agnostic-files/code.md"
         "04-modality-specific-files/01-magnetic-resonance-imaging-data.md": "modality-specific-files/magnetic-resonance-imaging-data.md"
         "04-modality-specific-files/02-magnetoencephalography.md": "modality-specific-files/magnetoencephalography.md"
         "04-modality-specific-files/03-electroencephalography.md": "modality-specific-files/electroencephalography.md"

From 0b26b6debcd144444c409baf3fcdf6fd5cc5280f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Boris=20Cl=C3=A9net?= <boris.clenet@inria.fr>
Date: Wed, 7 May 2025 15:03:50 +0200
Subject: [PATCH 06/11] Fix styling issue

---
 mkdocs.yml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/mkdocs.yml b/mkdocs.yml
index ffd018d0f6..50d6837b55 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -104,15 +104,21 @@ extra:
 
 extra_javascript:
   - js/jquery-3.6.0.min.js
+extra_css:
+  - css/tsv.css
 markdown_extensions:
   - toc:
       anchorlink: true
+  - attr_list
   - pymdownx.superfences:
       preserve_tabs: true
       custom_fences:
         - name: tsv
           class: tsv
           format: !!python/name:bidsschematools.render.tsv.fence
+        - name: tsvgz
+          class: tsv
+          format: !!python/name:bidsschematools.render.tsv.fence
   - admonition
   - pymdownx.details
 plugins:

From a4642a3a59dacc08a304db7ebcaff8668d153c28 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Boris=20Cl=C3=A9net?= <boris.clenet@inria.fr>
Date: Wed, 14 May 2025 17:18:23 +0200
Subject: [PATCH 07/11] Renaming data-description into data-summary-files

---
 mkdocs.yml                                                | 8 +++++---
 src/CHANGES.md                                            | 2 +-
 .../{data-description.md => data-summary-files.md}        | 0
 src/pregh-changes.md                                      | 2 +-
 4 files changed, 7 insertions(+), 5 deletions(-)
 rename src/modality-agnostic-files/{data-description.md => data-summary-files.md} (100%)

diff --git a/mkdocs.yml b/mkdocs.yml
index 50d6837b55..90d0a5ac14 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -7,7 +7,8 @@ nav:
       - Common principles: common-principles.md
       - Modality agnostic files:
           - Dataset description: modality-agnostic-files/dataset-description.md
-          - Data description: modality-agnostic-files/data-description.md
+          - Data summary files: modality-agnostic-files/data-summary-files.md
+          - Phenotypic and assessment data: modality-agnostic-files/phenotypic-assessment-data.md
           - Code: modality-agnostic-files/code.md
       - Modality specific files:
           - Magnetic Resonance Imaging: modality-specific-files/magnetic-resonance-imaging-data.md
@@ -136,8 +137,9 @@ plugins:
         "01-introduction.md": "introduction.md"
         "02-common-principles.md": "common-principles.md"
         "03-modality-agnostic-files/01-dataset-description.md": "modality-agnostic-files/dataset-description.md"
-        "03-modality-agnostic-files/02-data-description.md": "modality-agnostic-files/data-description.md"
-        "03-modality-agnostic-files/03-code.md": "modality-agnostic-files/code.md"
+        "03-modality-agnostic-files/02-data-summary-files.md": "modality-agnostic-files/data-summary-files.md"
+        "03-modality-agnostic-files/03-phenotypic-assessment-data.md": "modality-agnostic-files/phenotypic-assessment-data.md"
+        "03-modality-agnostic-files/04-code.md": "modality-agnostic-files/code.md"
         "04-modality-specific-files/01-magnetic-resonance-imaging-data.md": "modality-specific-files/magnetic-resonance-imaging-data.md"
         "04-modality-specific-files/02-magnetoencephalography.md": "modality-specific-files/magnetoencephalography.md"
         "04-modality-specific-files/03-electroencephalography.md": "modality-specific-files/electroencephalography.md"
diff --git a/src/CHANGES.md b/src/CHANGES.md
index 0334944a24..8908abe800 100644
--- a/src/CHANGES.md
+++ b/src/CHANGES.md
@@ -625,7 +625,7 @@
 ## 1.0.1-rc1
 
 -   Added T1 Rho maps: [4.1 Anatomy imaging data](modality-specific-files/magnetic-resonance-imaging-data.md#anatomy-imaging-data).
--   Added support for phenotypic information split into multiple files: 3.2 Participant key file.
+-   Added support for phenotypic information split into multiple files: [3.2 Participant key file](modality-agnostic-files/data-summary-files.md#participants-file).
 -   Added recommendations for multi site datasets.
 -   Added `SoftwareVersions`.
 -   Added `run-<run_index>` to the phase encoding maps. Improved the description.
diff --git a/src/modality-agnostic-files/data-description.md b/src/modality-agnostic-files/data-summary-files.md
similarity index 100%
rename from src/modality-agnostic-files/data-description.md
rename to src/modality-agnostic-files/data-summary-files.md
diff --git a/src/pregh-changes.md b/src/pregh-changes.md
index 5126a51f5a..7d9052b69d 100644
--- a/src/pregh-changes.md
+++ b/src/pregh-changes.md
@@ -32,7 +32,7 @@
 ## 1.0.1-rc1
 
 -   Added T1 Rho maps: [4.1 Anatomy imaging data](modality-specific-files/magnetic-resonance-imaging-data.md#anatomy-imaging-data).
--   Added support for phenotypic information split into multiple files: 3.2 Participant key file.
+-   Added support for phenotypic information split into multiple files: [3.2 Participant key file](modality-agnostic-files/data-summary-files.md#participants-file).
 -   Added recommendations for multi site datasets.
 -   Added `SoftwareVersions`.
 -   Added `run-<run_index>` to the phase encoding maps. Improved the description.

From 6559fa33f96451a87a3e9f13d23b8bcb6d68a248 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Boris=20Cl=C3=A9net?= <boris.clenet@inria.fr>
Date: Wed, 14 May 2025 17:27:55 +0200
Subject: [PATCH 08/11] Update links

---
 mkdocs.yml                                    |  4 +-
 src/appendices/meg-file-formats.md            |  2 +-
 src/common-principles.md                      | 10 +--
 src/longitudinal-and-multi-site-studies.md    |  2 +-
 .../data-summary-files.md                     | 87 +------------------
 .../phenotypic-and-assessment-data.md         | 82 +++++++++++++++++
 .../electroencephalography.md                 |  2 +-
 .../intracranial-electroencephalography.md    |  2 +-
 .../magnetoencephalography.md                 |  4 +-
 src/modality-specific-files/microscopy.md     |  4 +-
 src/modality-specific-files/motion.md         |  6 +-
 .../positron-emission-tomography.md           |  6 +-
 src/schema/objects/entities.yaml              |  2 +-
 src/schema/objects/files.yaml                 |  2 +-
 src/schema/objects/metadata.yaml              |  2 +-
 15 files changed, 108 insertions(+), 109 deletions(-)
 create mode 100644 src/modality-agnostic-files/phenotypic-and-assessment-data.md

diff --git a/mkdocs.yml b/mkdocs.yml
index 90d0a5ac14..462094e5f5 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -8,7 +8,7 @@ nav:
       - Modality agnostic files:
           - Dataset description: modality-agnostic-files/dataset-description.md
           - Data summary files: modality-agnostic-files/data-summary-files.md
-          - Phenotypic and assessment data: modality-agnostic-files/phenotypic-assessment-data.md
+          - Phenotypic and assessment data: modality-agnostic-files/phenotypic-and-assessment-data.md
           - Code: modality-agnostic-files/code.md
       - Modality specific files:
           - Magnetic Resonance Imaging: modality-specific-files/magnetic-resonance-imaging-data.md
@@ -138,7 +138,7 @@ plugins:
         "02-common-principles.md": "common-principles.md"
         "03-modality-agnostic-files/01-dataset-description.md": "modality-agnostic-files/dataset-description.md"
         "03-modality-agnostic-files/02-data-summary-files.md": "modality-agnostic-files/data-summary-files.md"
-        "03-modality-agnostic-files/03-phenotypic-assessment-data.md": "modality-agnostic-files/phenotypic-assessment-data.md"
+        "03-modality-agnostic-files/03-phenotypic-and-assessment-data.md": "modality-agnostic-files/phenotypic-and-assessment-data.md"
         "03-modality-agnostic-files/04-code.md": "modality-agnostic-files/code.md"
         "04-modality-specific-files/01-magnetic-resonance-imaging-data.md": "modality-specific-files/magnetic-resonance-imaging-data.md"
         "04-modality-specific-files/02-magnetoencephalography.md": "modality-specific-files/magnetoencephalography.md"
diff --git a/src/appendices/meg-file-formats.md b/src/appendices/meg-file-formats.md
index 615c62fe80..bd5d05be0c 100644
--- a/src/appendices/meg-file-formats.md
+++ b/src/appendices/meg-file-formats.md
@@ -212,7 +212,7 @@ entity to indicate each part.
 If there are multiple parts of a recording and the optional `scans.tsv` is provided,
 remember to list all files separately in `scans.tsv` and that the entries
 for the `acq_time` column in `scans.tsv` MUST all be identical, as described in
-[Scans file](../modality-agnostic-files/data-description.md#scans-file).
+[Scans file](../modality-agnostic-files/data-summary-files.md#scans-file).
 
 Example:
 
diff --git a/src/common-principles.md b/src/common-principles.md
index 3b469dd14e..dfdfd7dc3c 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -109,7 +109,7 @@ Data for each subject are placed in subdirectories named "`sub-<label>`",
 where string "`<label>`" is substituted with the unique identification
 label of each subject.
 Additional information on each participant MAY be provided in a
-[participants file](modality-agnostic-files/data-description.md#participants-file)
+[participants file](modality-agnostic-files/data-summary-files.md#participants-file)
 in the root directory of the dataset.
 
 If data for the subject were acquired across multiple sessions, then within
@@ -119,7 +119,7 @@ label for each session.
 In datasets where at least one subject has more than one session, this
 additional subdirectory later SHOULD be added for all subjects in the dataset.
 Additional information on each session MAY be provided in a
-[sessions file](modality-agnostic-files/data-description.md#sessions-file)
+[sessions file](modality-agnostic-files/data-summary-files.md#sessions-file)
 within the subject directory.
 
 Within the session subdirectory (or the subject subdirectory if no
@@ -1144,8 +1144,8 @@ to suppress warnings or provide interpretations of your filenames.
 
 <!-- Link Definitions -->
 
-[dataset-description]: modality-agnostic-files/data-description.md
-[dataset_description.json]: modality-agnostic-files/data-description.md#dataset_descriptionjson
-[derived-dataset-description]: modality-agnostic-files/data-description.md#derived-dataset-and-pipeline-description
+[dataset-description]: modality-agnostic-files/data-summary-files.md
+[dataset_description.json]: modality-agnostic-files/data-summary-files.md#dataset_descriptionjson
+[derived-dataset-description]: modality-agnostic-files/data-summary-files.md#derived-dataset-and-pipeline-description
 [deprecated]: #definitions
 [uris]: #uniform-resource-indicator
diff --git a/src/longitudinal-and-multi-site-studies.md b/src/longitudinal-and-multi-site-studies.md
index 66cc636c9c..5623bec305 100644
--- a/src/longitudinal-and-multi-site-studies.md
+++ b/src/longitudinal-and-multi-site-studies.md
@@ -3,7 +3,7 @@
 Multiple sessions (visits) are encoded by adding an extra layer of directories
 and [filenames](common-principles.md#filenames)
 in the form of a session (for example `ses-<label>`) and
-with a [`*_sessions.tsv` file](modality-agnostic-files/data-description.md#sessions-file).
+with a [`*_sessions.tsv` file](modality-agnostic-files/data-summary-files.md#sessions-file).
 
 <!-- This block generates a file tree.
 A guide for using macros can be found at
diff --git a/src/modality-agnostic-files/data-summary-files.md b/src/modality-agnostic-files/data-summary-files.md
index 06af9deb4f..d6b5032c2b 100644
--- a/src/modality-agnostic-files/data-summary-files.md
+++ b/src/modality-agnostic-files/data-summary-files.md
@@ -1,4 +1,4 @@
-# Data description
+# Data summary files
 
 ## Participants file
 
@@ -132,89 +132,6 @@ It is RECOMMENDED to accompany each `samples.tsv` file with a sidecar
 }
 ```
 
-## Phenotypic and assessment data
-
-Template:
-
-```Text
-phenotype/
-    <measurement_tool_name>.tsv
-    <measurement_tool_name>.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 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.
-
-As with all other tabular data, the additional phenotypic information files
-MAY be accompanied by a JSON file describing the columns in detail
-(see [Tabular files](../common-principles.md#tabular-files)).
-
-In addition to the column descriptions, the JSON file MAY contain the following fields:
-
-<!-- This block generates a metadata table.
-The definitions of these fields can be found in
-  src/schema/objects/metadata.yaml
-and a guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___make_metadata_table(
-   {
-      "MeasurementToolMetadata": "OPTIONAL",
-      "Derivative": "OPTIONAL",
-   }
-) }}
-
-As an example, consider the contents of a file called
-`phenotype/acds_adult.json`:
-
-```JSON
-{
-  "MeasurementToolMetadata": {
-    "Description": "Adult ADHD Clinical Diagnostic Scale V1.2",
-    "TermURL": "https://www.cognitiveatlas.org/task/id/trm_5586ff878155d"
-  },
-  "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 that in this example `MeasurementToolMetadata` includes information
-about the questionnaire and `adhd_b` and `adhd_c_dx` correspond to individual
-columns.
-
-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 is a transformation of values from other
-columns (for example a summary score based on a subset of items in a
-questionnaire).
-
 ## Scans file
 
 Template:
@@ -296,7 +213,7 @@ In case of multiple sessions there is an option of adding additional
 In such case one file per participant SHOULD be added.
 These files MUST include a `session_id` column and describe each session by one and only one row.
 Column names in `sessions.tsv` files MUST be different from group level participant key column names in the
-[`participants.tsv` file](./data-description.md#participants-file).
+[`participants.tsv` file](./data-summary-files.md#participants-file).
 
 <!-- This block generates a columns table.
 The definitions of these fields can be found in
diff --git a/src/modality-agnostic-files/phenotypic-and-assessment-data.md b/src/modality-agnostic-files/phenotypic-and-assessment-data.md
new file mode 100644
index 0000000000..d876a38ee7
--- /dev/null
+++ b/src/modality-agnostic-files/phenotypic-and-assessment-data.md
@@ -0,0 +1,82 @@
+# Phenotypic and assessment data
+
+Template:
+
+```Text
+phenotype/
+    <measurement_tool_name>.tsv
+    <measurement_tool_name>.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 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.
+
+As with all other tabular data, the additional phenotypic information files
+MAY be accompanied by a JSON file describing the columns in detail
+(see [Tabular files](../common-principles.md#tabular-files)).
+
+In addition to the column descriptions, the JSON file MAY contain the following fields:
+
+<!-- This block generates a metadata table.
+The definitions of these fields can be found in
+  src/schema/objects/metadata.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_metadata_table(
+   {
+      "MeasurementToolMetadata": "OPTIONAL",
+      "Derivative": "OPTIONAL",
+   }
+) }}
+
+As an example, consider the contents of a file called
+`phenotype/acds_adult.json`:
+
+```JSON
+{
+  "MeasurementToolMetadata": {
+    "Description": "Adult ADHD Clinical Diagnostic Scale V1.2",
+    "TermURL": "https://www.cognitiveatlas.org/task/id/trm_5586ff878155d"
+  },
+  "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 that in this example `MeasurementToolMetadata` includes information
+about the questionnaire and `adhd_b` and `adhd_c_dx` correspond to individual
+columns.
+
+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 is a transformation of values from other
+columns (for example a summary score based on a subset of items in a
+questionnaire).
diff --git a/src/modality-specific-files/electroencephalography.md b/src/modality-specific-files/electroencephalography.md
index 232fbb09a1..739a266aa3 100644
--- a/src/modality-specific-files/electroencephalography.md
+++ b/src/modality-specific-files/electroencephalography.md
@@ -200,7 +200,7 @@ A guide for using macros can be found at
 ```
 
 Note that the date and time information SHOULD be stored in the Study key file
-([`scans.tsv`](../modality-agnostic-files/data-description.md#scans-file)).
+([`scans.tsv`](../modality-agnostic-files/data-summary-files.md#scans-file)).
 Date time information MUST be expressed as indicated in [Units](../common-principles.md#units)
 
 ## Channels description (`*_channels.tsv`)
diff --git a/src/modality-specific-files/intracranial-electroencephalography.md b/src/modality-specific-files/intracranial-electroencephalography.md
index 1fc99c3947..93533cda7e 100644
--- a/src/modality-specific-files/intracranial-electroencephalography.md
+++ b/src/modality-specific-files/intracranial-electroencephalography.md
@@ -134,7 +134,7 @@ A guide for using macros can be found at
 {{ MACROS___make_sidecar_table("ieeg.iEEGOptional") }}
 
 Note that the date and time information SHOULD be stored in the study key file
-([`scans.tsv`](../modality-agnostic-files/data-description.md#scans-file)).
+([`scans.tsv`](../modality-agnostic-files/data-summary-files.md#scans-file)).
 Date time information MUST be expressed as indicated in [Units](../common-principles.md#units)
 
 #### Hardware information
diff --git a/src/modality-specific-files/magnetoencephalography.md b/src/modality-specific-files/magnetoencephalography.md
index 35b4f9960a..057ff3ad59 100644
--- a/src/modality-specific-files/magnetoencephalography.md
+++ b/src/modality-specific-files/magnetoencephalography.md
@@ -66,7 +66,7 @@ with split files.
 If there are multiple parts of a recording and the optional `scans.tsv` is provided,
 remember to list all files separately in `scans.tsv` and that the entries for the
 `acq_time` column in `scans.tsv` MUST all be identical, as described in
-[Scans file](../modality-agnostic-files/data-description.md#scans-file).
+[Scans file](../modality-agnostic-files/data-summary-files.md#scans-file).
 
 The Neuromag/Elekta/Megin system may also produce datasets that require a set of
 `crosstalk` and `calibration` files to be used properly (see also filename templates above).
@@ -234,7 +234,7 @@ A guide for using macros can be found at
 ```
 
 Note that the date and time information SHOULD be stored in the Study key file
-(`scans.tsv`), see [Scans file](../modality-agnostic-files/data-description.md#scans-file).
+(`scans.tsv`), see [Scans file](../modality-agnostic-files/data-summary-files.md#scans-file).
 Date time information MUST be expressed as indicated in [Units](../common-principles.md#units)
 
 ## Channels description (`*_channels.tsv`)
diff --git a/src/modality-specific-files/microscopy.md b/src/modality-specific-files/microscopy.md
index dd9abb5802..617407cd0c 100644
--- a/src/modality-specific-files/microscopy.md
+++ b/src/modality-specific-files/microscopy.md
@@ -404,7 +404,7 @@ A guide for using macros can be found at
 
 ## Required Samples file
 
-For Microscopy data, the [Samples file](../modality-agnostic-files/data-description.md#samples-file)
+For Microscopy data, the [Samples file](../modality-agnostic-files/data-summary-files.md#samples-file)
 `samples.tsv` is REQUIRED and its associated sidecar `samples.json` file is RECOMMENDED.
 
 Additional optional columns MAY be used to describe other samples' attributes.
@@ -412,7 +412,7 @@ Additional optional columns MAY be used to describe other samples' attributes.
 ## Recommended Participants data
 
 For Microscopy data, we RECOMMEND to make use of the columns `species`, `strain` and
-`strain_rrid` in the [Participants file](../modality-agnostic-files/data-description.md#participants-file)
+`strain_rrid` in the [Participants file](../modality-agnostic-files/data-summary-files.md#participants-file)
 when applicable.
 
 Additional optional columns MAY be used to describe other subjects' attributes.
diff --git a/src/modality-specific-files/motion.md b/src/modality-specific-files/motion.md
index b761f78f4f..4f4fb70ece 100644
--- a/src/modality-specific-files/motion.md
+++ b/src/modality-specific-files/motion.md
@@ -53,7 +53,7 @@ All relevant metadata about a tracking systems is stored in accompanying sidecar
 When multiple tracking systems are used to record motion or motion capture is used alongside the recording of other BIDS modalities and recordings should be interpreted together,
 it is advised to provide a possibility to synchronize recordings.
 The preferred way to do so is to use the acquisition time of the first data point of recordings and
-to store this information in the `acq_time` column of the [`*_scans.tsv`](../modality-agnostic-files/data-description.md#scans-file) file.
+to store this information in the `acq_time` column of the [`*_scans.tsv`](../modality-agnostic-files/data-summary-files.md#scans-file) file.
 Note that the [BIDS date time format](../common-principles.md#units) allows optional fractional seconds, which SHOULD be used to maximize the precision of the synchronization.
 Only if the precision of the synchronization is not high enough, the `*_events.tsv` file SHOULD be used to synchronize recordings.
 In this file, the start- and stop time of the recording of a system are specified in relation to a system to synchronize with.
@@ -122,9 +122,9 @@ If there are additional tracking systems (for example [optical motion capture](h
 data from these MUST be stored as separate files like `*_tracksys-omcA_motion.tsv` and `*_tracksys-omcB_motion.tsv`.
 All specified tracking systems MAY share `tracked_point` defined in `*_channels.tsv`, when tracking devices are placed on the same object or body part.
 
-Note that the onsets of the recordings SHOULD be stored in the study key file [(`scans.tsv`)](../modality-agnostic-files/data-description.md#scans-file).
+Note that the onsets of the recordings SHOULD be stored in the study key file [(`scans.tsv`)](../modality-agnostic-files/data-summary-files.md#scans-file).
 Here, date-time information MUST be expressed as indicated in [Units](../common-principles.md#units).
-The [`scans.tsv`](../modality-agnostic-files/data-description.md#scans-file) file contains the filename and the acquisition time of a recording,
+The [`scans.tsv`](../modality-agnostic-files/data-summary-files.md#scans-file) file contains the filename and the acquisition time of a recording,
 which MAY be used to synchronize multiple recordings.
 
 ## Channels description (`*_channels.tsv`)
diff --git a/src/modality-specific-files/positron-emission-tomography.md b/src/modality-specific-files/positron-emission-tomography.md
index 4901f86e7d..a1ec4a4061 100644
--- a/src/modality-specific-files/positron-emission-tomography.md
+++ b/src/modality-specific-files/positron-emission-tomography.md
@@ -313,8 +313,8 @@ Knudsen et al. 2020
 ([doi:10.1177/0271678X20905433](https://doi.org/10.1177/0271678X20905433))
 recommends recording participant body weight.
 If recorded once per participant, these data SHOULD be included in the
-[Participants file](../modality-agnostic-files/data-description.md#participants-file) or as
-[Phenotypic and assessment data](../modality-agnostic-files/data-description.md#phenotypic-and-assessment-data).
+[Participants file](../modality-agnostic-files/data-summary-files.md#participants-file) or as
+[Phenotypic and assessment data](../modality-agnostic-files/data-summary-files.md#phenotypic-and-assessment-data).
 
 For example:
 
@@ -326,7 +326,7 @@ sub-03	72
 ```
 
 If multiple measurements are made, these data SHOULD be included in the
-[Sessions file](../modality-agnostic-files/data-description.md#sessions-file).
+[Sessions file](../modality-agnostic-files/data-summary-files.md#sessions-file).
 
 For example:
 
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index 479416eeab..885d54e91b 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -357,7 +357,7 @@ split:
     If there are multiple parts of a recording and the optional `scans.tsv` is provided,
     all files MUST be listed separately in `scans.tsv` and
     the entries for the `acq_time` column in `scans.tsv` MUST all be identical,
-    as described in [Scans file](SPEC_ROOT/modality-agnostic-files/data-description.md#scans-file).
+    as described in [Scans file](SPEC_ROOT/modality-agnostic-files/data-summary-files.md#scans-file).
   type: string
   format: index
 stain:
diff --git a/src/schema/objects/files.yaml b/src/schema/objects/files.yaml
index 513eb0a68c..b16a8c9c1d 100644
--- a/src/schema/objects/files.yaml
+++ b/src/schema/objects/files.yaml
@@ -116,7 +116,7 @@ phenotype:
     A directory where to store participant level measurements (for
     example responses from multiple questionnaires) split into
     individual files separate from `participants.tsv`.
-    See the [relevant section](SPEC_ROOT/modality-agnostic-files/data-description.md#phenotypic-and-assessment-data)
+    See the [relevant section](SPEC_ROOT/modality-agnostic-files/phenotypic-and-assessment-data.md)
     for more information.
 sourcedata:
   display_name: Source data
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index ad1cff2318..8af01e23a4 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -3164,7 +3164,7 @@ ScanDate:
   description: |
     Date of scan in the format `"YYYY-MM-DD[Z]"`.
     This field is DEPRECATED, and this metadata SHOULD be recorded in the `acq_time` column of the
-    corresponding [Scans file](SPEC_ROOT/modality-agnostic-files/data-description.md#scans-file).
+    corresponding [Scans file](SPEC_ROOT/modality-agnostic-files/data-summary-files.md#scans-file).
   type: string
   format: date
 ScanOptions:

From c78769ac9d1d7cfdef97d5bc91f019784c633331 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Boris=20Cl=C3=A9net?= <boris.clenet@inria.fr>
Date: Fri, 16 May 2025 09:19:08 +0200
Subject: [PATCH 09/11] Changes in redirects

---
 mkdocs.yml | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 462094e5f5..417fd616be 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -136,10 +136,7 @@ plugins:
       redirect_maps:
         "01-introduction.md": "introduction.md"
         "02-common-principles.md": "common-principles.md"
-        "03-modality-agnostic-files/01-dataset-description.md": "modality-agnostic-files/dataset-description.md"
-        "03-modality-agnostic-files/02-data-summary-files.md": "modality-agnostic-files/data-summary-files.md"
-        "03-modality-agnostic-files/03-phenotypic-and-assessment-data.md": "modality-agnostic-files/phenotypic-and-assessment-data.md"
-        "03-modality-agnostic-files/04-code.md": "modality-agnostic-files/code.md"
+        "03-modality-agnostic-files.md": "modality-agnostic-files/dataset-description.md"
         "04-modality-specific-files/01-magnetic-resonance-imaging-data.md": "modality-specific-files/magnetic-resonance-imaging-data.md"
         "04-modality-specific-files/02-magnetoencephalography.md": "modality-specific-files/magnetoencephalography.md"
         "04-modality-specific-files/03-electroencephalography.md": "modality-specific-files/electroencephalography.md"

From 820871f50e5d2026935e05dd752b9e5165a877f0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Boris=20Cl=C3=A9net?= <boris.clenet@inria.fr>
Date: Fri, 16 May 2025 15:03:27 +0200
Subject: [PATCH 10/11] Redirects update

---
 mkdocs.yml           | 1 +
 src/CHANGES.md       | 2 +-
 src/pregh-changes.md | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 417fd616be..2e5c7b3576 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -137,6 +137,7 @@ plugins:
         "01-introduction.md": "introduction.md"
         "02-common-principles.md": "common-principles.md"
         "03-modality-agnostic-files.md": "modality-agnostic-files/dataset-description.md"
+        "modality-agnostic-files.md": "modality-agnostic-files/dataset-description.md"
         "04-modality-specific-files/01-magnetic-resonance-imaging-data.md": "modality-specific-files/magnetic-resonance-imaging-data.md"
         "04-modality-specific-files/02-magnetoencephalography.md": "modality-specific-files/magnetoencephalography.md"
         "04-modality-specific-files/03-electroencephalography.md": "modality-specific-files/electroencephalography.md"
diff --git a/src/CHANGES.md b/src/CHANGES.md
index 8908abe800..6350df47e8 100644
--- a/src/CHANGES.md
+++ b/src/CHANGES.md
@@ -625,7 +625,7 @@
 ## 1.0.1-rc1
 
 -   Added T1 Rho maps: [4.1 Anatomy imaging data](modality-specific-files/magnetic-resonance-imaging-data.md#anatomy-imaging-data).
--   Added support for phenotypic information split into multiple files: [3.2 Participant key file](modality-agnostic-files/data-summary-files.md#participants-file).
+-   Added support for phenotypic information split into multiple files: [3.2 Participant key file](modality-agnostic-files.md#participants-file).
 -   Added recommendations for multi site datasets.
 -   Added `SoftwareVersions`.
 -   Added `run-<run_index>` to the phase encoding maps. Improved the description.
diff --git a/src/pregh-changes.md b/src/pregh-changes.md
index 7d9052b69d..2cba2a81df 100644
--- a/src/pregh-changes.md
+++ b/src/pregh-changes.md
@@ -32,7 +32,7 @@
 ## 1.0.1-rc1
 
 -   Added T1 Rho maps: [4.1 Anatomy imaging data](modality-specific-files/magnetic-resonance-imaging-data.md#anatomy-imaging-data).
--   Added support for phenotypic information split into multiple files: [3.2 Participant key file](modality-agnostic-files/data-summary-files.md#participants-file).
+-   Added support for phenotypic information split into multiple files: [3.2 Participant key file](modality-agnostic-files.md#participants-file).
 -   Added recommendations for multi site datasets.
 -   Added `SoftwareVersions`.
 -   Added `run-<run_index>` to the phase encoding maps. Improved the description.

From 52794c2e405accc7582fb45cdaf6a5676e9b8174 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Boris=20Cl=C3=A9net?= <boris.clenet@inria.fr>
Date: Fri, 16 May 2025 15:30:26 +0200
Subject: [PATCH 11/11] Redirects update

---
 src/CHANGES.md       | 2 +-
 src/pregh-changes.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/CHANGES.md b/src/CHANGES.md
index 6350df47e8..8908abe800 100644
--- a/src/CHANGES.md
+++ b/src/CHANGES.md
@@ -625,7 +625,7 @@
 ## 1.0.1-rc1
 
 -   Added T1 Rho maps: [4.1 Anatomy imaging data](modality-specific-files/magnetic-resonance-imaging-data.md#anatomy-imaging-data).
--   Added support for phenotypic information split into multiple files: [3.2 Participant key file](modality-agnostic-files.md#participants-file).
+-   Added support for phenotypic information split into multiple files: [3.2 Participant key file](modality-agnostic-files/data-summary-files.md#participants-file).
 -   Added recommendations for multi site datasets.
 -   Added `SoftwareVersions`.
 -   Added `run-<run_index>` to the phase encoding maps. Improved the description.
diff --git a/src/pregh-changes.md b/src/pregh-changes.md
index 2cba2a81df..7d9052b69d 100644
--- a/src/pregh-changes.md
+++ b/src/pregh-changes.md
@@ -32,7 +32,7 @@
 ## 1.0.1-rc1
 
 -   Added T1 Rho maps: [4.1 Anatomy imaging data](modality-specific-files/magnetic-resonance-imaging-data.md#anatomy-imaging-data).
--   Added support for phenotypic information split into multiple files: [3.2 Participant key file](modality-agnostic-files.md#participants-file).
+-   Added support for phenotypic information split into multiple files: [3.2 Participant key file](modality-agnostic-files/data-summary-files.md#participants-file).
 -   Added recommendations for multi site datasets.
 -   Added `SoftwareVersions`.
 -   Added `run-<run_index>` to the phase encoding maps. Improved the description.