Merge branch 'main' into ref/clean-fmriprep-code-refs

Author: effigies

.coverage

@@ -1,5 +1,7 @@
 Alice Schiavone <[email protected]>
 Alice Schiavone <[email protected]> alice
+Anthony Galassi <[email protected]>
+Anthony Galassi <[email protected]> bendhouseart 
 Christopher J. Markiewicz <[email protected]>
 Christopher J. Markiewicz <[email protected]> <[email protected]>
 Christopher J. Markiewicz <[email protected]> <[email protected]>
@@ -15,5 +17,7 @@ NiPreps Bot <[email protected]>
 NiPreps Bot <[email protected]> nipreps-bot
 Oscar Esteban <[email protected]>
 Oscar Esteban <[email protected]> <[email protected]>
+Rami Hamati <[email protected]>
+Rami Hamati <[email protected]> ramroomh
 Ruben Dörfel <[email protected]>
 Ruben Dörfel <[email protected]> RDoerfel

.mailmap

@@ -8,8 +8,15 @@ Before every release, unlisted contributors will be invited again to add their n
 
 | **Lastname** | **Name** | **Handle** | **ORCID** | **Affiliation** |
 | --- | --- | --- | --- | --- |
+| Bae | Jonghyun | @baej3 | 0000-0002-3987-6603 | National Institute on Aging |
+| Bilgel | Murat | @bilgelm | 0000-0001-5042-7422 | National Institute on Aging |
+| Ceballos | Eric | @eric2302 | 0000-0002-5643-1243 | Montreal Neurological Institute |
+| Dörfel | Ruben | @RDoerfel | 0000-0002-5920-5102 | Karolinska Institutet, and Neurobiology Research Unit |
 | Esteban | Oscar | @oesteban | 0000-0001-8435-6191 | School of Engineering, HES-SO University of Applied Sciences and Arts Western Switzerland, Sion, Switzerland |
+| Galassi | Anthony | @bendhouseart | 0000-0001-6550-4574 | Data Science and Sharing Team, National Institute of Mental Health, Bethesda, MD, USA |
 | Goncalves | Mathias | @mgxd | 0000-0002-7252-7771 | Department of Psychology, Stanford University, CA, USA |
+| Hamati | Rami | @ramroomh | 0000-0001-7213-9253 | Institute of Mental Health Research |
+| Jonghyun | Bae | | 0000-0002-3987-6603 | National Institute on Aging |
 | Legarreta Gorroño | Jon Haitz | @jhlegarreta | 0000-0002-9661-1396 | Brigham and Women's Hospital, Mass General Brigham, Harvard Medical School, MA, USA |
 | Markiewicz | Christopher J. | @effigies | 0000-0002-6533-164X | Department of Psychology, Stanford University, CA, USA |
 | Schiavone | Alice | @aliswh | 0009-0006-4844-2088 | Neurobiology Research Unit, Rigshospitalet, Copenhagen and Department of Computer Science, University of Copenhagen |

.maint/CONTRIBUTORS.md

@@ -203,7 +203,7 @@ ENV PATH="/opt/afni-latest:$PATH" \
 RUN useradd -m -s /bin/bash -G users petprep
 WORKDIR /home/petprep
 ENV HOME="/home/petprep" \
-    LD_LIBRARY_PATH="/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH"
+    LD_LIBRARY_PATH="/usr/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH:-}"
 
 COPY --from=micromamba /bin/micromamba /bin/micromamba
 COPY --from=micromamba /opt/conda/envs/petprep /opt/conda/envs/petprep
@@ -212,7 +212,7 @@ ENV MAMBA_ROOT_PREFIX="/opt/conda"
 RUN micromamba shell init -s bash && \
     echo "micromamba activate petprep" >> $HOME/.bashrc
 ENV PATH="/opt/conda/envs/petprep/bin:$PATH" \
-    CPATH="/opt/conda/envs/petprep/include:$CPATH" \
+    CPATH="/opt/conda/envs/petprep/include:${CPATH:-}" \
     LD_LIBRARY_PATH="/opt/conda/envs/petprep/lib:$LD_LIBRARY_PATH"
 
 # Precaching atlases

Dockerfile

@@ -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/

README.rst

@@ -32,25 +32,46 @@ Therefore, once specified the container options and the image to be run
 the command line is the same as for the *bare-metal* installation but dropping
 the ``petprep`` executable name.
 
-Containerized execution (Docker and Singularity)
+Containerized execution (Docker and Apptainer)
 ================================================
 *PETPrep* is a *NiPreps* application, and therefore follows some overarching principles
 of containerized execution drawn from the BIDS-Apps protocols.
 For detailed information of containerized execution of *NiPreps*, please visit the corresponding
 `Docker <https://www.nipreps.org/apps/docker/>`__
-or `Singularity <https://www.nipreps.org/apps/singularity/>`__ subsections.
+or `Apptainer / Singularity <https://www.nipreps.org/apps/singularity/>`__ subsections.
 The *NiPreps* portal also contains
 `extended details of execution with the Docker wrapper <https://www.nipreps.org/apps/docker/#running-a-niprep-with-a-lightweight-wrapper>`__.
 
 In short, install the ``petprep-docker`` wrapper with pip::
 
   $ python -m pip install petprep-docker
 
+Warning - since petprep relies on many tools (see below Dependencies), you need about 30 Gb free space (the image is 24GB -- also beware of docker settings which by default will not use the last 10% of your disk space).
+
 Then run the ``petprep-docker`` command-line as if you were running
 ``petprep`` on a *bare-metal* installation::
 
   $ petprep-docker <input_bids_path> <derivatives_path> <analysis_level> <named_options>
 
+Alternatively, you can install using a pre-built image using::
+
+  $ docker pull ghcr.io/nipreps/petprep:main
+
+or::
+
+  $ apptainer build petprep.sif docker ://ghcr.io/nipreps/petprep:main
+
+Then run petprep via apptainer as follows::
+
+  $ apptainer run \
+   --bind /path_to_data:/data:ro \
+   --bind /path_to_output:/out \
+   --bind /path_to_freesurfer/license.txt:/license \
+   /path_to_sif/petprep.sif /data /out participant or group \
+   --participant-label sub-ID \
+   --fs-license-file /license \
+   --work-dir /out/work
+
 
 Manually Prepared Environment (Python 3.10+)
 ============================================

docs/installation.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/license.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/usage.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`
 

docs/workflows.rst

@@ -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',