Templates and Atlases

Templates and altases included in the C-PAC Docker and Singularity images are maintained in a separate repository: FCP-INDI/C-PAC_templates and packaged in a c-pac_templates staging image.

Adding a template or atlas to be packaged in C-PAC

In a branch:

1. For the new file(s), fill in as much of the appropriate table(s) in README.md as you can. If no appropriate table exists in the README, add one.

2. If you had add a new table to the README, add a matching subdirectory under atlases/label.

3. Rename your file(s) to begin with the “Atlas name” you used in the README table, and use BIDS standard template identifiers [1] to identify the atlas/template’s space if possible.

4. Add your file(s).

   • If your file(s) are available from a reliable source,

     1. If they’re available in a reliable, web-accessible Docker image, use that image as a staging image and COPY the files directly from , e.g.

        COPY --from=ghcr.io/fcp-indi/c-pac/neuroparc:v1.0-human /ndmg_atlases /ndmg_atlases
        

     2. If they’re avilable in a GitHub repository,

        1. Clone into the GitHubPipelines staging image, e.g.,

           RUN git clone --branch v0.1.1 --depth 1 https://github.com/DCAN-Labs/dcan-macaque-pipeline.git && \
               git clone --branch v0.22.6-Edit_KRR_LITE_to_only_allow_for_corr_kernel https://github.com/ThomasYeoLab/CBIG.git && \
           

        2. Copy or move relevant files to a directory that does not contain any unnecessary files, e.g.

               # Washington University NHP Pipelines
               cd dcan-macaque-pipeline/global/templates && \
               mkdir -p /macaque_templates && \
               for FILE in $(ls MacaqueYerkes19*mm.nii.gz MacaqueYerkes19*mm_brain.nii.gz MacaqueYerkes19*brain_mask.nii.gz); \
               do cp $FILE /macaque_templates/$FILE; \
               done && \
               for FILE in $(ls JointLabelCouncil/MacaqueYerkes19_T1w_0.5mm/); \
               do cp JointLabelCouncil/MacaqueYerkes19_T1w_0.5mm/$FILE /macaque_templates/MacaqueYerkes19_T1w_0.5mm_desc-JLC_$FILE; \
               done && \
               for FILE in $(ls JointLabelCouncil/J_Macaque_11mo_atlas_nACQ_194x252x160space_0.5mm/); \
               do cp JointLabelCouncil/J_Macaque_11mo_atlas_nACQ_194x252x160space_0.5mm/$FILE /macaque_templates/J_Macaque_11mo_atlas_nACQ_194x252x160space_0.5mm_desc-JLC_$FILE; \
               done && \
               # CBIG
               mkdir -p /atlases/label/human && \
               for NODECOUNT in 200 300 400 1000; \
               do \
                 cp CBIG/stable_projects/brain_parcellation/Schaefer2018_LocalGlobal/Parcellations/MNI/Schaefer2018_${NODECOUNT}Parcels_17Networks_order_FSLMNI152_2mm.nii.gz /atlases/label/human/Schaefer2018_space-FSLMNI152_res-2mm_desc-${NODECOUNT}Parcels17NetworksOrder.nii.gz; \
               done
           

   • Otherwise, your file(s) to the appropriate subdirectory of atlases/label in your branch.

5. If adding to a directory not already being copied from the GitHubPipelines staging image to the final templates image, add a COPY command to copy the files over, e.g.,

   COPY --from=GitHubPipelines /macaque_templates/* /cpac_templates/
   COPY --from=GitHubPipelines /atlases/label/human/* /cpac_templates/
   

If your template or atlas is in a different path

If you’re adding your template or atlas to the c-pac_templates staging image in a location other than /cpac_templates/, update both the Bionic Beaver staging image and the Xenial Xerus staging image to COPY your files from the c-pac_templates staging image to each Ubuntu staging image, e.g.,

# Installing surface files for downsampling
COPY --from=c-pac_templates /opt/dcan-tools/pipeline/global/templates/standard_mesh_atlases/ /opt/dcan-tools/pipeline/global/templates/standard_mesh_atlases/
COPY --from=c-pac_templates /opt/dcan-tools/pipeline/global/templates/28224_Greyordinates/ /opt/dcan-tools/pipeline/global/templates/28224_Greyordinates/
COPY --from=c-pac_templates /opt/dcan-tools/pipeline/global/templates/8617_Greyordinates/ /opt/dcan-tools/pipeline/global/templates/8617_Greyordinates/

Testing your updates

You can use .github/Dockerfiles/cpac_templates.Dockerfile to build a custom c-pac_templates staging image, e.g.,

docker build -t cpac_templates:custom -f .github/Dockerfiles/cpac_templates.Dockerfile .  # <-- run in your modified fork or branch of FCP-INDI/C-PAC_templates
docker run --rm -dit \
  --name=CPACTemplates \
  -v cpac_templates:/cpac_templates \
  ghcr.io/fcp-indi/c-pac_templates:latest  # <-- Start a daemon image with your custom templates
docker run --rm -it \
  --volumes-from CPACTemplates \
  fcpindi/c-pac:nightly $BIDS_DIR $OUTPUTS_DIR participant  # <-- Use C-PAC as usual, but bind the custom /cpac_templates
docker attach CPACTemplates  # <-- Clean up when you're done
exit                         # <-- Clean up when you're done

Note

When you use --volumes-from to bind a directory that already exists in the image, the container will only be able to see the content from the bound daemon container, not any of the files in the original image. You can bind specific files instead of their parent directories to make files from the bound daemon container available in an existing directory in a container.

Once your changes have been merged to main, C-PAC will include them in each subsequent build.

References

[1]

BIDS-contributors. 2022. Appendix VIII: Coordinate systems standard template identifiers. The Brain Imaging Data Structure (BIDS) Specification, 1.7.0