From 09efa263f38b6a50e249c12af75e8bfcf3348fdc Mon Sep 17 00:00:00 2001
From: Taylor Salo <salot@pennmedicine.upenn.edu>
Date: Sat, 9 Dec 2023 12:06:42 -0500
Subject: [PATCH] Prepare for 0.6.0 release (#362)

* Prepare for 0.6.0 release.

* Update CITATION.cff.
---
 .github/dependabot.yml |   7 +-
 CHANGES.md             |  52 ++++++++
 CITATION.cff           |  12 +-
 README.rst             |   6 +-
 docs/license.rst       |   2 +-
 docs/links.rst         |   3 +-
 docs/outputs.rst       | 293 ++++++++++++++++++++++++++++++++++++-----
 docs/spaces.rst        |  45 +------
 docs/usage.rst         |   7 +-
 long_description.rst   |  12 +-
 10 files changed, 350 insertions(+), 89 deletions(-)

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index f198400f0..2b5fd1113 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -7,7 +7,12 @@ version: 2
 updates:
   - package-ecosystem: "github-actions" # See documentation for possible values
     directory: "/" # Location of package manifests
-    labels: ["maintenance"]
+    labels: ["maintenance", "ignore-for-release"]
     assignees: ["tsalo"]
     schedule:
       interval: "weekly"
+  - package-ecosystem: pip
+    directory: "/"
+    labels: ["maintenance", "ignore-for-release"]
+    schedule:
+      interval: weekly
diff --git a/CHANGES.md b/CHANGES.md
index 015f4d9fe..f98798fdf 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,3 +1,55 @@
+## 0.6.0
+
+This release makes substantial changes to *ASLPrep*.
+The two main changes are (1) the Schaefer atlases are replaced with the PennLINC team's new 4S atlases,
+which combine the Schaefer cortical atlases and several subcortical atlases,
+and (2) a major rearchitect of the package based on *fMRIPrep* version 23.2.0a2.
+The latter allows *ASLPrep* to run FreeSurfer reconstruction,
+write out CIFTI and GIFTI format derivatives,
+and correctly apply susceptibility distortion correction with *SDCFlows*
+(although SDC support is dependent on the _next_ *SDCFlows* release, so in practice it won't work just yet).
+
+I'd like to credit Chris Markiewicz (@effigies) for doing the majority of the work in the *fMRIPrep* refactor,
+which I was able to copy and adapt for *ASLPrep*.
+
+Here's a list of parameter changes with this release:
+
+-   Users must point to the actual output directory.
+    `aslprep` will no longer be appended automatically.
+-   The parameter `--anat-derivatives` is replaced with `--derivatives`,
+    which takes one or more paths to *sMRIPrep* or *ASLPrep* derivatives.
+-   The parameter `--dummy-vols` is now `--dummy-scans` to match *fMRIPrep*.
+-   The following parameters are newly added:
+    `--bids-database-dir`, `--level`, `--medial-surface-nan`, `--project-goodvoxels`,
+    `--cifti-output`, `--no-msm`, `--no-submm-recon`, `--fs-subjects-dir`,
+    `--fs-no-reconall`, and `--config-file`.
+
+Output changes:
+
+-   The native-space `aslref` image is now split into `desc-hmc` and `desc-coreg` versions.
+-   `desc-pvGM_cbf` is renamed to `desc-basilGM_cbf`.
+-   `desc-pvWM_cbf` is renamed to `desc-basilWM_cbf`.
+-   `desc-confounds_regressors.tsv` is renamed to `desc-confounds_timeseries.tsv`.
+-   The transform `from-T1w_to-scanner_mode-image_xfm.txt` is no longer generated.
+    The inverse is invertible, so the information is still available.
+-   The transform `from-scanner_to-T1w_mode-image_xfm.txt` is split into
+    `from-orig_to-aslref_mode-image_xfm.txt` and `from-aslref_to-T1w_mode-image_xfm.txt` files.
+
+### 🛠 Breaking Changes
+* Add AtlasPack atlases by @tsalo in https://github.com/PennLINC/aslprep/pull/330
+* Replace AtlasPack 0.0.5 atlases with AtlasPack 0.1.0 atlases by @tsalo in https://github.com/PennLINC/aslprep/pull/334
+* Remove sdcflows and model ASLPrep on fMRIPrep/next by @tsalo in https://github.com/PennLINC/aslprep/pull/338
+
+### 🎉 Exciting New Features
+* Write out GIFTI and CIFTI CBF maps by @tsalo in https://github.com/PennLINC/aslprep/pull/361
+
+### 🐛 Bug Fixes
+* Pin scipy version to 1.10.1 by @tsalo in https://github.com/PennLINC/aslprep/pull/333
+* Raise error if no M0 volume(s)/estimate available and background suppression is enabled by @tsalo in https://github.com/PennLINC/aslprep/pull/337
+* Limit BASIL `--slicedt` argument to ascending slice orders by @tsalo in https://github.com/PennLINC/aslprep/pull/348
+
+**Full Changelog**: https://github.com/PennLINC/aslprep/compare/0.5.1...0.6.0
+
 
 ## 0.5.1
 
diff --git a/CITATION.cff b/CITATION.cff
index a18826e07..67210e65c 100644
--- a/CITATION.cff
+++ b/CITATION.cff
@@ -59,12 +59,20 @@ authors:
     family-names: Flounders
   - given-names: Alexandre R.
     family-names: Franco
+  - given-names: Mathias
+    family-names: Goncalves
+    affiliation: Stanford University
+    orcid: 'https://orcid.org/0000-0002-7252-7771'
   - given-names: Raquel E.
     family-names: Gur
   - given-names: Ruben C.
     family-names: Gur
   - given-names: Basma
     family-names: Jaber
+  - given-names: Christopher J.
+    family-names: Markiewicz
+    affiliation: Stanford University
+    orcid: 'https://orcid.org/0000-0002-6533-164X'
   - given-names: Corey
     family-names: McMillian
   - name: "The ALLFTD Consortium"
@@ -116,5 +124,5 @@ keywords:
   - BIDS-App
   - Neuroimaging
 license: BSD-3-Clause
-version: 0.3.0
-date-released: '2023-04-07'
+version: 0.6.0
+date-released: '2023-12-09'
diff --git a/README.rst b/README.rst
index a396ecb08..7b00d212c 100644
--- a/README.rst
+++ b/README.rst
@@ -100,7 +100,11 @@ ASLPrep is largely based on fMRIPrep, as ASL processing is very similar to fMRI
 fMRIPrep is developed by a larger group and receives more regular feedback on its workflow,
 so we (the ASLPrep developers) try to update ASLPrep in line with fMRIPrep.
 
-ASLPrep and fMRIPrep are both part of the NiPreps community.
+ASLPrep and fMRIPrep are both part of the NiPreps community, but ASLPrep is in a unique situation
+because it is owned and maintained by Ted Satterthwaite and his team.
+As such, while we do our best to keep ASLPrep in sync with fMRIPrep, differences may arise
+due to choices by leadership or, more commonly, necessarily differential processing for different
+modalities.
 
 There are several crucial differences between ASL and fMRI processing,
 which must be accounted for in ASLPrep:
diff --git a/docs/license.rst b/docs/license.rst
index 81ea776a0..5d9277a90 100644
--- a/docs/license.rst
+++ b/docs/license.rst
@@ -8,5 +8,5 @@ in the *ASLPrep* distribution.
 
 All trademarks referenced herein are property of their respective holders.
 
-Copyright (c) 2019-2020, Azeez Adebimpe
+Copyright (c) 2019-2023, PennLINC Developers
 All rights reserved.
diff --git a/docs/links.rst b/docs/links.rst
index 91e31d184..c85764037 100644
--- a/docs/links.rst
+++ b/docs/links.rst
@@ -1,8 +1,7 @@
 .. _AFNI: https://afni.nimh.nih.gov/
 .. _ANTs: https://stnava.github.io/ANTs/
 .. _BIDS: http://bids.neuroimaging.io
-.. _`BIDS Derivatives`: https://docs.google.com/document/d/17ebopupQxuRwp7U7TFvS6BH03ALJOgGHufxK8ToAvyI
-.. _`BIDS Derivatives RC1`: https://docs.google.com/document/d/17ebopupQxuRwp7U7TFvS6BH03ALJOgGHufxK8ToAvyI
+.. _`BIDS Derivatives`: https://bids-specification.readthedocs.io/en/stable/derivatives/introduction.html
 .. _`Connectome Workbench`: https://www.humanconnectome.org/software/connectome-workbench.html
 .. _Docker: https://www.docker.com/
 .. _`Docker Engine`: https://www.docker.com/products/container-runtime
diff --git a/docs/outputs.rst b/docs/outputs.rst
index 8961670bd..e5a0e4a97 100644
--- a/docs/outputs.rst
+++ b/docs/outputs.rst
@@ -7,27 +7,74 @@ Outputs of *ASLPrep*
 *ASLPrep* generates three broad classes of outputs:
 
 1. **Visual QA (quality assessment) reports**:
-   one :abbr:`HTML (hypertext markup language)` per subject, per session (if applicable),
+   one :abbr:`HTML (hypertext markup language)` per subject,
    that allows the user to conduct a thorough visual assessment of the raw and
    processed data.
    This also includes quality control measures.
 
 2. **Derivatives (preprocessed data and computed CBF):** the input ASL data ready for
-   analysis, (e.g., after the various preparation procedures have been applied),
-   the brain mask, and ASL images after masking has been applied. Other outputs
-   include computed CBF maps and post-processed data such as denoised and partial
+   analysis, (i.e., after the various preparation procedures have been applied),
+   the brain mask, and ASL images after masking has been applied.
+   Other outputs include computed CBF maps and post-processed data such as denoised and partial
    volume-corrected CBF.
 
-3. **Confounds and quality control metrics**: a confounds matrix that inlcudes framewise
+3. **Confounds and quality control metrics**: a confounds matrix that includes framewise
    displacement, motion parameters, coregistration and registration quality indices,
    and CBF quality control metrics.
 
 
+******
+Layout
+******
+
+Assuming ASLPrep is invoked with::
+
+   aslprep <input_dir>/ <output_dir>/ participant [OPTIONS]
+
+The outputs will be a `BIDS Derivatives`_ dataset of the form::
+
+   <output_dir>/
+      logs/
+      sub-<label>/
+      sub-<label>.html
+      dataset_description.json
+      .bidsignore
+
+For each participant in the dataset,
+a directory of derivatives (``sub-<label>/``)
+and a visual report (``sub-<label>.html``) are generated.
+The log directory contains `citation boilerplate`_ text.
+``dataset_description.json`` is a metadata file in which ASLPrep
+records metadata recommended by the BIDS standard.
+
+
+****************
+Processing level
+****************
+
+As of version 0.6.0, ASLPrep supports three levels of derivatives:
+
+* ``--level minimal``: This processing mode aims to produce the smallest
+  working directory and output dataset possible, while enabling all further
+  processing results to be deterministically generated.
+  Most components of the `visual reports`_ can be generated at this level,
+  so the quality of preprocessing can be assessed.
+  Because no resampling is done, confounds and carpetplots will be missing from the reports.
+  ASL-reference-space CBF derivatives will automatically be generated if this level is selected.
+* ``--level resampling``: This processing mode aims to produce additional
+  derivatives that enable third-party resampling, resampling BOLD series
+  in the working directory as needed, but these are not saved to the output directory.
+  ASL-reference-space CBF derivatives will automatically be generated if this level is selected.
+* ``--level full``: This processing mode aims to produce all derivatives
+  that have previously been a part of the ASLPrep output dataset.
+  This is the default processing level.
+
+
 **************
 Visual Reports
 **************
 
-*ASLPrep* outputs summary reports are written to ``<output dir>/aslprep/sub-<label>.html``.
+*ASLPrep* outputs summary reports are written to ``<output dir>/sub-<label>.html``.
 These reports provide a quick way to make visual inspection of the results easy.
 `View a sample report. <_static/sub-01.html>`_
 
@@ -37,20 +84,19 @@ Derivatives of *ASLPrep*
 ************************
 
 Preprocessed, or derivative, data are written to
-``<output dir>/aslprep/sub-<label>/[ses-<label>/]``.
-The `BIDS Derivatives RC1`_ specification describes the naming and metadata conventions
-that we follow.
+``<output dir>/sub-<label>/[ses-<label>/]``.
+The `BIDS Derivatives`_ specification describes the naming and metadata conventions that we follow.
 
 
 Anatomical Derivatives
 ======================
 
-Anatomical derivatives are placed in each subject's ``anat`` subfolder.
-These derivatives are the same as smriprep output::
+Anatomical derivatives are placed in each subject's ``anat`` subfolder::
 
-   sub-<label>/[ses-<label>/]
+   sub-<label>/
       anat/
          <source_entities>[_space-<label>]_desc-preproc_T1w.nii.gz
+         <source_entities>[_space-<label>]_desc-preproc_T2w.nii.gz
          <source_entities>[_space-<label>]_desc-brain_mask.nii.gz
          <source_entities>[_space-<label>]_dseg.nii.gz
          <source_entities>[_space-<label>]_label-CSF_probseg.nii.gz
@@ -58,62 +104,243 @@ These derivatives are the same as smriprep output::
          <source_entities>[_space-<label>]_label-WM_probseg.nii.gz
 
 Spatially-standardized derivatives are denoted with a space label,
-such as ``MNI152NLin2009cAsym``, while derivatives in
-the original ``T1w`` space omit the ``space-`` keyword.
+such as ``MNI152NLin2009cAsym``,
+while derivatives in the original ``T1w`` space omit the ``space-`` keyword.
+
+T2w images are aligned to the anatomical (``T1w``) space, if found.
+
+.. note::
+
+   T2w derivatives are only generated if FreeSurfer processing is enabled.
 
 Additionally, the following transforms are saved::
 
    sub-<label>/[ses-<label>/]
       anat/
+         sub-<label>_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5
+         sub-<label>_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5
          sub-<label>_from-<space>_to-T1w_mode-image_xfm.h5
          sub-<label>_from-T1w_to-<space>_mode-image_xfm.h5
 
-
-ASL and CBF Derivatives
-=======================
-
-ASL derivatives are stored in the ``perf/`` subfolder.
-All derivatives contain ``task-<task_label>`` (mandatory) and ``run-<run_index>`` (optional), and
-these will be indicated with ``[specifiers]``::
+If FreeSurfer reconstructions are used, the following surface files are generated::
+
+  sub-<label>/
+    anat/
+      sub-<label>_hemi-[LR]_white.surf.gii
+      sub-<label>_hemi-[LR]_midthickness.surf.gii
+      sub-<label>_hemi-[LR]_pial.surf.gii
+      sub-<label>_hemi-[LR]_desc-reg_sphere.surf.gii
+      sub-<label>_hemi-[LR]_space-fsLR_desc-reg_sphere.surf.gii
+      sub-<label>_hemi-[LR]_space-fsLR_desc-msmsulc_sphere.surf.gii
+
+The registration spheres target ``fsaverage`` and ``fsLR`` spaces. If MSM
+is enabled (i.e., the ``--no-msm`` flag is not passed), then the ``msmsulc``
+spheres are generated and used for creating ``space-fsLR`` derivatives.
+
+And the affine translation (and inverse) between the original T1w sampling and FreeSurfer's
+conformed space for surface reconstruction (``fsnative``) is stored in::
+
+  sub-<label>/
+    anat/
+      sub-<label>_from-fsnative_to-T1w_mode-image_xfm.txt
+      sub-<label>_from-T1w_to-fsnative_mode-image_xfm.txt
+
+Finally, cortical thickness, curvature, and sulcal depth maps are converted to GIFTI
+and CIFTI-2::
+
+  sub-<label>/
+    anat/
+      sub-<label>_hemi-[LR]_thickness.shape.gii
+      sub-<label>_hemi-[LR]_curv.shape.gii
+      sub-<label>_hemi-[LR]_sulc.shape.gii
+      sub-<label>_space-fsLR_den-32k_thickness.dscalar.nii
+      sub-<label>_space-fsLR_den-32k_curv.dscalar.nii
+      sub-<label>_space-fsLR_den-32k_sulc.dscalar.nii
+
+.. warning::
+
+   GIFTI metric files follow the FreeSurfer conventions and are not modified
+   by *ASLPrep* in any way.
+
+   The Human Connectome Project (HCP) inverts the sign of the curvature and
+   sulcal depth maps. For consistency with HCP, *ASLPrep* follows these
+   conventions and masks the medial wall of CIFTI-2 dscalar files.
+
+
+.. _fsderivs:
+
+FreeSurfer derivatives
+~~~~~~~~~~~~~~~~~~~~~~
+
+If FreeSurfer is run, then a FreeSurfer subjects directory is created in
+``<output dir>/sourcedata/freesurfer`` or the directory indicated with the
+``--fs-subjects-dir`` flag.
+Additionally, FreeSurfer segmentations are resampled into the BOLD space,
+and lookup tables are provided. ::
+
+    <output_dir>/
+      sourcedata/
+        freesurfer/
+          fsaverage{,5,6}/
+              mri/
+              surf/
+              ...
+          sub-<label>/
+              mri/
+              surf/
+              ...
+          ...
+      desc-aparc_dseg.tsv
+      desc-aparcaseg_dseg.tsv
+
+Copies of the ``fsaverage`` subjects distributed with the running version of
+FreeSurfer are copied into this subjects directory, if any functional data are
+sampled to those subject spaces.
+
+Note that the use of ``sourcedata/`` recognizes FreeSurfer derivatives as an input to
+the ASLPrep workflow.
+This is strictly true when pre-computed FreeSurfer derivatives are provided either in
+the ``sourcedata/`` directory or passed via the ``--fs-subjects-dir`` flag;
+if ASLPrep runs FreeSurfer, then there is a mutual dependency.
+
+
+Perfusion Derivatives
+=====================
+
+ASL and CBF derivatives are stored in the ``perf/`` subfolder::
 
    sub-<label>/[ses-<label>/]
       perf/
-         <source_entities>_desc-hmc_aslref.nii.gz  # asl reference image for HMC
-         <source_entities>_desc-coreg_aslref.nii.gz  # asl reference image for coregistration
-         <source_entities>[_space-<label>]_aslref.nii.gz  # asl reference image for normalization
          <source_entities>[_space-<label>]_desc-brain_mask.nii.gz  # asl brain mask
          <source_entities>[_space-<label>]_desc-preproc_asl.nii.gz  # preprocessed asl timeseries
 
-Additionally, the following transforms are saved::
+.. note::
+
+   The mask file is part of the *minimal* processing level.
+   The ASL series is only generated at the *full* processing level.
+
+**Motion correction outputs**.
 
+Head-motion correction (HMC) produces a reference image to which all volumes are aligned,
+and a corresponding transform that maps the original ASL series to the reference image::
+
+   sub-<label>/[ses-<label>/]
+      perf/
+         <source_entities>_desc-hmc_aslref.nii.gz  # asl reference image for HMC
          <source_entities>_from-orig_to-aslref_mode-image_xfm.txt  # HMC transforms from raw ASL to aslref
-         <source_entities>_from-aslref_to-T1w_mode-image_xfm.txt
+
+.. note::
+
+   Motion correction outputs are part of the *minimal* processing level.
+
+**Coregistration outputs**.
+
+Registration of the ASL series to the T1w image generates a further reference image and affine
+transform::
+
+   sub-<label>/[ses-<label>/]
+      perf/
+         <source_entities>_desc-coreg_aslref.nii.gz
+         <source_entities>_from-aslref_to-T1w_mode-image_desc-coreg_xfm.txt
+
+.. note::
+
+   Coregistration outputs are part of the *minimal* processing level.
+
+**Fieldmap registration**.
+
+If a fieldmap is used for the correction of an ASL series,
+then a registration is calculated between the ASL series and the fieldmap.
+If, for example, the fieldmap is identified with ``"B0Identifier": "TOPUP"``,
+the generated transform will be named::
+
+   sub-<label>/[ses-<label>/]
+      perf/
+         <source_entities>_from-aslref_to-TOPUP_mode-image_xfm.nii.gz
+
+If the association is discovered through the ``IntendedFor`` field of the
+fieldmap metadata, then the transform will be given an auto-generated name::
+
+   sub-<label>/[ses-<label>/]
+      perf/
+         <source_entities>_from-aslref_to-auto000XX_mode-image_xfm.txt
+
+.. note::
+
+   Fieldmap registration outputs are part of the *minimal* processing level.
+
+**Regularly gridded outputs (images)**.
+Volumetric output spaces labels (``space-<label>`` above, and in the following) include
+``T1w`` and ``MNI152NLin2009cAsym`` (default).
+
+**Surfaces, segmentations and parcellations from FreeSurfer**.
+If FreeSurfer reconstructions are used,
+the ``(aparc+)aseg`` segmentations are aligned to the subject's T1w space and resampled to the ASL grid,
+and the ASL series are resampled to the mid-thickness surface mesh::
+
+   sub-<label>/[ses-<label>/]
+      perf/
+         <source_entities>_space-T1w_desc-aparcaseg_dseg.nii.gz
+         <source_entities>_space-T1w_desc-aseg_dseg.nii.gz
+         <source_entities>_hemi-[LR]_space-<label>_asl.func.gii
+
+Surface output spaces include ``fsnative`` (full density subject-specific mesh),
+``fsaverage`` and the down-sampled meshes ``fsaverage6`` (41k vertices) and
+``fsaverage5`` (10k vertices, default).
+
+**Grayordinates files**.
+`CIFTI <https://www.nitrc.org/forum/attachment.php?attachid=333&group_id=454&forum_id=1955>`_ is
+a container format that holds both volumetric (regularly sampled in a grid) and surface
+(sampled on a triangular mesh) samples.
+Sub-cortical time series are sampled on a regular grid derived from one MNI template, while
+cortical time series are sampled on surfaces projected from the [Glasser2016]_ template.
+If CIFTI outputs are requested (with the ``--cifti-outputs`` argument), the ASL series are also
+saved as ``dtseries.nii`` CIFTI2 files::
+
+   sub-<label>/[ses-<label>/]
+      perf/
+         <source_entities>_asl.dtseries.nii
+
+CIFTI output resolution can be specified as an optional parameter after ``--cifti-output``.
+By default, '91k' outputs are produced and match up to the standard `HCP Pipelines`_ CIFTI
+output (91282 grayordinates @ 2mm).
+However, '170k' outputs are also possible, and produce higher resolution CIFTI output
+(170494 grayordinates @ 1.6mm).
+
+CBF Derivatives
+---------------
+
+Cerebral blood flow (CBF) derivatives are generated in each of the volumetric spaces,
+surface spaces, and CIFTI2 resolutions requested for the preprocessed ASL data.
+For the sake of brevity, we only show the NIfTI outputs below,
+but these descriptions and suffixes apply to GIFTI and CIFTI outputs as well.
 
 CBF Outputs::
 
+   sub-<label>/[ses-<label>/]
+      perf/
          <source_entities>[_space-<label>]_cbf.nii.gz  # mean CBF
          <source_entities>[_space-<label>]_desc-timeseries_cbf.nii.gz  # computed CBF timeseries
          <source_entities>[_space-<label>]_att.nii.gz  # arterial transit time (multi-PLD data only)
 
-SCORE and SCRUB Outputs::
+If ``--scorescrub`` is used::
 
+   sub-<label>/[ses-<label>/]
+      perf/
          <source_entities>[_space-<label>]_desc-scoreTimeseries_cbf.nii.gz  # CBF timeseries denoised with SCORE
          <source_entities>[_space-<label>]_desc-score_cbf.nii.gz  # mean CBF denoised with SCORE
          <source_entities>[_space-<label>]_desc-scrub_cbf.nii.gz  # mean CBF denoised with SCRUB
 
-BASIL outputs::
+If ``--basil`` is used::
 
+   sub-<label>/[ses-<label>/]
+      perf/
          <source_entities>[_space-<label>]_desc-basil_cbf.nii.gz  # mean CBF computed with BASIL
          <source_entities>[_space-<label>]_desc-basilGM_cbf.nii.gz  # GM partial volume corrected CBF with BASIL
          <source_entities>[_space-<label>]_desc-basilWM_cbf.nii.gz  # WM partial volume corrected CBF with BASIL
          <source_entities>[_space-<label>]_att.nii.gz  # bolus arrival time/arterial transit time (in seconds)
 
 
-**Regularly gridded outputs (images):**
-Volumetric output space labels (``<label>`` above, and in the following) include
-``T1w`` and ``MNI152NLin2009cAsym`` (default).
-
-
 *************
 ASL Confounds
 *************
diff --git a/docs/spaces.rst b/docs/spaces.rst
index 890c5f749..84d302004 100644
--- a/docs/spaces.rst
+++ b/docs/spaces.rst
@@ -4,47 +4,16 @@
 Standard and nonstandard spaces
 ###############################
 
-The command line interface of *ASLPPrep* allows resampling of the pre-processed
+The command line interface of *ASLPrep* allows resampling of the pre-processed
 and computed CBF maps onto other output spaces.
 That is achieved using the ``--output-spaces`` argument, where standard and
 nonstandard spaces can be inserted.
 
-.. important::
-
-  *ASLPrep* will reduce the number of output spaces to just spaces listed in ``--output-spaces``,
-  even if other options require resampling the preprocessed data into intermediary spaces.
-
-
-***************
-Standard spaces
-***************
-
-By default, *ASLPrep* uses ``MNI152NLin2009cAsym`` as spatial-standardization reference and
-output space. Valid template identifiers can be used from the
-`TemplateFlow repository <https://github.com/templateflow/templateflow>`__.
-
-However, many users will be interested in utilizing a coarse gridding (typically 2 mm isotropic)
-of the target template. This can be achieved by applying modifiers to the template identifier,
-separated by a ``:`` character.
+This argument is specified in the same manner as *fMRIPrep*.
+For more information about this parameter,
+please see `fMRIPrep's documentation <https://fmriprep.org/en/stable/spaces.html>`_.
 
-For instance, ``--output-spaces MNI152NLin6Asym:res-2`` will generate
-ASL and CBF on standard space (``MNI152NLin6Asym``) with the template's 2 mm
-isotropic resolution.
-
-
-******************
-Nonstandard spaces
-******************
-
-Additionally, ``--output-spaces`` accepts identifiers of spatial references
-that do not generate *standardized* coordinate spaces:
-
-  * ``T1w`` or ``anat``: can be used to resample data into the individual's anatomical
-    reference (e.g., the T1w image).
-
-  * ``func``, ``run``, ``asl``, or ``sbref`` can be used to
-    generate ASL/CBF data in their original grid, after head-motion
-    and susceptibility-distortion corrections as well as CBF computation.
-    These keywords are experimental.
+.. important::
 
-Modifiers are not allowed when providing nonstandard spaces.
+  Just note that, instead of ``func``, ``bold``, and ``boldref``,
+  *ASLPrep* uses ``asl`` and ``aslref`` for its non-standard spaces.
diff --git a/docs/usage.rst b/docs/usage.rst
index 50d0788ab..3a8e573dd 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -54,8 +54,7 @@ Command-Line Arguments
 Running *ASLPrep* via Docker containers
 ***************************************
 
-For every new version of *ASLPrep* that is released, a corresponding Docker
-image is generated.
+For every new version of *ASLPrep* that is released, a corresponding Docker image is generated.
 
 In order to run *ASLPrep* Docker images, the Docker Engine must be installed.
 
@@ -216,8 +215,8 @@ The documentation of this project is found here: https://aslprep.readthedocs.io.
 All bugs, concerns and enhancement requests for this software can be submitted here:
 https://github.com/PennLINC/aslprep/issues.
 
-If you have a question about using ``aslprep``,
+If you have a question about using *ASLPrep*,
 please create a new topic on `NeuroStars <https://neurostars.org>`_ with
 `the "Software Support" category and the "aslprep" tag
 <https://neurostars.org/tags/c/software-support/234/aslprep>`_.
-The ``aslprep`` developers follow NeuroStars, and will be able to answer your question there.
+The *ASLPrep* developers follow NeuroStars, and will be able to answer your question there.
diff --git a/long_description.rst b/long_description.rst
index 841ed21c4..347f37140 100644
--- a/long_description.rst
+++ b/long_description.rst
@@ -1,4 +1,4 @@
-Preprocessing of arterial spin labeling (ASL)  involves numerous steps to clean and standardize
+Preprocessing of arterial spin labeling (ASL) involves numerous steps to clean and standardize
 the data before statistical analysis.
 Generally, researchers create ad hoc preprocessing workflows for each dataset,
 building upon a large inventory of available tools.
@@ -26,14 +26,14 @@ This pipeline was designed to provide the best software implementation for each
 preprocessing, and will be updated as newer and better neuroimaging software becomes
 available.
 
-ASLPrep performs basic preprocessing steps (coregistration, normalization, unwarping,segmentation, 
-skullstripping  and computation of  cerebral blood flow (CBF)) providing outputs that can be
+ASLPrep performs basic preprocessing steps (coregistration, normalization, unwarping,segmentation,
+skullstripping and computation of cerebral blood flow [CBF]) providing outputs that can be
 easily submitted to a variety of group level analyses, including task-based or resting-state
 CBF, graph theory measures, surface or volume-based statistics, etc.
 ASLPrep allows you to easily do the following:
 
   * Take ASL data from *unprocessed* (only reconstructed) to ready for analysis.
-  * Compute Cerebral Blood Flow(CBF), denoising and partial volume correction
+  * Compute Cerebral Blood Flow (CBF), denoising, and partial volume correction
   * Implement tools from different software packages.
   * Achieve optimal data processing quality by using the best tools available.
   * Generate preprocessing-assessment reports, with which the user can easily identify problems.
@@ -42,6 +42,4 @@ ASLPrep allows you to easily do the following:
   * Automate and parallelize processing steps, which provides a significant speed-up from
     typical linear, manual processing.
 
-[Documentation  `aslprep.org <https://aslprep.readthedocs.io>`_ ]
-
-
+[Documentation `aslprep.org <https://aslprep.readthedocs.io>`_]