WIP: Update PETPrep documentation

README.rst

@@ -138,13 +138,3 @@ This was supported by the BRAIN Initiative
 grant (OpenNeuroPET, grant ID 1R24MH120004-01A1); the Novo Nordisk Foundation (OpenNeuroPET, grant ID NN20OC0063277); the Laura and John Arnold Foundation,
 the NIH (grant NBIB R01EB020740, PI: Ghosh);
 and NIMH (R24MH114705, R24MH117179, R01MH121867, PI: Poldrack)
-
-.. _FSL: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki
-.. _ANTs: http://stnava.github.io/ANTs/
-.. _FreeSurfer: https://surfer.nmr.mgh.harvard.edu/
-.. _AFNI: https://afni.nimh.nih.gov/
-.. _PETSurfer: https://surfer.nmr.mgh.harvard.edu/fswiki/PetSurfer
-.. _PETPVC: https://github.com/UCL/PETPVC
-.. _kinfitr: https://github.com/mathesong/kinfitr
-.. _PMOD: https://www.pmod.com/
-.. _BIDS: https://bids.neuroimaging.io/

docs/installation.rst

@@ -89,9 +89,10 @@ the ``petprep`` package:
 - ANTs_ (version 2.5.1)
 - AFNI_ (version 24.0.05)
 - `C3D <https://sourceforge.net/projects/c3d/>`_ (version 1.4.0)
-- FreeSurfer_ (version 7.3.2)
+- FreeSurfer_ (version 7.4.1)
 - `bids-validator <https://github.com/bids-standard/bids-validator>`_ (version 1.14.0)
 - `connectome-workbench <https://www.humanconnectome.org/software/connectome-workbench>`_ (version 1.5.0)
+- PETPVC_ (version 1.2.10)
 
 Not running on a local machine? - Data transfer
 ===============================================

docs/links.rst

@@ -3,6 +3,7 @@
 .. _`BIDS Derivatives`: https://bids-specification.readthedocs.io/en/stable/05-derivatives/01-introduction.html
 .. _`BEP 011`: https://bids-specification.readthedocs.io/en/bep011/05-derivatives/04-structural-derivatives.html
 .. _`BEP 012`: https://bids-specification.readthedocs.io/en/bep012/05-derivatives/05-functional-derivatives.html
+.. _`BEP 023`: https://docs.google.com/document/d/1yzsd1J9GT-aA0DWhdlgNr5LCu6_gvbjLyfvYq2FuxlY/edit?tab=t.0#heading=h.mqkmyp254xh6
 .. _Installation: installation.html
 .. _workflows: workflows.html
 .. _FSL: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/
@@ -24,3 +25,8 @@
 .. _tedana: https://github.com/me-ica/tedana
 .. _`T2* workflow`: https://tedana.readthedocs.io/en/latest/generated/tedana.workflows.t2smap_workflow.html#tedana.workflows.t2smap_workflow  # noqa
 .. _`citation boilerplate`: https://www.nipreps.org/intro/transparency/#citation-boilerplates
+.. _PETSurfer: https://surfer.nmr.mgh.harvard.edu/fswiki/PetSurfer
+.. _PETPVC: https://github.com/UCL/PETPVC
+.. _kinfitr: https://github.com/mathesong/kinfitr
+.. _PMOD: https://www.pmod.com/
+.. _BIDS: https://bids.neuroimaging.io/

docs/outputs.rst

@@ -7,7 +7,7 @@ Outputs of *PETPrep*
 ---------------------
 *PETPrep* outputs conform to the :abbr:`BIDS (brain imaging data structure)`
 Derivatives specification (see `BIDS Derivatives`_, along with the
-upcoming `BEP 011`_ and `BEP 012`_).
+upcoming `BEP 011`_ and `BEP 023`_).
 *PETPrep* generates three broad classes of outcomes:
 
 1. **Visual QA (quality assessment) reports**:
@@ -20,9 +20,9 @@ upcoming `BEP 011`_ and `BEP 012`_).
    have been applied.
    For example, :abbr:`INU (intensity non-uniformity)`-corrected versions
    of the T1-weighted image (per subject), the brain mask,
-   or :abbr:`BOLD (blood-oxygen level dependent)`
-   images after head-motion correction, slice-timing correction and aligned into
-   the same-subject's T1w space or in some standard space.
+   or dynamic PET series after motion correction (and optional partial volume
+   correction) aligned into the same-subject's T1w space or in some
+   standard space.
 
 3. **Confounds**: this is a special family of derivatives that can be utilized
    to inform subsequent denoising steps.
@@ -57,14 +57,14 @@ The log directory contains `citation boilerplate`_ text.
 ``dataset_description.json`` is a metadata file in which PETPrep
 records metadata recommended by the BIDS standard.
 
-This layout, now the default, may be explicitly specified with the
+This default layout, may be explicitly specified with the
 ``--output-layout bids`` command-line option.
-For compatibility with versions of PETPrep prior to 21.0, the
+For compatibility with versions of fMRIPrep prior to 21.0, the
 `legacy layout`_ is available via ``--output-layout legacy``.
 
 Processing level
 ----------------
-As of version 23.2.0, PETPrep supports three levels of derivatives:
+As of version 0.0.1, PETPrep 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
@@ -73,13 +73,9 @@ As of version 23.2.0, PETPrep supports three levels of derivatives:
   preprocessing can be assessed. Because no resampling is done, confounds
   and carpetplots will be missing from the reports.
 * ``--level resampling``: This processing mode aims to produce additional
-  derivatives that enable third-party resampling, resampling PET series
+  derivatives that enable third-party resampling, resampling PET data
   in the working directory as needed, but these are not saved to the output
   directory.
-  The ``--me-output-echos`` flag will be enabled at this level, in which
-  case the individual echos will be saved to the working directory after
-  slice-timing correction, head-motion correction, and susceptibility
-  distortion correction.
 * ``--level full``: This processing mode aims to produce all derivatives
   that have previously been a part of the PETPrep output dataset.
   This is the default processing level.
@@ -197,7 +193,7 @@ and lookup tables are provided. ::
       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
+FreeSurfer are copied into this subjects directory, if any PET data are
 sampled to those subject spaces.
 
 Note that the use of ``sourcedata/`` recognizes FreeSurfer derivatives as an input to
@@ -206,16 +202,14 @@ This is strictly true when pre-computed FreeSurfer derivatives are provided eith
 the ``sourcedata/`` directory or passed via the ``--fs-subjects-dir`` flag;
 if PETPrep runs FreeSurfer, then there is a mutual dependency.
 
-Functional derivatives
+PET derivatives
 ~~~~~~~~~~~~~~~~~~~~~~
-Functional derivatives are stored in the ``func/`` subfolder.
-All derivatives contain ``task-<task_label>`` (mandatory) and ``run-<run_index>`` (optional), and
-these will be indicated with ``[specifiers]``::
+PET derivatives are stored in the ``pet/`` subfolder.
 
   sub-<subject_label>/
     func/
-      sub-<subject_label>_[specifiers]_space-<space_label>_desc-brain_mask.nii.gz
-      sub-<subject_label>_[specifiers]_space-<space_label>_desc-preproc_pet.nii.gz
+      sub-<subject_label>_space-<space_label>_desc-brain_mask.nii.gz
+      sub-<subject_label>_space-<space_label>_desc-preproc_pet.nii.gz
 
 .. note::
 
@@ -251,27 +245,6 @@ image and affine transform::
 
    Coregistration outputs are part of the *minimal* processing level.
 
-**Fieldmap registration**.
-
-If a fieldmap is used for the correction of a PET series, then a registration
-is calculated between the PET series and the fieldmap. If, for example, the fieldmap
-is identified with ``"B0Identifier": "TOPUP"``, the generated transform will be named::
-
-  sub-<subject_label>/
-    func/
-      sub-<subject_label>_[specifiers]_from-petref_to-TOPUP_mode-image_xfm.txt
-
-If the association is discovered through the ``IntendedFor`` field of the
-fieldmap metadata, then the transform will be given an auto-generated name::
-
-  sub-<subject_label>/
-    func/
-      sub-<subject_label>_[specifiers]_from-petref_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).
@@ -285,7 +258,7 @@ mid-thickness surface mesh::
     func/
       sub-<subject_label>_[specifiers]_space-T1w_desc-aparcaseg_dseg.nii.gz
       sub-<subject_label>_[specifiers]_space-T1w_desc-aseg_dseg.nii.gz
-      sub-<subject_label>_[specifiers]_hemi-[LR]_space-<space_label>_bold.func.gii
+      sub-<subject_label>_[specifiers]_hemi-[LR]_space-<space_label>_pet.func.gii
 
 Surface output spaces include ``fsnative`` (full density subject-specific mesh),
 ``fsaverage`` and the down-sampled meshes ``fsaverage6`` (41k vertices) and
@@ -356,30 +329,25 @@ also included.
 
 Confounds
 ---------
-The :abbr:`BOLD (blood-oxygen level dependent)` signal measured with fMRI is a mixture of fluctuations
-of both neuronal and non-neuronal origin.
-Neuronal signals are measured indirectly as changes in the local concentration of oxygenated hemoglobin.
-Non-neuronal fluctuations in fMRI data may appear as a result of head motion, scanner noise,
-or physiological fluctuations (related to cardiac or respiratory effects).
-For a detailed review of the possible sources of noise in the BOLD signal, refer to [Greve2013]_.
+The PET signal is a mixture of fluctuations of both neuronal and non-neuronal origin.
+Non-neuronal fluctuations in PET data may appear as a result of head motion or scanner noise.
 
 *Confounds* (or nuisance regressors) are variables representing fluctuations with a potential
 non-neuronal origin.
-Such non-neuronal fluctuations may drive spurious results in fMRI data analysis,
-including standard activation :abbr:`GLM (General Linear Model)` and functional connectivity analyses.
+Such non-neuronal fluctuations may drive spurious results in PET data analysis.
 It is possible to minimize confounding effects of non-neuronal signals by including
 them as nuisance regressors in the GLM design matrix or regressing them out from
-the fMRI data - a procedure known as *denoising*.
-There is currently no consensus on an optimal denoising strategy in the fMRI community.
+the PET data - a procedure known as *denoising*.
+There is currently no consensus on an optimal denoising strategy in the PET community.
 Rather, different strategies have been proposed, which achieve different compromises between
 how much of the non-neuronal fluctuations are effectively removed, and how much of neuronal fluctuations
 are damaged in the process.
 The *PETPrep* pipeline generates a large array of possible confounds.
 
 The most well established confounding variables in neuroimaging are the six head-motion parameters
 (three rotations and three translations) - the common output of the head-motion correction
-(also known as *realignment*) of popular fMRI preprocessing software
-such as SPM_ or FSL_.
+(also known as *realignment*) of popular PET preprocessing software
+such as SPM_ or FreeSurfer_.
 Beyond the standard head-motion parameters, the PETPrep pipeline generates a large array
 of possible confounds, which enable researchers to choose the most suitable denoising
 strategy for their downstream analyses.
@@ -392,7 +360,7 @@ Such tabular files may include over 100 columns of potential confound regressors
    Do not include all columns of ``~_desc-confounds_timeseries.tsv`` table
    into your design matrix or denoising procedure.
    Filter the table first, to include only the confounds (or components thereof)
-   you want to remove from your fMRI signal.
+   you want to remove from your PET signal.
    The choice of confounding variables may depend on the analysis you want to perform,
    and may be not straightforward as no gold standard procedure exists.
    For a detailed description of various denoising strategies and their performance,
@@ -443,9 +411,6 @@ frames with sudden and large motion or intensity spikes.
 - ``dvars`` - the derivative of RMS variance over voxels (or :abbr:`DVARS (derivative of
   RMS variance over voxels)`) [Power2012]_;
 - ``std_dvars`` - standardized :abbr:`DVARS (derivative of RMS variance over voxels)`;
-- ``non_steady_state_outlier_XX`` - columns indicate non-steady state volumes with a single
-  ``1`` value and ``0`` elsewhere (*i.e.*, there is one ``non_steady_state_outlier_XX`` column per
-  outlier/volume).
 
 Detected outliers can be further removed from time series using methods such as:
 volume *censoring* - entirely discarding problematic time points [Power2012]_,
@@ -653,14 +618,14 @@ See implementation on :mod:`~petprep.workflows.pet.confounds.init_pet_confs_wf`.
 Legacy layout
 -------------
 
-Prior to PETPrep 21.0, the following organizational structure was used::
+Prior to tools such as fMRIPrep 21.0, the following organizational structure was used::
 
     <output_dir>/
-      petprep/
+      fmriprep/
       freesurfer/
 
 Although this has the advantage of keeping all outputs together,
-it ensured that the output of PETPrep could not itself be a BIDS derivative dataset,
+it ensured that the output of fMRIPrep could not itself be a BIDS derivative dataset,
 only contain one.
 
 To restore this behavior, use the ``--output-layout legacy`` command-line option.

docs/spaces.rst

@@ -34,7 +34,7 @@ Standard spaces
 When using *PETPrep* in a workflow that will investigate effects that span across
 analytical groupings, neuroimagers typically resample their data on to a standard,
 stereotactic coordinate system.
-The most extended standard space for fMRI analyses is generally referred to MNI.
+The most widely used standard space for PET analyses is generally referred to as MNI.
 For instance, to instruct *PETPrep* to use the MNI template brain distributed with
 FSL as coordinate reference the option will read as follows: ``--output-spaces MNI152NLin6Asym``.
 By default, *PETPrep* uses ``MNI152NLin2009cAsym`` as spatial-standardization reference.