Merge remote-tracking branch 'upstream/master' into spec-trace

.github/workflows/shellcheck.yml

@@ -0,0 +1,26 @@
+---
+name: Shellcheck
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  shellcheck:
+    name: Check shell scripts
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install dependencies
+        run: |
+          sudo apt update && sudo apt install -y shellcheck
+      - name: shellcheck
+        run: |
+          git grep -l '^#\( *shellcheck \|!\(/bin/\|/usr/bin/env \)\(sh\|bash\|dash\|ksh\)\)' | xargs shellcheck

.pre-commit-config.yaml

@@ -1,5 +1,7 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
+ci:
+  skip: [shellcheck]
 exclude: 'tools/schemacode/bidsschematools/tests/data/broken_dataset_description.json'
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
@@ -13,7 +15,7 @@ repos:
       - id: check-added-large-files
       - id: check-case-conflict
   - repo: https://github.com/psf/black
-    rev: 24.4.0
+    rev: 24.4.2
     hooks:
       - id: black
         files: ^tools/(?!schemacode)
@@ -55,7 +57,7 @@ repos:
       - id: codespell
         args: ["--config=.codespellrc", "--dictionary=-", "--dictionary=.codespell_dict"]
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.9.0
+    rev: v1.10.0
     hooks:
       - id: mypy
         # Sync with project.optional-dependencies.typing
@@ -71,3 +73,7 @@ repos:
           - types-jsonschema
         args: ["tools/schemacode/bidsschematools"]
         pass_filenames: false
+  - repo: https://github.com/koalaman/shellcheck-precommit
+    rev: v0.10.0
+    hooks:
+      - id: shellcheck

scripts/test_tag

@@ -9,7 +9,7 @@
 EPOCH="$(date +%s)"
 
 GIT_DIR=$( git rev-parse --git-dir )
-REPO_ROOT=$( ls -d ${GIT_DIR%.git} )
+REPO_ROOT=$( ls -d "${GIT_DIR%.git}" )
 
 VERSION_FILE="$REPO_ROOT/src/schema/SCHEMA_VERSION"
 

src/common-principles.md

@@ -658,6 +658,21 @@ for more information.
 
 ## The Inheritance Principle
 
+In some circumstances, there can be multiple data files for which
+all or a subset of the relevant metadata is precisely equivalent.
+Where this occurs,
+it may be preferable to define those metadata *only once*,
+and be placed on the filesystem in such a way that those files
+are deemed to be *applicable* to each relevant data file individually,
+but *not* be erroneously associated with other data files
+to which the metadata contained within are not applicable.
+The Inheritance Principle defines a systematized set of rules
+to determine which metadata files to associate with which data files.
+Further, because multiple metadata files may apply to an individual data file,
+the Principle defines the *order of precedence* of such metadata files contents.
+
+### Rules
+
 1.  Any metadata file (such as `.json`, `.bvec` or `.tsv`) MAY be defined at any directory level.
 
 1.  For a given data file, any metadata file is applicable to that data file if:
@@ -687,7 +702,7 @@ for more information.
         same key present in another metadata file at a lower level
         (though it is RECOMMENDED to minimize the extent of such overrides).
 
-Corollaries:
+### Corollaries
 
 1.  As per rule 3, metadata files applicable only to a specific participant / session
     MUST be defined in or below the directory corresponding to that participant / session;
@@ -704,6 +719,8 @@ Corollaries:
     a key-value in a later file does not imply the "unsetting" of that field
     (indeed removal of existing fields is not possible).
 
+### Examples
+
 Example 1: Demonstration of inheritance principle
 
 <!-- This block generates a file tree.

src/longitudinal-and-multi-site-studies.md

@@ -80,7 +80,7 @@ for practical guidance when curating a new longitudinal dataset.
 
 This version of the BIDS specification does not explicitly cover studies with
 data coming from multiple sites or multiple centers (such extension is planned
-in [BIDS `2.0`](https://github.com/bids-standard/bids-2-devel).
+in [BIDS `2.0`](https://github.com/bids-standard/bids-2-devel/issues/11)).
 There are however ways to model your data without any loss in terms of metadata.
 
 ### Option 1: Treat each site/center as a separate dataset
@@ -92,11 +92,21 @@ Apps and everything should just work.
 
 ### Option 2: Combining sites/centers into one dataset
 
-Alternatively you can combine data from all sites into one dataset. To identify
-which site each subjects comes from you can add a `site` column in the
+Alternatively you can combine data from all sites into one dataset.
+This can be done in two ways:
+
+
+#### Option 2.a: Collate sites at subject level
+
+To identify which site each subjects comes from you can add a `site` column in the
 `participants.tsv` file indicating the source site. This solution allows you to
-analyze all of the subjects together in one dataset. One caveat is that subjects
+analyze all subjects together in one dataset. One caveat is that subjects
 from all sites will have to have unique labels. To enforce that and improve
 readability you can use a subject label prefix identifying the site. For example
 `sub-NUY001`, `sub-MIT002`, `sub-MPG002` and so on. Remember that hyphens and
 underscores are not allowed in subject labels.
+
+#### Option 2.b: Use different sessions for different sites
+
+In case of studies such as "Traveling Human Phantom" it is possible to incorporate site within session label.
+For example `sub-human1/ses-NUY`, `sub-human1/ses-MIT`, `sub-phantom1/ses-NUY`, `sub-phantom1/ses-MIT` and so on.