Merge pull request bids-standard#2177 from yarikoptic/enh-pipeline

DOC: make mentioning of pipeline_name consistent

Author: effigies

src/common-principles.md

@@ -309,7 +309,7 @@ Derivatives can be stored/distributed in two ways:
     Different components of a pipeline can, however, also be stored under different
     subdirectories.
     There are few restrictions on the directory names;
-    it is RECOMMENDED to use the format `<pipeline>-<variant>` in cases where
+    it is RECOMMENDED to use the format `<pipeline-name>-<variant>` in cases where
     it is anticipated that the same pipeline will output more than one variant
     (for example, `AFNI-blurring` and `AFNI-noblurring`).
     For the sake of consistency, the subdirectory name SHOULD be
@@ -381,7 +381,7 @@ Derivatives can be stored/distributed in two ways:
 
 Throughout this specification, if a section applies particularly to derivatives,
 then Case 1 will be assumed for clarity in templates and examples, but removing
-`/derivatives/<pipeline>` from the template name will provide the equivalent for
+`/derivatives/<pipeline-name>[-<variant>]` from the template name will provide the equivalent for
 Case 2.
 In both cases, every derivatives dataset is considered a BIDS dataset and must
 include a `dataset_description.json` file at the root level (see
@@ -423,8 +423,8 @@ A guide for using macros can be found at
             "..." : "",
         },
         "derivatives": {
-            "pipeline_1": {},
-            "pipeline_2": {},
+            "pipeline1-v1": {},
+            "pipeline2": {},
             "...": "",
         },
         "dataset_description.json": "",

src/derivatives/common-data-types.md

@@ -178,11 +178,11 @@ A guide for using macros can be found at
 Template:
 
 ```Text
-<pipeline_name>/
+<pipeline-name>/
     sub-<label>/
         [ses-<label>/]
             <datatype>/
-                <source_entities>[_space-<space>][_desc-<label>]_<suffix>.<extension>
+                <source-entities>[_space-<space>][_desc-<label>]_<suffix>.<extension>
 ```
 
 Data is considered to be *preprocessed* or *cleaned* if the data type of the input,

src/derivatives/imaging.md

@@ -8,11 +8,11 @@ extent and resolution.
 Template:
 
 ```Text
-<pipeline_name>/
+<pipeline-name>/
     sub-<label>/
         [ses-<label>/]
             <datatype>/
-                <source_entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
+                <source-entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
 ```
 
 Volumetric preprocessing does not modify the number of dimensions, and so
@@ -146,12 +146,12 @@ And the corresponding `sub-001_task-rest_run-1_space-fsLR_bold.json` file:
 Template:
 
 ```Text
-<pipeline_name>/
+<pipeline-name>/
     sub-<label>/
         [ses-<label>/]
             anat|func|dwi/
-                <source_entities>[_space-<space>][_res-<label>][_label-<label>][_desc-<label>]_mask.json
-                <source_entities>[_space-<space>][_res-<label>][_label-<label>][_desc-<label>]_mask.nii[.gz]
+                <source-entities>[_space-<space>][_res-<label>][_label-<label>][_desc-<label>]_mask.json
+                <source-entities>[_space-<space>][_res-<label>][_label-<label>][_desc-<label>]_mask.nii[.gz]
 ```
 
 A binary (1 - inside, 0 - outside) mask in the space defined by the [`space` entity](../appendices/entities.md#space).
@@ -265,13 +265,13 @@ of how integer values map to anatomical structures.
 Template:
 
 ```Text
-<pipeline_name>/
+<pipeline-name>/
     sub-<label>/
         [ses-<label>/]
             anat|func|dwi/
-                <source_entities>[_space-<space>][_seg-<label>][_res-<label>][_desc-<label>]_dseg.json
-                <source_entities>[_space-<space>][_seg-<label>][_res-<label>][_desc-<label>]_dseg.nii[.gz]
-                <source_entities>[_space-<space>][_seg-<label>][_res-<label>][_desc-<label>]_dseg.tsv
+                <source-entities>[_space-<space>][_seg-<label>][_res-<label>][_desc-<label>]_dseg.json
+                <source-entities>[_space-<space>][_seg-<label>][_res-<label>][_desc-<label>]_dseg.nii[.gz]
+                <source-entities>[_space-<space>][_seg-<label>][_res-<label>][_desc-<label>]_dseg.tsv
 ```
 
 Example:
@@ -332,12 +332,12 @@ the structure.
 Template:
 
 ```Text
-<pipeline_name>/
+<pipeline-name>/
     sub-<label>/
         [ses-<label>/]
             func|anat|dwi/
-                <source_entities>[_space-<space>][_seg-<label>][_res-<label>][_label-<label>][_desc-<label>]_probseg.json
-                <source_entities>[_space-<space>][_seg-<label>][_res-<label>][_label-<label>][_desc-<label>]_probseg.nii[.gz]
+                <source-entities>[_space-<space>][_seg-<label>][_res-<label>][_label-<label>][_desc-<label>]_probseg.json
+                <source-entities>[_space-<space>][_seg-<label>][_res-<label>][_label-<label>][_desc-<label>]_probseg.nii[.gz]
 ```
 
 Example:
@@ -408,14 +408,14 @@ CIFTI-2 dense label files, with the extension `.dlabel.nii`.
 Template:
 
 ```Text
-<pipeline_name>/
+<pipeline-name>/
     sub-<label>/
         [ses-<label>/]
             anat/
-                <source_entities>[_hemi-{L|R}][_space-<space>][_seg-<label>][_res-<label>][_den-<label>][_desc-<label>]_dseg.json
-                <source_entities>[_hemi-{L|R}][_space-<space>][_seg-<label>][_den-<label>][_desc-<label>]_dseg.label.gii
-                <source_entities>[_hemi-{L|R}][_space-<space>][_seg-<label>][_res-<label>][_den-<label>][_desc-<label>]_dseg.dlabel.nii
-                <source_entities>[_hemi-{L|R}][_space-<space>][_seg-<label>][_res-<label>][_den-<label>][_desc-<label>]_dseg.tsv
+                <source-entities>[_hemi-{L|R}][_space-<space>][_seg-<label>][_res-<label>][_den-<label>][_desc-<label>]_dseg.json
+                <source-entities>[_hemi-{L|R}][_space-<space>][_seg-<label>][_den-<label>][_desc-<label>]_dseg.label.gii
+                <source-entities>[_hemi-{L|R}][_space-<space>][_seg-<label>][_res-<label>][_den-<label>][_desc-<label>]_dseg.dlabel.nii
+                <source-entities>[_hemi-{L|R}][_space-<space>][_seg-<label>][_res-<label>][_den-<label>][_desc-<label>]_dseg.tsv
 ```
 
 The [`hemi-<label>`](../appendices/entities.md#hemi) entity is REQUIRED for GIFTI files storing information about

src/derivatives/introduction.md

@@ -60,12 +60,12 @@ in [Derived dataset and pipeline description][derived-dataset-description].
     copy of that raw file.
 
 -   Each Derivatives filename MUST be of the form:
-    `<source_entities>[_keyword-<value>]_<suffix>.<extension>`
+    `<source-entities>[_keyword-<value>]_<suffix>.<extension>`
     (where `<value>` could either be an `<index>` or a `<label>` depending on
     the keyword; see [Definitions][definitions])
 
 -   When the derivatives chain involves outputs derived from a single raw input,
-    `source_entities` MUST be the entire source filename, with the omission of
+    `source-entities` MUST be the entire source filename, with the omission of
     the source suffix and extension. One exception to this rule is filename
     entities that are no longer relevant. Depending on the nature of the
     derivative file, the suffix can either be the same as the source file if

src/modality-agnostic-files/dataset-description.md

@@ -111,7 +111,7 @@ Example:
 
 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`.
+`<dataset>/derivatives/<pipeline-name>/dataset_description.json`.
 
 In contrast to raw BIDS datasets, derived BIDS datasets MUST include a
 `GeneratedBy` key:
@@ -130,8 +130,8 @@ and a guide for using macros can be found at
 
 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>`.
+That is, in a directory `<dataset>/derivatives/<pipeline-name>[-<variant>]/`, the first
+`GeneratedBy` object should have a `Name` of `<pipeline-name>`.
 
 Example:
 

src/schema/objects/metaentities.yaml

@@ -43,11 +43,11 @@ matches:
 
     `<matches>` could correspond to `sub-control01_task-nback_run-1`.
 
-source_entities:
+source-entities:
   display_name: source entities
   description: |
-    `source_entities` is used as a placeholder in BIDS derivatives filenames templates.
+    `source-entities` is used as a placeholder in BIDS derivatives filenames templates.
 
-    `source_entities` MUST be the entire source filename, with the omission of
+    `source-entities` MUST be the entire source filename, with the omission of
     the source suffix and extension.
     One exception to this rule is filename entities that are no longer relevant.

src/schema/rules/metaentities.yaml

@@ -2,4 +2,4 @@
 # This file simply defines the order in which the meta-entities and placeholders are presented in the specification.
 # The actual term definitions appear in `objects/metaentities.yaml`.
 - matches
-- source_entities
+- source-entities

tools/schemacode/src/bidsschematools/render/text.py

@@ -266,7 +266,7 @@ def make_filename_template(
         If True, placeholder meta-entities will replace keyword-value entities in the
         filename.
         If ``dstype`` is ``"raw"``, the placeholder meta-entity is ``<matches>``.
-        If ``dstype`` is ``"derivatives"``, the placeholder meta-entity is ``<source_entities>``.
+        If ``dstype`` is ``"derivatives"``, the placeholder meta-entity is ``<source-entities>``.
         Default is False.
     empty_dirs: bool, optional
         If False, empty datatype directories are not included. If ``placeholders`` is True,
@@ -333,7 +333,7 @@ def make_filename_template(
     entity_list = schema.rules.entities
     start_string = ""
     if placeholders:
-        metaentity_name = "matches" if dstype == "raw" else "source_entities"
+        metaentity_name = "matches" if dstype == "raw" else "source-entities"
         start_string = (
             lt
             + utils._link_with_html(
@@ -501,7 +501,7 @@ def append_filename_template_legend(text, pdf_format=False):
     legend = f"""{info_str}
 - `<matches>` is a placeholder to denote an arbitrary (and valid) sequence of entities
   and labels at the beginning of the filename (only BIDS "raw").
-- `<source_entities>` is a placeholder to denote an arbitrary sequence of entities and labels
+- `<source-entities>` is a placeholder to denote an arbitrary sequence of entities and labels
   at the beginning of the filename matching a source file from which the file derives
   (only BIDS-Derivatives).
 - Filename entities or directories between square brackets