From bf015e63eee151196f811492e760f57335aba7b9 Mon Sep 17 00:00:00 2001
From: Cyril Pernet <wamcyril@gmail.com>
Date: Thu, 9 Nov 2023 17:04:06 +0100
Subject: [PATCH] [ENH] Add `descriptions.tsv` file relating to the
 `desc-<label>` entity (#1613)

* add descriptions.tsv

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* a little rewrite and removed +.md

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* remove BEP 28 mention

* Update src/derivatives/common-data-types.md

* Update src/derivatives/common-data-types.md

* Apply suggestions from code review

Co-authored-by: Remi Gau <remi_gau@hotmail.com>

* rebase, fix remark and latin, nicer linebreaks

* streamline language, fix errors

* remove part of the language

* desc_id -> label

* fix: description -> descriptions (plural)

* label -> desc_id

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Remi Gau <remi_gau@hotmail.com>
Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
---
 src/derivatives/common-data-types.md | 71 ++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/src/derivatives/common-data-types.md b/src/derivatives/common-data-types.md
index 486e733790..55ad6e3bf1 100644
--- a/src/derivatives/common-data-types.md
+++ b/src/derivatives/common-data-types.md
@@ -254,6 +254,77 @@ be propagated to the JSON description of the derivative unless the processing
 makes them invalid (for example, if a source 4D image is averaged to create a single
 static volume, a `RepetitionTime` property would no longer be relevant).
 
+## descriptions.tsv
+
+To keep a record of processing steps applied to the data, a `descriptions.tsv` file MAY be used.
+The `descriptions.tsv` file MUST contain at least the following two columns:
+
+-   `desc_id`
+-   `description`
+
+This file MAY be located at the root of the derivative dataset,
+or at the subject or session level
+([Inheritance Principle](../common-principles.md#the-inheritance-principle)).
+
+The `desc_id` column contains the labels used with the [`desc entity`](../appendices/entities.md#desc),
+within the particular nesting that the `descriptions.tsv` file is placed.
+For example, if the `descriptions.tsv` file is placed at the root of the derivative dataset,
+its `desc_id` column SHOULD contain all labels of the [`desc entity`](../appendices/entities.md#desc)
+used across the entire derivative dataset.
+
+The `description` column contains human-readable descriptions of the processing steps.
+
+The use of `descriptions.tsv` files together with the [`desc entity`](../appendices/entities.md#desc)
+are helpful to document how files are generated, even if their use may not be sufficient
+to provide full computational reproducibility.
+
+### Example use of a `descriptions.tsv` file
+
+<!-- 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___make_filetree_example(
+    {
+    "raw/": {
+        "CHANGES": "",
+        "README": "",
+        "channels.tsv": "",
+        "dataset_description.json": "",
+        "participants.tsv": "",
+            "sub-001": {
+                "eeg": {
+                    "sub-001_task-listening_events.tsv": "",
+                    "sub-001_task-listening_events.json": "",
+                    "sub-001_task-listening_eeg.edf": "",
+                    "sub-001_task-listening_eeg.json": "",
+                    },
+                },
+            },
+    "derivatives/": {
+        "descriptions.tsv": "",
+        "sub-001": {
+            "eeg": {
+                "sub-001_task-listening_desc-Filt_eeg.edf": "",
+                "sub-001_task-listening_desc-Filt_eeg.json": "",
+                "sub-001_task-listening_desc-FiltDs_eeg.edf": "",
+                "sub-001_task-listening_desc-FiltDs_eeg.json": "",
+                "sub-001_task-listening_desc-preproc_eeg.edf": "",
+                "sub-001_task-listening_desc-preproc_eeg.json": "",
+                },
+            },
+        }
+    }
+) }}
+
+Contents of the `descriptions.tsv` file:
+
+| desc_id | description                                                                                     |
+|---------|-------------------------------------------------------------------------------------------------|
+| Filt    | low-pass filtered at 30Hz                                                                       |
+| FiltDs  | low-pass filtered at 30Hz, downsampled to 250Hz                                                 |
+| preproc | low-pass filtered at 30Hz, downsampled to 250Hz, and rereferenced to a common average reference |
+
 <!-- Link Definitions -->
 
 [coordsys]: ../appendices/coordinate-systems.md#image-based-coordinate-systems