From d20b5d1fde903037014e03bf5a02ab4bf342e3ca Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Tue, 24 Oct 2023 18:58:17 +0200 Subject: [PATCH] rebase, fix remark and latin, nicer linebreaks --- src/derivatives/common-data-types.md | 37 +++++++++++++++++----------- 1 file changed, 23 insertions(+), 14 deletions(-) diff --git a/src/derivatives/common-data-types.md b/src/derivatives/common-data-types.md index 589e3c95a4..6a7ddd58d9 100644 --- a/src/derivatives/common-data-types.md +++ b/src/derivatives/common-data-types.md @@ -252,19 +252,28 @@ A guide for using macros can be found at All REQUIRED metadata fields coming from a derivative file’s source file(s) MUST 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). As each file -includes what was computed by increment, a trail of the computational steps performed -is created. Because many steps can occur until the fully clean data are obtained and -because it is OPTIONAL to save every file or step, the simpler `desc-preproc` -and `desc-proc` are available. It becomes however important to document what such -pre-processing or processing are, and record the order of computational steps. This -can be done in the JSON sidecar files or alternatively described in a `descriptions.tsv` file. +static volume, a `RepetitionTime` property would no longer be relevant). +As each file includes what was computed by increment, +a trail of the computational steps performed is created. +Because many steps can occur until the fully clean data are obtained, +and because it is OPTIONAL to save every file or step, +the simpler `desc-preproc` and `desc-proc` are available. +It becomes however important to document what such pre-processing or processing are, +and record the order of computational steps. +This can be done in the JSON sidecar files or alternatively described in a `descriptions.tsv` file. ## descriptions.tsv -To keep a record of what has been done to the data, a `descriptions.tsv` file can be used, containing at least two columns: `desc_id` and `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))). +To keep a record of what has been done to the data, a `descriptions.tsv` file can be used, +containing at least two columns: `desc_id` and `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))). -`desc_id` contains all labels used in the [`desc entity`](../appendices/entities.md#desc), while `description` is a human-readable description of what was computed. Note that while it is helpful to document how files are generated, we see this as 'light provenance', i.e. it is not aimed at providing full computational reproducibility. +`desc_id` contains all labels used in the [`desc entity`](../appendices/entities.md#desc), +while `description` is a human-readable description of what was computed. +Note that while it is helpful to document how files are generated, we see this as *light provenance*, +that is, it is not aimed at providing full computational reproducibility. {{ MACROS___make_filetree_example( { @@ -300,11 +309,11 @@ To keep a record of what has been done to the data, a `descriptions.tsv` file ca `descriptions.tsv` -| 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 | +| 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 |