Merge branch 'main' into fix-collection

.circleci/config.yml

@@ -5,7 +5,7 @@ orbs:
 .dockersetup:
   &dockersetup
   docker:
-    - image: pennlinc/xcp_d_build:0.0.6rc15
+    - image: pennlinc/xcp_d_build:0.0.7
   working_directory: /src/xcp_d
 
 runinstall:

CITATION.cff

@@ -86,5 +86,5 @@ keywords:
   - BIDS-App
   - Neuroimaging
 license: BSD-3-Clause
-version: 0.4.0
-date-released: '2023-06-12'
+version: 0.5.0
+date-released: '2023-09-13'

Dockerfile

@@ -1,4 +1,4 @@
-FROM pennlinc/xcp_d_build:0.0.6rc15
+FROM pennlinc/xcp_d_build:0.0.7
 
 # Install xcp_d
 COPY . /src/xcp_d

docs/changes.md

@@ -1,5 +1,45 @@
 # What's New
 
+## 0.5.0
+
+The 0.5.0 release prepares for the XCP-D manuscript, so I plan to not introduce any backwards-incompatible changes between this release and 1.0.0 (the official paper release).
+<!-- Release notes generated using configuration in .github/release.yml at main -->
+
+### 🛠 Breaking Changes
+* Add CIFTI subcortical atlas to XCP-D by @tsalo in https://github.com/PennLINC/xcp_d/pull/864
+* Change "ciftiSubcortical" atlas name to "HCP" by @tsalo in https://github.com/PennLINC/xcp_d/pull/932
+### 🎉 Exciting New Features
+* Write out top-level sidecar for PennLINC QC file by @tsalo in https://github.com/PennLINC/xcp_d/pull/894
+* Parcellate ReHo, ALFF, and surface morphometric maps by @tsalo in https://github.com/PennLINC/xcp_d/pull/839
+* Refactor dcan/hcp ingestion and add more surface files by @tsalo in https://github.com/PennLINC/xcp_d/pull/887
+* Add "none" option for denoising by @tsalo in https://github.com/PennLINC/xcp_d/pull/879
+* Add `--exact-time` parameter by @tsalo in https://github.com/PennLINC/xcp_d/pull/885
+* Allow white matter surface suffix to be either "_smoothwm" or "_white" by @tsalo in https://github.com/PennLINC/xcp_d/pull/899
+* Add `--fs-license-file` parameter to command line interface by @tsalo in https://github.com/PennLINC/xcp_d/pull/930
+* Generate executive summary figures without `--dcan-qc` by @tsalo in https://github.com/PennLINC/xcp_d/pull/936
+### 🐛 Bug Fixes
+* Standardize executive summary carpet if params is "none" by @tsalo in https://github.com/PennLINC/xcp_d/pull/916
+* Support CIFTI morphometry files and add PNC test data by @tsalo in https://github.com/PennLINC/xcp_d/pull/922
+* Correct ABCD/HCP surface ingression by @tsalo in https://github.com/PennLINC/xcp_d/pull/927
+### Other Changes
+* Add contributing documentation by @tsalo in https://github.com/PennLINC/xcp_d/pull/893
+* Update changelog and CFF file for 0.4.0 by @tsalo in https://github.com/PennLINC/xcp_d/pull/896
+* Change packaging to use hatch-vcs and pyproject.toml by @tsalo in https://github.com/PennLINC/xcp_d/pull/897
+* Fix description of signal denoising method in docs by @tsalo in https://github.com/PennLINC/xcp_d/pull/898
+* Improve QC sidecar contents by @tsalo in https://github.com/PennLINC/xcp_d/pull/900
+* Rename the parcellated ALFF/ReHo outputs by @tsalo in https://github.com/PennLINC/xcp_d/pull/902
+* Remove workaround for nonbinary Nibabies brain masks by @tsalo in https://github.com/PennLINC/xcp_d/pull/905
+* Update Landing Page Figure by @kahinimehta in https://github.com/PennLINC/xcp_d/pull/908
+* Remove unused functions in filemanip module by @tsalo in https://github.com/PennLINC/xcp_d/pull/911
+* Add tests for xcp_d.utils.utils module by @tsalo in https://github.com/PennLINC/xcp_d/pull/910
+* Add tests for xcp_d.utils.execsummary module by @tsalo in https://github.com/PennLINC/xcp_d/pull/912
+* Expand tests by @tsalo in https://github.com/PennLINC/xcp_d/pull/913
+* Test CLI parameter validation by @tsalo in https://github.com/PennLINC/xcp_d/pull/918
+* Refactor collection functions by @tsalo in https://github.com/PennLINC/xcp_d/pull/917
+
+
+**Full Changelog**: https://github.com/PennLINC/xcp_d/compare/04.0...0.5.0
+
 ## 0.4.0
 
 ### 🛠 Breaking Changes

docs/links.rst

@@ -10,3 +10,5 @@
 .. _`Docker installation`: https://docs.docker.com/install/
 .. _`Docker Hub`: https://hub.docker.com/r/pennlinc/xcp_d/tags
 .. _`Singularity`: https://sylabs.io/guides/3.5/user-guide/introduction.html
+.. _`QSIPrep`: https://qsiprep.readthedocs.io
+.. _`ASLPrep`: https://aslprep.readthedocs.io

docs/outputs.rst

@@ -5,16 +5,16 @@
 Outputs of *XCP-D*
 ##################
 
-The  ``xcp_d`` outputs are written out in BIDS format and consist of three main parts.
+The  *XCP-D* outputs are written out in BIDS format and consist of three main parts.
 
 .. admonition:: A note on BIDS compliance
 
-   ``xcp_d`` attempts to follow the BIDS specification as best as possible.
-   However, many ``xcp_d`` derivatives are not currently covered by the specification.
+   *XCP-D* attempts to follow the BIDS specification as best as possible.
+   However, many *XCP-D* derivatives are not currently covered by the specification.
    In those instances, we attempt to follow recommendations from existing BIDS Extension Proposals
    (BEPs), which are in-progress proposals to add new features to BIDS.
 
-   Three BEPs that are of particular use in ``xcp_d`` are
+   Three BEPs that are of particular use in *XCP-D* are
    `BEP012: Functional preprocessing derivatives <https://github.com/bids-standard/bids-specification/pull/519>`_,
    `BEP017: BIDS connectivity matrix data schema <https://docs.google.com/document/d/1ugBdUF6dhElXdj3u9vw0iWjE6f_Bibsro3ah7sRV0GA/edit?usp=sharing>`_,
    and
@@ -24,8 +24,8 @@ The  ``xcp_d`` outputs are written out in BIDS format and consist of three main
    In cases where a derivative type is not covered by an existing BEP,
    we have simply attempted to follow the general principles of BIDS.
 
-   If you discover a problem with the BIDS compliance of ``xcp_d``'s derivatives, please open an
-   issue in the ``xcp_d`` repository.
+   If you discover a problem with the BIDS compliance of *XCP-D*'s derivatives, please open an
+   issue in the *XCP-D* repository.
 
 
 ***************
@@ -44,6 +44,33 @@ The executive summary is based on the DCAN lab's
       sub-<label>[_ses-<label>]_executive_summary.html
 
 
+*************************
+Parcellations and Atlases
+*************************
+
+*XCP-D* produces parcellated anatomical and functional outputs using a series of atlases.
+The individual outputs are documented in the relevant sections of this document,
+with this section describing the atlases themselves.
+
+The atlases currently used in *XCP-D* can be separated into three groups: subcortical, cortical,
+and combined cortical/subcortical.
+The two subcortical atlases are the Tian atlas :footcite:p:`tian2020topographic` and the
+CIFTI subcortical parcellation.
+The cortical atlases are the Glasser :footcite:p:`Glasser_2016` and the
+Gordon :footcite:p:`Gordon_2014`.
+The combined cortical/subcortical atlases are 10 different resolutions of the
+4S (Schaefer Supplemented with Subcortical Structures) atlas.
+
+The 4S atlas combines the Schaefer 2018 cortical atlas (version v0143) :footcite:p:`Schaefer_2017`
+at 10 different resolutions (100, 200, 300, 400, 500, 600, 700, 800, 900, and 1000 parcels) with
+the CIT168 subcortical atlas :footcite:p:`pauli2018high`,
+the Diedrichson cerebellar atlas :footcite:p:`king2019functional`,
+and the HCP thalamic atlas :footcite:p:`najdenovska2018vivo`.
+The 4S atlas is used in the same manner across three PennLINC BIDS Apps:
+XCP-D, QSIPrep_, and ASLPrep_, to produce synchronized outputs across modalities.
+For more information about the 4S atlas, please see https://github.com/PennLINC/AtlasPack.
+
+
 ******************
 Anatomical Outputs
 ******************
@@ -116,7 +143,7 @@ functional connectivity matrices, and resting-state derivatives.
 
 .. important::
 
-   Prior to version 0.4.0, the denoised data outputted by ``xcp_d`` was interpolated,
+   Prior to version 0.4.0, the denoised data outputted by *XCP-D* was interpolated,
    meaning that high-motion volumes were replaced with interpolated data prior to temporal
    filtering.
    **This was a bug.**

docs/workflows.rst

@@ -392,13 +392,8 @@ Parcellation and functional connectivity estimation
 :func:`~xcp_d.workflows.connectivity.init_functional_connectivity_cifti_wf`
 
 The ``filtered, denoised BOLD`` is fed into a functional connectivity workflow,
-which extracts parcel-wise time series from the BOLD using several atlases:
-
-   a. Schaefer 100, 200, 300, 400, 500, 600, 700, 800, 900, and 1000 parcel resolutions
-   b. Glasser 360
-   c. Gordon 333
-   d. Tian Subcortical Atlas :footcite:p:`tian2020topographic`
-   e. HCP Subcortical Atlas :footcite:p:`glasser2013minimal`
+which extracts parcel-wise time series from the BOLD using several atlases.
+These atlases are documented in :doc:`outputs`.
 
 The resulting parcellated time series for each atlas is then used to generate static functional
 connectivity matrices, as measured with Pearson correlation coefficients.