Merge pull request #89 from nipreps/update_documentation

WIP: Update documentation

Author: mnoergaard

README.rst

@@ -139,3 +139,13 @@ 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/license.rst

@@ -6,9 +6,9 @@ projects of the framework.
 
 License information
 -------------------
-Copyright (c) 2023, the *NiPreps* Developers.
+Copyright (c) 2025, the *NiPreps* Developers.
 
-As of the 21.0.x pre-release and release series, *PETPrep* is
+As of the 0.0.x pre-release and release series, *PETPrep* is
 licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
@@ -20,20 +20,14 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 
-Copyright (c) 2015-2023, the *PETPrep* developers and the CRN.
+Copyright (c) 2025-, the *NiPreps* developers.
 All rights reserved.
 
-*PETPrep* 20.2 series and earlier are
-licensed under the BSD 3-clause license.
-You may obtain a copy of the License at
-https://opensource.org/licenses/BSD-3-Clause
-
 All trademarks referenced herein are property of their respective holders.
 
 The ``petprep-wrapper`` for Docker
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Copyright (c) 2020-2023, the *NiPreps* Developers.
-Copyright (c) 2015-2020, the *PETPrep* developers and the CRN.
+Copyright (c) 2025-, the *NiPreps* Developers.
 All rights reserved.
 
 *PETPrep-wrapper* is

docs/usage.rst

@@ -176,6 +176,39 @@ This feature has several intended use-cases:
 See also the ``--level`` flag, which can be used to control which derivatives are
 generated.
 
+Head motion correction
+----------------------
+*PETPrep* can correct for head motion in the PET data.
+The head motion is estimated using a frame-based robust registration approach to an unbiased mean 
+volume implemented in FreeSurfer's mri_robust_register (Reuter et al., 2010), combined with 
+preprocessing steps using tools from FSL (Jenkinson et al., 2012). Specifically, for the estimation 
+of head motion, each frame is initially smoothed with a Gaussian filter (full-width half-maximum [FWHM] of 10 mm, --hmc-fwhm 10), 
+followed by thresholding at 20% of the intensity range to reduce noise and improve registration 
+accuracy (removing stripe artefacts from filtered back projection reconstructions). 
+Per default, the motion is estimated selectively of frames acquired after 120 seconds post-injection of the tracer (--hmc-start-time 120),
+as frames before this often contain low count statistics. Frames preceding 120 seconds were corrected 
+using identical transformations as derived for the first frame after 120 seconds. The robust 
+registration (mri_robust_register) algorithm utilized settings optimized for PET data: intensity 
+scaling was enabled, automated sensitivity detection was activated, and the Frobenius norm threshold 
+for convergence was set at 0.0001, ensuring precise and consistent alignment across frames.
+
+To edit the motion correction parameters and run the workflow, use: ::
+
+    $ petprep /data/bids_root /out participant --hmc-fwhm 8 --hmc-start-time 60
+
+Segmentation
+----------------
+*PETPrep* can segment the brain into different brain regions and extract time activity curves from these regions.
+The ``--seg`` flag selects the segmentation method to use.
+Available options are ``gtm`` (default) whole-brain segmentation from freesurfer, ``brainstem``, ``wm`` (white matter), ``thalamicNuclei``, ``hippocampusAmygdala``, ``raphe``, and ``limbic``.
+
+The ``gtm`` segmentation is a whole-brain segmentation that includes the
+cerebral cortex, subcortical structures, and cerebellum.
+
+To run the segmentation with the default ``gtm`` method, use: ::
+
+    $ petprep /data/bids_root /out participant --seg gtm 
+
 Partial volume correction
 -------------------------
 *PETPrep* can optionally correct PET images for partial volume effects.
@@ -223,6 +256,8 @@ Use ``--ref-mask-name`` to select a predefined region and
 The available masks are and do not require ``--ref-mask-index`` to be specified:
 - ``cerebellum``: Cerebellar gray matter (requires the ``--seg gtm`` option).
 - ``semiovale``: White matter in the centrum semiovale (requires the ``--seg wm`` option).
+- ``neocortex``: Neocortical gray matter (requires the ``--seg gtm`` option).
+- ``thalamus``: Thalamic gray matter (requires the ``--seg gtm`` option).
 
 The presets are defined in ``petprep/data/reference_mask/config.json``.
 
@@ -251,7 +286,7 @@ All bugs, concerns and enhancement requests for this software can be submitted h
 https://github.com/nipreps/petprep/issues.
 
 If you have a problem or would like to ask a question about how to use *PETPrep*,
-please submit a question to `NeuroStars.org <https://neurostars.org/tag/petprep>`_ with an ``petprep`` tag.
+please submit a question to `NeuroStars.org <https://neurostars.org/tag/petprep>`_ with a ``petprep`` tag.
 NeuroStars.org is a platform similar to StackOverflow but dedicated to neuroinformatics.
 
 Previous questions about *PETPrep* are available here:

docs/workflows.rst

@@ -8,8 +8,8 @@ available and are used as the input.
 Certain processing steps will run only when the required metadata is
 available in the input dataset.
 
-A (very) high-level view of the simplest pipeline (for a single-band dataset with only
-one task, single-run, with no slice-timing information nor fieldmap acquisitions)
+A (very) high-level view of the simplest pipeline (for a single dataset with only
+a single tracer and single baseline)
 is presented below:
 
 .. workflow::
@@ -394,27 +394,6 @@ customized via the :option:`--hmc-fwhm` and :option:`--hmc-start-time`
 command line options.  By default a 10 mm FWHM Gaussian is applied and
 estimation begins at 120 s.
 
-Susceptibility Distortion Correction (SDC)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-One of the major problems that affects :abbr:`EPI (echo planar imaging)` data
-is the spatial distortion caused by the inhomogeneity of the field inside
-the scanner.
-
-.. figure:: _static/unwarping.svg
-
-    Applying susceptibility-derived distortion correction, based on
-    fieldmap estimation.
-
-Please note that all routines for susceptibility-derived distortion correction
-have been excised off of *PETPrep* for utilization on other projects
-(e.g., `dMRIPrep <https://www.nipreps.org/dmriprep>`__).
-For more detailed documentation on
-:abbr:`SDC (susceptibility-derived distortion correction)`
-routines, check on the `SDCFlows component <https://www.nipreps.org/sdcflows>`__.
-
-Theory, methods and references are found within the
-`SDCFlows documentation <https://www.nipreps.org/sdcflows/master/api/sdcflows.workflows.fit.fieldmap.html>`__.
-
 Pre-processed PET in native space
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 :py:func:`~petprep.workflows.pet.fit.init_pet_native_wf`
@@ -435,14 +414,13 @@ A new *preproc* :abbr:`PET (positron emission tomography)` series is generated
 from the original data in the original space.
 All volumes in the :abbr:`PET (positron emission tomography)` series are
 resampled in their native space by concatenating the mappings found in previous
-correction workflows (:abbr:`HMC (head-motion correction)` and
-:abbr:`SDC (susceptibility-derived distortion correction)` if executed)
+correction workflows (:abbr:`HMC (head-motion correction)`)
 for a one-shot interpolation process.
 Interpolation uses a Lanczos kernel.
 
 .. _pet_reg:
 
-EPI to T1w registration
+PET to T1w registration
 ~~~~~~~~~~~~~~~~~~~~~~~
 :py:func:`~petprep.workflows.pet.registration.init_bbreg_wf`
 

petprep/cli/parser.py

@@ -360,20 +360,6 @@ def _bids_filter(value, parser):
         action=DeprecatedAction,
         help='Deprecated - use `--force no-bbr` instead.',
     )
-    g_conf.add_argument(
-        '--hmc-fwhm',
-        action='store',
-        default=10,
-        type=float,
-        help='FWHM for Gaussian smoothing applied during head-motion estimation.',
-    )
-    g_conf.add_argument(
-        '--hmc-start-time',
-        action='store',
-        default=120,
-        type=float,
-        help='Time (in seconds) after which head-motion estimation is performed.',
-    )
     g_conf.add_argument(
         '--random-seed',
         dest='_random_seed',
@@ -536,6 +522,22 @@ def _bids_filter(value, parser):
         'The user is responsible for ensuring that all necessary files are present.',
     )
 
+    g_hmc = parser.add_argument_group('Options for head motion correction')
+    g_hmc.add_argument(
+        '--hmc-fwhm',
+        action='store',
+        default=10,
+        type=float,
+        help='FWHM for Gaussian smoothing applied during head-motion estimation.',
+    )
+    g_hmc.add_argument(
+        '--hmc-start-time',
+        action='store',
+        default=120,
+        type=float,
+        help='Time (in seconds) after which head-motion estimation is performed.',
+    )
+
     g_seg = parser.add_argument_group('Segmentation options')
     g_seg.add_argument(
         '--seg',