Finalize BIDS Atlas compliance (#1584)

Co-authored-by: Ross Blair <rosswilsonblair@gmail.com>

Author: tsalo

.circleci/config.yml

@@ -5,7 +5,7 @@ orbs:
 .dockersetup:
   &dockersetup
   docker:
-    - image: pennlinc/xcp_d_build:0.0.22
+    - image: pennlinc/xcp_d_build:0.0.24
   working_directory: /src/xcp_d
 
 runinstall:
@@ -77,15 +77,15 @@ jobs:
     steps:
       - checkout
       - restore_cache:
-          key: schaefer100-02
+          key: schaefer100-05
       - run: *runinstall
       - run:
           name: Download BIDS-Atlas dataset
           command: |
             cd /src/xcp_d/.circleci
             python get_data.py $PWD/data schaefer100
       - save_cache:
-          key: schaefer100-02
+          key: schaefer100-05
           paths:
             - /src/xcp_d/.circleci/data/schaefer100
 
@@ -179,7 +179,7 @@ jobs:
       - restore_cache:
           key: fmriprepwithoutfreesurfer-03
       - restore_cache:
-          key: schaefer100-02
+          key: schaefer100-05
       - run: *runinstall
       - run:
           name: Run full xcp_d on nifti without freesurfer
@@ -525,7 +525,7 @@ jobs:
       - restore_cache:
           key: nibabies-04
       - restore_cache:
-          key: schaefer100-02
+          key: schaefer100-05
       - run: *runinstall
       - run:
           name: Run pytest on the tests directory

Dockerfile

@@ -1,4 +1,4 @@
-FROM pennlinc/xcp_d_build:0.0.22
+FROM pennlinc/xcp_d_build:0.0.24
 
 # Install xcp_d
 COPY . /src/xcp_d

docs/outputs.rst

@@ -21,7 +21,6 @@ The  *XCP-D* outputs are written out in BIDS format and consist of three main pa
    `BEP012: Functional preprocessing derivatives <https://github.com/bids-standard/bids-specification/pull/519>`_,
    `BEP017: Relationship & connectivity matrix data schema <https://docs.google.com/document/d/1ugBdUF6dhElXdj3u9vw0iWjE6f_Bibsro3ah7sRV0GA/edit?usp=sharing>`_,
    and
-   `BEP038: Atlas Specification <https://docs.google.com/document/d/1RxW4cARr3-EiBEcXjLpSIVidvnUSHE7yJCUY91i5TfM/edit?usp=sharing>`_.
 
    In cases where a derivative type is not covered by an existing BEP,
    we have simply attempted to follow the general principles of BIDS.
@@ -97,22 +96,19 @@ For more information about the 4S atlas, please see https://github.com/PennLINC/
    You can also skip other postprocessing steps using the ``--skip`` parameter.
    See :ref:`usage_cli` for more information about the ``--skip`` parameter.
 
-Atlases are written out to the ``atlases`` subfolder, following BEP038.
+Atlases are written out to the ``atlases`` subfolder, following BIDS formatting.
 
 .. code-block::
 
    xcp_d/
       atlases/
          dataset_description.json
-         atlas-<label>/
-            atlas-<label>_dseg.json
-            atlas-<label>_dseg.tsv
-
-            # NIfTI
-            atlas-<label>_space-<label>_dseg.nii.gz
-
-            # CIFTI
-            atlas-<label>_space-<label>_dseg.dlabel.nii
+         atlas-<label>_description.json
+         tpl-<label>/
+            tpl-<label>_atlas-<label>[_res-<label>][_den-<label>][_desc-<label>]_dseg.json
+            tpl-<label>_atlas-<label>[_res-<label>][_den-<label>][_desc-<label>]_dseg.tsv
+            tpl-<label>_atlas-<label>[_res-<label>][_den-<label>][_desc-<label>]_dseg.nii.gz
+            tpl-<label>_atlas-<label>[_res-<label>][_den-<label>][_desc-<label>]_dseg.dlabel.nii
 
 
 ******************

docs/usage.rst

@@ -587,31 +587,24 @@ External Atlases
 While *XCP-D* comes with many built-in parcellations,
 we understand that many users will want to use different ones.
 
-As long as the parcellation is organized in a BIDS-Atlas dataset and is in
+As long as the parcellation is organized according to BIDS v1.11.0 and is in
 fsLR-32k space (for CIFTI processing) or
 MNIInfant, MNI152NLin6Asym, or MNI152NLin2009cAsym space (for NIfTI processing),
 you can use it with *XCP-D*.
 
-.. warning::
-   BIDS Extension Proposal 38 (Atlas Specification) has not been integrated in BIDS yet,
-   so the organization and naming for atlas datasets may change in the future.
-
-   We have attempted to follow the proposed structure in *XCP-D*,
-   but we cannot guarantee that this will not change.
-
 .. tip::
    The main elements from the BIDS-Atlas dataset that *XCP-D* uses are:
 
-   1. There must be a dataset_description.json file with DatasetType set to "atlas".
+   1. There must be a dataset_description.json file with DatasetType set to "derivative".
    2. The atlas metadata files must have the same entities as the atlas image files,
-      as PyBIDS does not support the inheritance principle when querying BIDS-Atlas datasets (yet).
-   3. There must be a TSV file for the atlas, with "index" and "label" columns.
+      as PyBIDS does not support the inheritance principle when querying atlas datasets (yet).
+   3. There must be a TSV file for the atlas, with "index" and "name" columns.
 
 To do this, use the ``--datasets`` and ``--atlases`` parameters.
 The ``--datasets`` parameter should point to the directory containing the BIDS-Atlas dataset,
 and the ``--atlases`` parameter should include the names of the atlases in the dataset to use.
 
-For example, consider a scenario where you have two BIDS-Atlas datasets, one containing all of the
+For example, consider a scenario where you have two BIDS atlas datasets, one containing all of the
 Schaefer 2018 resolutions and one containing the AAL atlas.
 These datasets are in ``/data/atlases/schaefer`` and ``/data/atlases/aal``, respectively.
 The file structure for these two datasets might look like this:
@@ -621,25 +614,28 @@ The file structure for these two datasets might look like this:
    /data/atlases/
       schaefer/
          dataset_description.json
-         atlas-Schaefer100/
-            atlas-Schaefer100_dseg.tsv
-            atlas-Schaefer100_space-fsLR_den-32k_dseg.dlabel.nii
-            atlas-Schaefer100_space-fsLR_den-32k_dseg.json
-         atlas-Schaefer200/
-            atlas-Schaefer200_dseg.tsv
-            atlas-Schaefer200_space-fsLR_den-32k_dseg.dlabel.nii
-            atlas-Schaefer200_space-fsLR_den-32k_dseg.json
+         atlas-Schaefer100_description.json
+         atlas-Schaefer200_description.json
          ...
-         atlas-Schaefer1000/
-            atlas-Schaefer1000_dseg.tsv
-            atlas-Schaefer1000_space-fsLR_den-32k_dseg.dlabel.nii
-            atlas-Schaefer1000_space-fsLR_den-32k_dseg.json
+         atlas-Schaefer1000_description.json
+         tpl-fsLR/
+            tpl-fsLR_atlas-Schaefer100_den-32k_dseg.dlabel.nii
+            tpl-fsLR_atlas-Schaefer100_den-32k_dseg.json
+            tpl-fsLR_atlas-Schaefer100_den-32k_dseg.tsv
+            tpl-fsLR_atlas-Schaefer200_den-32k_dseg.dlabel.nii
+            tpl-fsLR_atlas-Schaefer200_den-32k_dseg.json
+            tpl-fsLR_atlas-Schaefer200_den-32k_dseg.tsv
+            ...
+            tpl-fsLR_atlas-Schaefer1000_den-32k_dseg.dlabel.nii
+            tpl-fsLR_atlas-Schaefer1000_den-32k_dseg.json
+            tpl-fsLR_atlas-Schaefer1000_den-32k_dseg.tsv
       aal/
          dataset_description.json
-         atlas-AAL/
-            atlas-AAL_dseg.tsv
-            atlas-AAL_space-fsLR_den-32k_dseg.dlabel.nii
-            atlas-AAL_space-fsLR_den-32k_dseg.json
+         atlas-AAL_description.json
+         tpl-fsLR/
+            tpl-fsLR_atlas-AAL_den-32k_dseg.dlabel.nii
+            tpl-fsLR_atlas-AAL_den-32k_dseg.json
+            tpl-fsLR_atlas-AAL_den-32k_dseg.tsv
 
 You may want to only apply the Schaefer100 atlas from the ``schaefer`` dataset and the AAL atlas
 from the ``aal`` dataset, along with one of *XCP-D*'s built-in atlases (``4S156Parcels``).
@@ -653,7 +649,7 @@ Here's what the *XCP-D* call might look like:
       /home/user/data/path/to/output_dir \
       participant \ # analysis_level
       --mode <mode> \ # required
-      --datasets schaefer=/home/user/data/path/to/schaefer_atlas aal==/home/user/data/path/to/aal_atlas \
+      --datasets schaefer=/data/atlases/schaefer aal==/data/atlases/aal \
       --atlases Schaefer100 AAL 4S156Parcels
 
 *XCP-D* will search for ``atlas-Schaefer100``, ``atlas-AAL``, and ``atlas-4S156Parcels`` across the
@@ -662,7 +658,7 @@ If the atlases are found, then they will be used for parcellation.
 
 .. important::
 
-   Atlas names must be unique across BIDS-Atlas datasets.
+   Atlas names must be unique across BIDS atlas datasets.
    If two atlases have the same name, *XCP-D* will raise an error.
 
 

xcp_d/cli/parser.py

@@ -1181,7 +1181,7 @@ def _validate_parameters(opts, build_log, parser):
             opts.skip_outputs.append('parcellation')
     if opts.atlases:
         if 'xcpdatlases' not in opts.datasets:
-            opts.datasets['xcpdatlases'] = load_data('atlases')
+            opts.datasets['xcpdatlases'] = Path('/XCPDAtlases')
 
         if any(atlas.startswith('4S') for atlas in opts.atlases):
             if 'xcpd4s' not in opts.datasets:

xcp_d/cli/run.py

@@ -167,7 +167,9 @@ def main():
         )
 
         if config.execution.atlases:
-            write_atlas_dataset_description(config.execution.output_dir / 'atlases')
+            write_atlas_dataset_description(
+                config.execution.output_dir / 'derivatives' / 'atlases'
+            )
 
         # Generate reports phase
         failed_reports = generate_reports(

xcp_d/data/atlas_bids_config.json

@@ -2,13 +2,18 @@
     "name": "atlas",
     "entities": [
         {
-            "name": "atlas",
-            "pattern": "[/\\\\]+atlas-([a-zA-Z0-9]+)",
-            "directory": "{atlas}"
+            "name": "template",
+            "pattern": "[_/\\\\]+tpl-([a-zA-Z0-9+]+)",
+            "directory": "{template}"
+        },
+        {
+            "name": "cohort",
+            "pattern": "[_/\\\\]+cohort-([a-zA-Z0-9+]+)",
+            "directory": "{cohort}"
         },
         {
-            "name": "space",
-            "pattern": "[_/\\\\]+space-([a-zA-Z0-9]+)"
+            "name": "atlas",
+            "pattern": "[_/\\\\]+atlas-([a-zA-Z0-9+]+)"
         },
         {
             "name": "hemi",
@@ -24,7 +29,7 @@
         },
         {
             "name": "desc",
-            "pattern": "[_/\\\\]+desc-([a-zA-Z0-9]+)"
+            "pattern": "[_/\\\\]+desc-([a-zA-Z0-9+]+)"
         },
         {
             "name": "suffix",
@@ -36,9 +41,9 @@
         }
     ],
     "default_path_patterns": [
-        "atlas-{atlas}/atlas-{atlas}[_space-{space}][_res-{res}][_desc-{desc}]_{suffix<dseg|probseg|mask>}.{extension<nii|nii.gz|json>|nii.gz}",
-        "atlas-{atlas}/atlas-{atlas}[_space-{space}][_res-{res}][_den-{den}][_desc-{desc}]_{suffix<dseg|probseg|mask>}.{extension<dlabel.nii|json>|dlabel.nii}",
-        "atlas-{atlas}/atlas-{atlas}[_hemi-{hemi}][_space-{space}][_den-{den}][_desc-{desc}]_{suffix<dseg|probseg|mask>}.{extension<label.gii|json>|label.gii}",
-        "atlas-{atlas}/atlas-{atlas}[_space-{space}][_desc-{desc}]_{suffix<dseg|probseg|mask>}.{extension<tsv|json>|tsv}"
+        "tpl-{template}/[cohort-{cohort}]/tpl-{template}[_cohort-{cohort}]_atlas-{atlas}[_res-{res}][_desc-{desc}]_{suffix<dseg|probseg|mask>}.{extension<nii|nii.gz|json>|nii.gz}",
+        "tpl-{template}/[cohort-{cohort}]/tpl-{template}[_cohort-{cohort}]_atlas-{atlas}[_res-{res}][_den-{den}][_desc-{desc}]_{suffix<dseg|probseg|mask>}.{extension<dlabel.nii|json>|dlabel.nii}",
+        "tpl-{template}/[cohort-{cohort}]/tpl-{template}[_cohort-{cohort}]_atlas-{atlas}[_hemi-{hemi}][_den-{den}][_desc-{desc}]_{suffix<dseg|probseg|mask>}.{extension<label.gii|json>|label.gii}",
+        "tpl-{template}/[cohort-{cohort}]/tpl-{template}[_cohort-{cohort}]_atlas-{atlas}[_res-{res}][_den-{den}][_desc-{desc}]_{suffix<dseg|probseg|mask>}.{extension<tsv|json>|tsv}"
     ]
 }