From 50690653e78bf744b69b5b6200ba9abaff282d35 Mon Sep 17 00:00:00 2001 From: "Christopher J. Markiewicz" Date: Tue, 28 May 2019 11:02:42 -0400 Subject: [PATCH] FIX: Apply suggestions from @sappelhoff review --- CODEOWNERS | 5 ++-- src/02-common-principles.md | 9 ++++--- src/05-derivatives/01-introduction.md | 34 ++++++++++++++------------- 3 files changed, 24 insertions(+), 24 deletions(-) diff --git a/CODEOWNERS b/CODEOWNERS index a547d92f01..ce07f9ca43 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -11,10 +11,9 @@ # Individual sections /src/01-common-principles.md @chrisgorgo @DimitriPapadopoulos /src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md @chrisgorgo -/src/04-modality-specific-files/03-electroencephalography.md @sappelhoff +/src/04-modality-specific-files/03-electroencephalography.md @sappelhoff @ezemikulan +/src/04-modality-specific-files/04-intracranial-electroencephalography.md @ezemikulan /src/05-derivatives/03-structural-derivatives.md @edickie @ahoopes /src/05-derivatives/04-functional-derivatives.md @effigies /src/05-derivatives/05-diffusion-derivatives.md @francopestilli @oesteban -/src/04-modality-specific-files/03-electroencephalography.md @sappelhoff @ezemikulan -/src/04-modality-specific-files/04-intracranial-electroencephalography.md @ezemikulan /src/99-appendices/06-meg-file-formats.md @monkeyman192 diff --git a/src/02-common-principles.md b/src/02-common-principles.md index 967d74079e..d901da8524 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -96,11 +96,10 @@ However, in the case that these data are to be included: `sourcedata/sub-01/ses-pre/func/sub-01_ses-pre_task-rest_bold.dicom.tgz` or `sourcedata/sub-01/ses-pre/func/MyEvent.sce`. -1. A README file SHOULD be found at the root of the `sourcedata` folder - (or both). This file should describe the nature of the - raw data or the derived data. We RECOMMEND including the PDF print-out with - the actual sequence parameters generated by the scanner in the `sourcedata` - folder. +1. A README file SHOULD be found at the root of the `sourcedata` folder. + This file should describe the nature of the raw data or the derived data. + We RECOMMEND including the PDF print-out with the actual sequence + parameters generated by the scanner in the `sourcedata` folder. Alternatively one can organize their data in the following way diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md index 138a729eed..e6cc99e61b 100644 --- a/src/05-derivatives/01-introduction.md +++ b/src/05-derivatives/01-introduction.md @@ -17,8 +17,8 @@ Derivatives can be stored/distributed in two ways: RECOMMENDED to use the format `-` in cases where it is anticipated that the same pipeline will output more than one variant (e.g., `AFNI-blurring`, `AFNI-noblurring`, etc.). For the sake of consistency, the - subfolder name needs to be a substring of `PipelineDescription.Name` field - in the `dataset_description.json` (see below). + subfolder name MUST be a substring of `PipelineDescription.Name` field in + the `dataset_description.json` (see below). For example: @@ -32,17 +32,17 @@ Derivatives can be stored/distributed in two ways: dataset. This way of specifying derivatives is particularly useful when the source dataset is provided with read-only access, and for publishing derivatives as independent bodies of work, or for describing derivatives - that were created from more than one source dataset. It is consistent with - BIDS principles for the `sourcedata/` subdirectory to be used to include or - reference the source dataset(s) as it existed when the derivatives were - generated. Likewise, any code used to generate the derivatives from the - source data may be included in the `code/` subdirectory. + that were created from more than one source dataset. The `sourcedata/` + subdirectory MAY be used to include the source dataset(s) that were used + to generate the derivatives. + Likewise, any code used to generate the derivatives from the source data + MAY be included in the `code/` subdirectory. The rest of the Derivatives specification assumes Case 1, but Case 2 applies after removing `/derivatives/` from template names. In both cases every derivatives dataset is considered a BIDS dataset and must include a `dataset_description.json` file at the root level. Consequently, files should be -organized to comply with the BIDS to the full extent possible (i.e., unless +organized to comply with BIDS to the full extent possible (i.e., unless explicitly contradicted below). Any subject-specific derivatives should be housed within each subject’s directory; if session-specific derivatives are generated, they should be deposited under a session subdirectory within the @@ -90,9 +90,9 @@ Example: ## Coordinate systems -Coordinate system (a.k.a. space) a particular derivative is in should be denoted -using a filename keyword `space` whenever such keyword is present in the -filename template of a given derivative type. The allowed values for this +The coordinate system (a.k.a. space) a particular derivative is in SHOULD be +denoted using a filename keyword `space` whenever such keyword is present in +the filename template of a given derivative type. The allowed values for this keyword depend on the file format: | File format | Description | Allowed `CoordinateSystem` values | @@ -116,10 +116,11 @@ sub-01/func/sub-01_task-rest_space-HCPMNIfsLR32k_bold.nii ## Common file level metadata fields Each derivative file SHOULD be described by a JSON file provided as a sidecar or -higher up in the hierarchy of the derived dataset (according to Inheritance -Principle - section 3.5 of the main specification) unless a particular -derivative includes REQUIRED metadata fields in which case a JSON file is also -REQUIRED. Each derivative type defines their own set of fields, but all of them +higher up in the hierarchy of the derived dataset (according to +[The Inheritance Principle](../02-common-principles.md#the-inheritance-principle)) +unless a particular derivative includes REQUIRED metadata fields in which case a +JSON file is also REQUIRED. +Each derivative type defines their own set of fields, but all of them share the following (non-required) ones: | **Key name** | **Description** | @@ -174,7 +175,8 @@ sub-01/anat/sub-01_hemi-L_space-individual_thickness.json pertinent fields is very valuable and thus encouraged. Moreover, for some types of files, there may be one or more required metadata fields, in which case at least one metadata file containing that field must be located - somewhere within the file’s hierarchy (per the Inheritance Principle). + somewhere within the file’s hierarchy (per [the Inheritance + Principle](../02-common-principles.md#the-inheritance-principle)). - When chaining derivative pipelines, any JSON fields that were specified as mandatory in the input files should be propagated forward in the output