Fix typos in documentation and add page on BIDS curation

README.rst

@@ -81,7 +81,7 @@ ASLPrep
 
 *ASLPrep* adapts the preprocessing steps depending on the input dataset
 and provide results as good as possible independently of scanner make and scanning parameters
-With the BIDS input, little or no parameter are required allowing ease of operation.
+With the BIDS input, little or no parameters are required allowing ease of operation.
 *ASLPrep* also provides visual reports for each subject,
 detailing the most important processing steps.
 
@@ -117,7 +117,7 @@ which must be accounted for in ASLPrep:
    different volume types in the ASL time series exhibit different contrasts, which can introduce
    artifacts into the motion-corrected data.
    As such, ASLPrep motion corrects each volume type separately,
-   and then concatenated the corrected time series back together.
+   and then concatenates the corrected time series back together.
 4. ASLPrep includes extra steps to do the following:
    1. Calculate CBF.
    2. Calculate CBF QC metrics, paralleling the ASL confound calculation.

docs/bids.rst

@@ -0,0 +1,112 @@
+.. include:: links.rst
+
+###################
+Preparing BIDS Data
+###################
+
+Here we discuss a few different quirks in BIDS that might affect how you prepare your ASL data.
+
+
+***********************
+Mixed-type 4D ASL files
+***********************
+
+Unlike fMRI data, the 4D ASL file can contain multiple types of volumes, including M0, control,
+label, noise, and derived volumes.
+As such, the time axis is not as meaningful as it is for fMRI data.
+
+The aslcontext.tsv file is used to describe the volume types in the ASL file.
+
+The NIfTI file format only allows for a single time-step unit,
+even though ASL files may have different time-steps for different volumes.
+This has necessitated metadata in the ASL NIfTI files' sidecar JSON files to describe the time-steps
+for each volume; namely RepetitionTimePreparation and RepetitionTimeExcitation.
+
+
+***********************
+Repetition Time Nuances
+***********************
+
+.. warning::
+
+   It's important to talk to your physicist to determine the correct values for these fields.
+   The values produced by the DICOM converter are not always correct- probably because the DICOM
+   does not have the right information.
+
+There are three relevant repetition time fields in ASL data:
+
+1. RepetitionTime: This can only be a single value. When the ASL BEP was first developed,
+   it was decided that the RepetitionTime field would not be changed to allow arrays of values,
+   as is needed for ASL data. Instead, they created the RepetitionTimePreparation field, which
+   can be either a single value or an array of values (one value per volume in the ASL file).
+2. RepetitionTimePreparation: This is effectively the same as RepetitionTime, but can be an array.
+
+   - This value (especially for the M0 scan) may be useful for calculating CBF.
+     It's not used in ASLPrep, but other tools may use it.
+
+3. RepetitionTimeExcitation: The "true" time between the beginning of the first excitation pulse
+   and the last one.
+
+
+**********
+M0 Scaling
+**********
+
+In many ASL sequences, the M0 volumes need to be scaled before they can be used to calculate CBF.
+This is one value that many dataset curators will not know offhand.
+Unfortunately, there is no standard way to find this value.
+Some sequences will include the scaling factor in a private DICOM field,
+or it may be available in the protocol's summary file (see below for an example).
+
+BIDS expects the M0 volumes to be scaled as part of the BIDS curation process,
+but ASLPrep has a ``--m0-scale`` parameter that users can use if they haven't already scaled
+the M0 volumes.
+
+.. tip::
+
+   If you are working with a BIDS dataset where it is not clear if the M0 volumes have been scaled,
+   and, if they have not, it's not clear how much they need to be scaled, you can compute CBF based
+   on M0 scale = 1 and then try to figure out the actual value if the values look out of range.
+
+
+*********************************************
+Separate M0 scans and the "IntendedFor" field
+*********************************************
+
+When you have a separate M0 scan, you need to explicitly link it to the ASL series with which it will be used.
+The M0 scan can be linked to multiple ASL series, or each ASL series can have its own M0 scan.
+
+The ``IntendedFor`` field is used to link the M0 scan to the ASL series,
+but it is not used in the same way as other ``IntendedFor`` cases (e.g., to link field maps to images).
+
+The M0 scan is not necessarily used for distortion correction.
+It will be used for CBF calculations, and may be used for other purposes within ASLPrep
+(e.g., as a high-contrast image for coregistration).
+
+
+*********************
+Other metadata fields
+*********************
+
+One of the most common issues with working with ASL data is that many of the required metadata fields
+are not encoded in standard DICOM fields, so they cannot be inferred from the DICOMs alone
+(at least not by a layperson).
+We recommend checking with your scanner physicist, when possible, to determine the correct values
+for these fields.
+
+Ask your physicist for the correct values for the following fields:
+
+- If the sequence is PCASL or PASL. This is typically in the series description or protocol name, but it can be wrong.
+- ``BackgroundSuppression``
+- ``LabelingEfficiency`` (or rely on ASLPrep's heuristic)
+- ``PostLabelingDelay`` (should be in protocol summary file and private DICOM fields, but may be difficult to discover)
+- ``LabelingDuration`` (should be in protocol summary file and private DICOM fields, but may be difficult to discover)
+- ``BackgroundSuppressionNumberPulses``
+- ``VascularCrushing``
+- ``LookLocker``
+- The order of volumes in the ASL file.
+  The aslcontext.tsv is not automatically generated and is not something that can be inferred
+  from the DICOMs (at least not easily).
+
+The list above is not comprehensive.
+There may be other fields or elements that need to be manually added to the dataset before it is usable.

docs/index.rst

@@ -26,4 +26,5 @@ Contents
    spaces
    contributors
    api
+   bids
    What's New <https://github.com/PennLINC/aslprep/releases>

docs/outputs.rst

@@ -46,7 +46,9 @@ 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.
+records metadata recommended by the BIDS standard. 
+The atlases directory contains the relevant json, tsv, and nifti files
+for each atlas, and the .bidsignore file contains a record of the files that bids-validator ignored.
 
 
 ****************
@@ -419,7 +421,7 @@ the HCP thalamic atlas :footcite:p:`najdenovska2018vivo`,
 and the amygdala and hippocampus parcels from the HCP CIFTI subcortical parcellation
 :footcite:p:`glasser2013minimal`.
 The 4S atlas is used in the same manner across three PennLINC BIDS Apps:
-ASLPrep, QSIPrep_, and XCP-D, to produce synchronized outputs across modalities.
+ASLPrep, QSIPrep, and XCP-D, to produce synchronized outputs across modalities.
 For more information about the 4S atlas, please see https://github.com/PennLINC/AtlasPack.
 
 MNI152NLin6Asym-space atlases are warped to the ASL reference image space before parcellation.

docs/usage.rst

@@ -22,12 +22,16 @@ We highly recommend that you validate your dataset with the free, online
     04-modality-specific-files/01-magnetic-resonance-imaging-data.html#scaling>`_.
 
     What this means is that the M0 scans in your dataset should preferably be scaled before running
-    ASLPrep.
+    ASLPrep. This depends on whether or not your scans are already scaled is not readily available from DICOMs;
+    you should ask your MRI tech if it is scaled.
+    Refer to :doc:`bids` for this and other quirks in BIDS for ASL data.
 
     Please see
     `the BIDS starter kit <https://bids-standard.github.io/bids-starter-kit/tutorials/asl.html>`_
     for information about converting ASL data to BIDS.
 
+    Please see `the BIDS specification for ASL <https://bids-specification.readthedocs.io/en/stable/modality-specific-files/magnetic-resonance-imaging-data.html#arterial-spin-labeling-perfusion-data>`_ to view the required metadata for ASL data.
+
     If your data are not already scaled, you should use the ``--m0_scale`` parameter when running
     ASLPrep.
 
@@ -141,7 +145,7 @@ Handling environment variables
 
 By default, Singularity interacts with all environment variables from the host.
 The host libraries could accidentally conflict with singularity variables.
-To avoid such a situation, it is recommended that you sue the ``--cleanenv or -e``
+To avoid such a situation, it is recommended that you use the ``--cleanenv or -e``
 flag.
 For instance: ::
 

docs/workflows.rst

@@ -245,7 +245,7 @@ Interpolation uses a Lanczos kernel.
 .. figure:: _static/sub-20589_ses-11245_task-rest_desc-carpetplot_asl.svg
 
    The preprocessed ASL with label and control.
-   The signal plots above the carpet plot are framewise displacement (FD) and DVRAS.
+   The signal plots above the carpet plot are framewise displacement (FD) and DVARS.
 
 
 .. _cbf_preproc: