Merge branch 'master' into update-pet-recon-method-recon-filter

bids-standard · Oct 21, 2022 · 3341a07 · 3341a07
2 parents d616e82 + 19db390
commit 3341a07
Show file tree

Hide file tree

Showing 28 changed files with 228 additions and 153 deletions.
diff --git a/.codespell_dict b/.codespell_dict
@@ -0,0 +1,6 @@
+sub-directory->subdirectory
+sub-directories->subdirectories
+file name->filename
+file names->filenames
+folder->directory
+folders->directories
diff --git a/.codespellrc b/.codespellrc
@@ -0,0 +1,6 @@
+[codespell]
+skip = *.js,*.svg,*.eps,.git
+ignore-words-list = fo,te,als
+builtin = clear,rare
+dictionary = .codespell_dict
+exclude-file = src/CHANGES.md
diff --git a/.github/workflows/redirect_circleci_artifacts.yml b/.github/workflows/redirect_circleci_artifacts.yml
@@ -2,6 +2,7 @@ on: [status]
 
 jobs:
   circleci_artifacts_redirector_job:
+    if: "${{ startsWith(github.event.context, 'ci/circleci: build_docs_pdf') }}"
     runs-on: ubuntu-latest
     name: Run CircleCI artifacts redirector
     steps:

diff --git a/.github/workflows/validation.yml b/.github/workflows/validation.yml
@@ -18,9 +18,6 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - uses: codespell-project/actions-codespell@master
-        with:
-          skip: js,*.svg,*.eps
-          ignore_words_list: fo,te,als
 
   # Markdown formatting
   remark:

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -12,3 +12,7 @@ repos:
       - id: check-ast
       - id: check-added-large-files
       - id: check-case-conflict
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.2
+    hooks:
+      - id: codespell
diff --git a/macros_doc.md b/macros_doc.md
@@ -80,17 +80,19 @@ consistency.
 All the macros we use are in listed in this
 [Python file](https://github.com/bids-standard/bids-specification/blob/master/tools/mkdocs_macros_bids/macros.py).
 
-| Name                     | Purpose                                                                                | Uses schema | Example                                                                                                                                                                                     |
-| ------------------------ | -------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| make_columns_table       | Generate a markdown table of TSV column information.                                   | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/03-modality-agnostic-files.md?plain=1#L202)                                    |
-| make_entity_table        | Generate an entity table from the schema, based on specific filters.                   | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/99-appendices/04-entity-table.md?plain=1#L23)                                  |
-| make_entity_definitions  | Generate definitions and other relevant information for entities in the specification. | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/99-appendices/09-entities.md?plain=1#L16)                                      |
-| make_filename_template   | Generate a filename template from the schema, based on specific filters.               | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/04-modality-specific-files/10-microscopy.md?plain=1#L21)                       |
-| make_filetree_example    | Generate a filetree snippet from example content.                                      | No          | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/02-common-principles.md?plain=1#L268)                                          |
-| make_glossary            |                                                                                        | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/99-appendices/14-glossary.md?plain=1#L9)                                       |
-| make_metadata_table      | Generate a markdown table of metadata field information.                               | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/02-common-principles.md?plain=1#L462)                                          |
-| make_suffix_table        | Generate a markdown table of suffix information.                                       | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md?plain=1#L199) |
-| define_common_principles | List the common principles and definitions.                                            | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/831ee55577b91aaa110153e9269e7829b095fb6f/src/02-common-principles.md?plain=1#L12)                                           |
+| Name                           | Purpose                                                                                | Uses schema | Example                                                                                                                                                                                     |
+| ------------------------------ | -------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| make_columns_table             | Generate a markdown table of TSV column information.                                   | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/03-modality-agnostic-files.md?plain=1#L202)                                    |
+| make_entity_table              | Generate an entity table from the schema, based on specific filters.                   | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/99-appendices/04-entity-table.md?plain=1#L23)                                  |
+| make_entity_definitions        | Generate definitions and other relevant information for entities in the specification. | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/99-appendices/09-entities.md?plain=1#L16)                                      |
+| make_filename_template         | Generate a filename template from the schema, based on specific filters.               | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/04-modality-specific-files/10-microscopy.md?plain=1#L21)                       |
+| make_filetree_example          | Generate a filetree snippet from example content.                                      | No          | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/02-common-principles.md?plain=1#L268)                                          |
+| make_glossary                  |                                                                                        | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/99-appendices/14-glossary.md?plain=1#L9)                                       |
+| make_metadata_table            | Generate a markdown table of metadata field information.                               | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/02-common-principles.md?plain=1#L462)                                          |
+| make_suffix_table              | Generate a markdown table of suffix information.                                       | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md?plain=1#L199) |
+| define_common_principles       | List the common principles and definitions.                                            | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/831ee55577b91aaa110153e9269e7829b095fb6f/src/02-common-principles.md?plain=1#L12)                                           |
+| define_allowed_top_directories | Create a list of allowed top-level directories with their descriptions.                | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/2a701fd034d51c25e8fe18ba67bb7b76621ba477/src/02-common-principles.md?plain=1#L124)                                          |
+
 
 ## When should I use a macro?
 

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
@@ -86,29 +86,40 @@ instead of specified with an `n/a` value, or included as an empty file
 
 ## Filesystem structure
 
-Data for each subject are placed in sub-directories named "`sub-<label>`",
+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](03-modality-agnostic-files.md#participants-file)
 in the root directory of the dataset.
 
 If data for the subject were acquired across multiple sessions, then within
-the subject directory resides sub-directories named "`ses-<label>`",
+the subject directory resides subdirectories named "`ses-<label>`",
 where string "`<label>`" is substituted with a unique identification
 label for each session.
 In datasets where at least one subject has more than one session, this
-additional sub-directory later SHOULD be added for all subjects in the dataset.
+additional subdirectory later SHOULD be added for all subjects in the dataset.
 Additional information on each session MAY be provided in a
 [sessions file](03-modality-agnostic-files.md#sessions-file)
 within the subject directory.
 
-Within the session sub-directory (or the subject sub-directory if no
-session sub-directories are present) are sub-directories named according to
+Within the session subdirectory (or the subject subdirectory if no
+session subdirectories are present) are subdirectories named according to
 data type as defined above.
 A data type directory SHOULD NOT be defined if there are no files to be placed
 in that directory.
 
+### Other top level directories
+
+In addition to the subject directories, the root directory of a BIDS dataset
+MAY also contain the following directories:
+
+<!-- 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___define_allowed_top_directories() }}
+
 ## Filenames
 
 A filename consists of a chain of *entity instances* and a *suffix*

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -167,7 +167,7 @@ whenever possible. See also
 
 <!--
 This block generates a filename templates.
-The inputs for this macro can be found in the folder
+The inputs for this macro can be found in the directory
   src/schema/rules/datatypes
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
@@ -359,7 +359,7 @@ and a guide for using macros can be found at
 
 <!--
 This block generates a filename templates.
-The inputs for this macro can be found in the folder
+The inputs for this macro can be found in the directory
   src/schema/rules/datatypes
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
@@ -567,7 +567,7 @@ and a guide for using macros can be found at
 
 <!--
 This block generates a filename templates.
-The inputs for this macro can be found in the folder
+The inputs for this macro can be found in the directory
   src/schema/rules/datatypes
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
@@ -777,7 +777,7 @@ and can be used for practical guidance when curating a new dataset.
 
 <!--
 This block generates a filename templates.
-The inputs for this macro can be found in the folder
+The inputs for this macro can be found in the directory
   src/schema/rules/datatypes
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
@@ -1009,7 +1009,7 @@ containing that type of fieldmap can be found here:
 
 <!--
 This block generates a filename templates.
-The inputs for this macro can be found in the folder
+The inputs for this macro can be found in the directory
   src/schema/rules/datatypes
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
@@ -1055,7 +1055,7 @@ second echos are available.
 
 <!--
 This block generates a filename templates.
-The inputs for this macro can be found in the folder
+The inputs for this macro can be found in the directory
   src/schema/rules/datatypes
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
@@ -1091,7 +1091,7 @@ In some cases (for example GE), the scanner software will directly reconstruct a
 
 <!--
 This block generates a filename templates.
-The inputs for this macro can be found in the folder
+The inputs for this macro can be found in the directory
   src/schema/rules/datatypes
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
@@ -1140,7 +1140,7 @@ AFNI `3dqwarp`.
 
 <!--
 This block generates a filename templates.
-The inputs for this macro can be found in the folder
+The inputs for this macro can be found in the directory
   src/schema/rules/datatypes
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md

diff --git a/src/04-modality-specific-files/02-magnetoencephalography.md b/src/04-modality-specific-files/02-magnetoencephalography.md
@@ -18,7 +18,7 @@ the [BIDS examples repository](https://github.com/bids-standard/bids-examples).
 
 <!--
 This block generates a filename templates.
-The inputs for this macro can be found in the folder
+The inputs for this macro can be found in the directory
   src/schema/rules/datatypes
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
@@ -162,7 +162,7 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_sidecar_table("meg.MEGwithEEG") }}
 
-Example:
+#### Example `*_meg.json`
 
 ```JSON
 {
@@ -203,7 +203,7 @@ Date time information MUST be expressed as indicated in [Units](../02-common-pri
 
 <!--
 This block generates a filename templates.
-The inputs for this macro can be found in the folder
+The inputs for this macro can be found in the directory
   src/schema/rules/datatypes
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
@@ -268,12 +268,18 @@ Note that upper-case is REQUIRED:
 | FITERR           | Fit error signal from each head localization coil    |
 | OTHER            | Any other type of channel                            |
 
-Example of free text for field `description`:
+Examples of free text for field `description`:
 
--   stimulus, response, vertical EOG, horizontal EOG, skin conductance, sats,
-    intracranial, eyetracker
+-   stimulus
+-   response
+-   vertical EOG
+-   horizontal EOG
+-   skin conductance
+-   sats
+-   intracranial
+-   eyetracker
 
-Example:
+### Example `*_channels.tsv`
 
 ```Text
 name type units description
@@ -287,7 +293,7 @@ UADC001 AUDIO V envelope of audio signal presented to participant
 
 <!--
 This block generates a filename templates.
-The inputs for this macro can be found in the folder
+The inputs for this macro can be found in the directory
   src/schema/rules/datatypes
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
@@ -400,7 +406,7 @@ Photos of the anatomical landmarks and/or head localization coils
 
 <!--
 This block generates a filename templates.
-The inputs for this macro can be found in the folder
+The inputs for this macro can be found in the directory
   src/schema/rules/datatypes
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
@@ -418,6 +424,8 @@ The [`acq-<label>`](../appendices/entities.md#acq) entity can be used to indicat
 the same face (or other body part in different angles to show, for example, the
 location of the nasion (NAS) as opposed to the right periauricular point (RPA)).
 
+### Example `*_photo.jpg`
+
 Example of the NAS fiducial placed between the eyebrows, rather than at the
 actual anatomical nasion: `sub-0001_ses-001_acq-NAS_photo.jpg`
 
@@ -427,7 +435,7 @@ actual anatomical nasion: `sub-0001_ses-001_acq-NAS_photo.jpg`
 
 <!--
 This block generates a filename templates.
-The inputs for this macro can be found in the folder
+The inputs for this macro can be found in the directory
   src/schema/rules/datatypes
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
@@ -443,7 +451,7 @@ a session, for example when the head points are in a separate file from the EEG
 locations. These files are stored in the specific format of the 3-D digitizer’s
 manufacturer (see the [MEG File Formats Appendix](../appendices/meg-file-formats.md)).
 
-Example:
+For example:
 
 <!-- This block generates a file tree.
 A guide for using macros can be found at
@@ -470,8 +478,8 @@ Empty-room MEG recordings capture the environmental and recording system's noise
 
 It is RECOMMENDED to explicitly specify which empty-room recording should be used with which experimental run(s) or session(s). This can be done via the [`AssociatedEmptyRoom`](../glossary.md#associatedemptyroom-metadata) field in the `*_meg.json` sidecar files.
 
-Empty-room recordings may be collected once per day, where a single empty-room recording may be shared between multiple subjects and/or sessions (see example 1).
-Empty-room recordings can also be collected for each individual experimental session (see example 2).
+Empty-room recordings may be collected once per day, where a single empty-room recording may be shared between multiple subjects and/or sessions (see [Example 1](#example-1)).
+Empty-room recordings can also be collected for each individual experimental session (see [Example 2](#example-2)).
 
 In the case of empty-room recordings being associated with multiple subjects and/or sessions, it is RECOMMENDED to store the empty-room recording inside a subject directory named `sub-emptyroom`.
 If a [`session-<label>`](../appendices/entities.md#ses) entity is present, its label SHOULD be the date of the empty-room recording in the format `YYYYMMDD`, that is `ses-YYYYMMDD`.
@@ -483,7 +491,7 @@ In the case of empty-room recordings being collected for the individual experime
 
 In either case, the label for the [`task-<label>`](../appendices/entities.md#task) entity in the empty-room recording SHOULD be set to `noise`.
 
-Example 1:
+### Example 1
 
 One empty-room recording per day, applying to all subjects for that day.
 
@@ -508,9 +516,9 @@ A guide for using macros can be found at
    }
 ) }}
 
-Example 2:
+### Example 2
 
-One recording per session, stored within the session folder.
+One recording per session, stored within the session directory.
 
 <!-- This block generates a file tree.
 A guide for using macros can be found at
@@ -533,5 +541,3 @@ A guide for using macros can be found at
       },
    }
 ) }}
-
-<!-- Link Definitions -->