petpal 0.5.5__tar.gz → 0.5.7__tar.gz

{petpal-0.5.5 → petpal-0.5.7}/PKG-INFO

@@ -1,10 +1,9 @@
 Metadata-Version: 2.4
 Name: petpal
-Version: 0.5.5
+Version: 0.5.7
 Summary: PET-PAL (Positron Emission Tomography Processing and Analysis Library)
 Project-URL: Repository, https://github.com/PETPAL-WUSM/PETPAL.git
-Author: Bradley Judge
-Author-email: Furqan Dar <dar@wustl.edu>, Noah Goldman <noahg@wustl.edu>, Kenan Oestreich <kenan.oestreich@wustl.edu>
+Author-email: Noah Goldman <noahg@wustl.edu>, Bradley Judge <bjudge@wustl.edu>, Furqan Dar <dar@wustl.edu>, Kenan Oestreich <kenan.oestreich@wustl.edu>
 License-File: LICENSE
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Intended Audience :: Science/Research
@@ -45,7 +44,17 @@ Description-Content-Type: text/markdown
 
 ## Installation
 
-Currently, we only support building the package directly from source. Clone the repository using your preferred method. After navigating to the top-level directory (where `pyproject.toml` exists), we run the following command in the terminal:
+### Using Pip
+
+The simplest way to install PETPAL is using pip. First, ensure you are using Python version >=3.12. Then, run the following:
+
+```shell
+pip install petpal
+```
+
+### Build from source
+
+Clone the repository using your preferred method. After navigating to the top-level directory (where `pyproject.toml` exists), we run the following command in the terminal:
 
 ```shell
 pip install .  # Installs the package

{petpal-0.5.5 → petpal-0.5.7}/README.md

@@ -9,7 +9,17 @@
 
 ## Installation
 
-Currently, we only support building the package directly from source. Clone the repository using your preferred method. After navigating to the top-level directory (where `pyproject.toml` exists), we run the following command in the terminal:
+### Using Pip
+
+The simplest way to install PETPAL is using pip. First, ensure you are using Python version >=3.12. Then, run the following:
+
+```shell
+pip install petpal
+```
+
+### Build from source
+
+Clone the repository using your preferred method. After navigating to the top-level directory (where `pyproject.toml` exists), we run the following command in the terminal:
 
 ```shell
 pip install .  # Installs the package

{petpal-0.5.5 → petpal-0.5.7}/petpal/cli/cli_pib_processing.py

@@ -94,12 +94,11 @@ def main():
 
     # Configure steps for kinetic modeling container
     suvr_step = ImageToImageStep(name='suvr',
-                                 function=petpal.preproc.image_operations_4d.suvr,
+                                 function=petpal.preproc.standard_uptake_value.suvr,
                                  input_image_path='',
                                  output_image_path='',
                                  ref_region=ref_region_label,
-                                 segmentation_image_path=seg_path,
-                                 verbose=False)
+                                 segmentation_image_path=seg_path)
 
     # Add steps to kinetic modeling container
     kinetic_modeling_container.add_step(step=suvr_step)

{petpal-0.5.5 → petpal-0.5.7}/petpal/cli/cli_preproc.py

@@ -33,7 +33,7 @@ Examples:
 
    .. code-block:: bash
 
-       petpal-preproc register-pet -i /path/to/input_img.nii.gz -o petpal_reg.nii.gz --motion-target 0 600 --anatomical /path/to/anat.nii.gz --half-life 6584
+       petpal-preproc register-pet -i /path/to/input_img.nii.gz -o petpal_reg.nii.gz --motion-target 0 600 --anatomical /path/to/anat.nii.gz
 
 
     * Write regional tacs:
@@ -54,7 +54,7 @@ Examples:
 
    .. code-block:: bash
 
-       petpal-preproc weighted-series-sum -i /path/to/input_img.nii.gz -o petpal_wss.nii.gz --half-life 6584 --start-time 1800 --end-time 7200
+       petpal-preproc weighted-series-sum -i /path/to/input_img.nii.gz -o petpal_wss.nii.gz --start-time 1800 --end-time 7200
 
 
    * SUVR Image:
@@ -95,8 +95,11 @@ import argparse
 import ants
 
 
-from ..utils import useful_functions
-from ..preproc import image_operations_4d, motion_corr, register, regional_tac_extraction
+from ..preproc import (image_operations_4d,
+                       motion_corr,
+                       register,
+                       regional_tac_extraction,
+                       standard_uptake_value)
 
 
 _PREPROC_EXAMPLES_ = r"""
@@ -106,13 +109,13 @@ Examples:
   - Windowed moco:
     petpal-preproc windowed-motion-corr -i /path/to/input_img.nii.gz -o petpal_moco.nii.gz --window-size 120 --transform-type QuickRigid
   - Register to anatomical:
-    petpal-preproc register-pet -i /path/to/input_img.nii.gz -o petpal_reg.nii.gz --motion-target 0 600 --anatomical /path/to/anat.nii.gz --half-life 6584
+    petpal-preproc register-pet -i /path/to/input_img.nii.gz -o petpal_reg.nii.gz --motion-target 0 600 --anatomical /path/to/anat.nii.gz
   - Write regional tacs:
     petpal-preproc write-tacs -i /path/to/input_img.nii.gz -p sub-001 -o /tmp/petpal_tacs -s /path/to/segmentation.nii.gz -l perlcyno -x
   - Write tacs, deprecated:
     petpal-preproc write-tacs-old -i /path/to/input_img.nii.gz -o /tmp/petpal_tacs --segmentation /path/to/segmentation.nii.gz --label-map-path /path/to/dseg.tsv
   - Half life weighted sum of series:
-    petpal-preproc weighted-series-sum -i /path/to/input_img.nii.gz -o petpal_wss.nii.gz --half-life 6584 --start-time 1800 --end-time 7200
+    petpal-preproc weighted-series-sum -i /path/to/input_img.nii.gz -o petpal_wss.nii.gz --start-time 1800 --end-time 7200
   - SUVR:
     petpal-preproc suvr -i /path/to/input_img.nii.gz -o petpal_suvr.nii.gz --segmentation /path/to/segmentation.nii.gz --ref-region 1
   - Gauss blur:
@@ -121,6 +124,8 @@ Examples:
     petpal-preproc rescale-image -i /path/to/input_img.nii.gz -o petpal_rescale.nii.gz --scale-factor 1000
   - Warp to atlas:
     petpal-preproc warp-pet-atlas -i /path/to/input_img.nii.gz -o petpal_reg-atlas.nii.gz --anatomical /path/to/anat.nii.gz --reference-atlas /path/to/atlas.nii.gz
+  - SUV:
+    petpal-preproc suv -i /path/to/input_img.nii.gz -o petpal_suv.nii.gz --weight 75 --dose 250 --start-time 1200 --end-time 3600
 """
 
 
@@ -159,7 +164,7 @@ def _add_common_args(parser: argparse.ArgumentParser) -> None:
     """
     parser.add_argument('-o',
                         '--out-img',
-                        default='petpal_wss_output.nii.gz',
+                        default='petpal_preproc_output.nii.gz',
                         help='Output image filename')
     parser.add_argument('-i', '--input-img',required=True,help='Path to input image.',type=str)
 
@@ -183,10 +188,6 @@ def _generate_args() -> argparse.ArgumentParser:
     parser_wss = subparsers.add_parser('weighted-series-sum',
                                        help='Half-life weighted sum of 4D PET series.')
     _add_common_args(parser_wss)
-    parser_wss.add_argument('--half-life',
-                            required=True,
-                            help='Half life of radioisotope in seconds.',
-                            type=float)
     parser_wss.add_argument('--start-time',
                             required=False,
                             help='Start time of sum in seconds.',
@@ -215,9 +216,6 @@ def _generate_args() -> argparse.ArgumentParser:
                             required=True)
     parser_moco.add_argument('--transform-type', required=False,default='Rigid',
                              help='Transformation type (Rigid or Affine).',type=str)
-    parser_moco.add_argument('--half-life', required=False,
-                             help='Half life of radioisotope in seconds.'
-                                  'Required for some motion targets.',type=float)
 
     parser_tac = subparsers.add_parser('write-tacs',
                                        help='Write ROI TACs from 4D PET using segmentation masks.')
@@ -279,9 +277,19 @@ def _generate_args() -> argparse.ArgumentParser:
                             help='Path to segmentation image in anatomical space.')
     parser_suvr.add_argument('-r',
                              '--ref-region',
-                             help='Reference region to normalize SUVR to.',
+                             help='Reference region to normalize SUVR to. List multiple regions to '
+                                  'combine as one reference.',
                              required=True,
-                             type=int)
+                             type=int,
+                             nargs='+')
+    parser_suvr.add_argument('--start-time',
+                            required=True,
+                            help='Start time for SUVR calculation in seconds from scan start',
+                            type=float)
+    parser_suvr.add_argument('--end-time',
+                            required=True,
+                            help='End time for SUVR calculation in seconds from scan start',
+                            type=float)
 
     parser_blur = subparsers.add_parser('gauss-blur',help='Perform 3D gaussian blurring.')
     _add_common_args(parser_blur)
@@ -328,9 +336,27 @@ def _generate_args() -> argparse.ArgumentParser:
                             help="Motion target option. Can be an image path, "
                                  "'weighted_series_sum' or a tuple (i.e. '-t 0 600' for first "
                                  "ten minutes).")
-    parser_reg.add_argument('-l', '--half-life', help='Half life of radioisotope in seconds.',
-                            type=float)
 
+    parser_suv = subparsers.add_parser('suv',help='Standard Uptake Value (SUV) calculation')
+    _add_common_args(parser_suv)
+    parser_suv.add_argument('-w',
+                            '--weight',
+                            required=True,
+                            help='Weight of the participant in kg',
+                            type=float)
+    parser_suv.add_argument('-d',
+                            '--dose',
+                            required=True,
+                            help='Dose of radiotracer injected in MBq',
+                            type=float)
+    parser_suv.add_argument('--start-time',
+                            required=True,
+                            help='Start time for SUV calculation in seconds from scan start',
+                            type=float)
+    parser_suv.add_argument('--end-time',
+                            required=True,
+                            help='End time for SUV calculation in seconds from scan start',
+                            type=float)
     return parser
 
 
@@ -345,89 +371,89 @@ def main():
         preproc_parser.print_help()
         raise SystemExit('Exiting without command')
 
-    if len(args.motion_target)==1:
-        motion_target = args.motion_target[0]
+    if 'motion_target' in dir(args):
+        if len(args.motion_target)==1:
+            motion_target = args.motion_target[0]
+        else:
+            motion_target = args.motion_target
     else:
-        motion_target = args.motion_target
+        motion_target = None
 
     command = str(args.command).replace('-','_')
 
-    if command=='weighted_series_sum':
-        useful_functions.weighted_series_sum(input_image_4d_path=args.input_img,
-                                             out_image_path=args.out_img,
-                                             half_life=args.half_life,
-                                             start_time=args.start_time,
-                                             end_time=args.end_time,
-                                             verbose=True)
-
-    if command=='auto_crop':
-        image_operations_4d.SimpleAutoImageCropper(input_image_path=args.input_img,
-                                                   out_image_path=args.out_img,
-                                                   thresh_val=args.thresh_val,
-                                                   verbose=True)
-
-    if command=='motion_correction':
-        motion_corr.motion_corr(input_image_4d_path=args.input_img,
+    match command:
+        case 'weighted_series_sum':
+            standard_uptake_value.weighted_sum_for_suv(input_image_path=args.input_img,
+                                                       output_image_path=args.out_img,
+                                                       start_time=args.start_time,
+                                                       end_time=args.end_time)
+        case 'auto_crop':
+            image_operations_4d.SimpleAutoImageCropper(input_image_path=args.input_img,
+                                                    out_image_path=args.out_img,
+                                                    thresh_val=args.thresh_val,
+                                                    verbose=True)
+        case 'motion_correction':
+            motion_corr.motion_corr(input_image_path=args.input_img,
+                                    out_image_path=args.out_img,
+                                    motion_target_option=motion_target,
+                                    verbose=True,
+                                    type_of_transform=args.transform_type)
+        case 'register_pet':
+            register.register_pet(input_reg_image_path=args.input_img,
                                 out_image_path=args.out_img,
+                                reference_image_path=args.anatomical,
                                 motion_target_option=motion_target,
-                                verbose=True,
-                                type_of_transform=args.transform_type,
-                                half_life=args.half_life)
-    if command=='register_pet':
-        register.register_pet(input_reg_image_path=args.input_img,
-                              out_image_path=args.out_img,
-                              reference_image_path=args.anatomical,
-                              motion_target_option=motion_target,
-                              verbose=True,
-                              half_life=args.half_life)
-
-    if command=='write_tacs_old':
-        regional_tac_extraction.write_tacs(input_image_path=args.input_img,
-                                           out_tac_dir=args.out_tac_dir,
-                                           segmentation_image_path=args.segmentation,
-                                           label_map_path=args.label_map_path,
-                                           verbose=True)
-
-    if command=='write_tacs':
-        tac_obj = regional_tac_extraction.WriteRegionalTacs(input_image_path=args.input_img,
-                                                  segmentation_path=args.segmentation,
-                                                  label_map=args.label_map)
-        tac_obj(out_tac_prefix=args.patid,
-                out_tac_dir=args.out_tac_dir,
-                one_tsv_per_region=not args.excel)
-
-    if command=='warp_pet_atlas':
-        register.warp_pet_atlas(input_image_path=args.input_img,
-                                anat_image_path=args.anatomical,
-                                atlas_image_path=args.reference_atlas,
-                                out_image_path=args.out_img,
                                 verbose=True)
-
-    if command=='gauss_blur':
-        image_operations_4d.gauss_blur(input_image_path=args.input_img,
-                                       blur_size_mm=args.blur_size_mm,
+        case 'write_tacs_old':
+            regional_tac_extraction.write_tacs(input_image_path=args.input_img,
+                                            out_tac_dir=args.out_tac_dir,
+                                            segmentation_image_path=args.segmentation,
+                                            label_map_path=args.label_map_path,
+                                            verbose=True)
+        case 'write_tacs':
+            tac_obj = regional_tac_extraction.WriteRegionalTacs(input_image_path=args.input_img,
+                                                    segmentation_path=args.segmentation,
+                                                    label_map=args.label_map)
+            tac_obj(out_tac_prefix=args.patid,
+                    out_tac_dir=args.out_tac_dir,
+                    one_tsv_per_region=not args.excel)
+        case 'warp_pet_atlas':
+            register.warp_pet_to_atlas(input_image_path=args.input_img,
+                                       anat_image_path=args.anatomical,
+                                       atlas_image_path=args.reference_atlas,
                                        out_image_path=args.out_img,
-                                       verbose=True,
-                                       use_fwhm=True)
-
-    if command=='suvr':
-        image_operations_4d.suvr(input_image_path=args.input_img,
-                                 out_image_path=args.out_img,
-                                 segmentation_image_path=args.segmentation,
-                                 ref_region=args.ref_region)
-
-    if command=='windowed_motion_corr':
-        motion_corr.windowed_motion_corr_to_target(input_image_path=args.input_img,
-                                                   out_image_path=args.out_img,
-                                                   motion_target_option=motion_target,
-                                                   w_size=args.window_size,
-                                                   type_of_transform=args.transform_type)
-
-    if command=='rescale_image':
-        input_img = ants.image_read(filename=args.input_img)
-        out_img = image_operations_4d.rescale_image(input_image=input_img,
-                                                    rescale_constant=args.scale_factor)
-        ants.image_write(image=out_img, filename=args.out_img)
+                                       verbose=True)
+        case 'gauss_blur':
+            image_operations_4d.gauss_blur(input_image_path=args.input_img,
+                                        blur_size_mm=args.blur_size_mm,
+                                        out_image_path=args.out_img,
+                                        verbose=True,
+                                        use_fwhm=True)
+        case 'suvr':
+            standard_uptake_value.suvr(input_image_path=args.input_img,
+                                       output_image_path=args.out_img,
+                                       segmentation_image_path=args.segmentation,
+                                       ref_region=args.ref_region,
+                                       start_time=args.start_time,
+                                       end_time=args.end_time)
+        case 'windowed_motion_corr':
+            motion_corr.windowed_motion_corr_to_target(input_image_path=args.input_img,
+                                                    out_image_path=args.out_img,
+                                                    motion_target_option=motion_target,
+                                                    w_size=args.window_size,
+                                                    type_of_transform=args.transform_type)
+        case 'rescale_image':
+            input_img = ants.image_read(filename=args.input_img)
+            out_img = image_operations_4d.rescale_image(input_image=input_img,
+                                                        rescale_constant=args.scale_factor)
+            ants.image_write(image=out_img, filename=args.out_img)
+        case 'suv':
+            standard_uptake_value.suv(input_image_path=args.input_img,
+                                      output_image_path=args.out_img,
+                                      start_time=args.start_time,
+                                      end_time=args.end_time,
+                                      weight=args.weight,
+                                      dose=args.dose)
 
 if __name__ == "__main__":
     main()

{petpal-0.5.5 → petpal-0.5.7}/petpal/cli/cli_vat_processing.py

@@ -7,6 +7,7 @@ from petpal.kinetic_modeling import graphical_analysis,rtm_analysis
 from petpal.preproc import image_operations_4d, motion_corr, register, segmentation_tools
 from petpal.preproc import symmetric_geometric_transfer_matrix as sgtm
 import petpal.preproc.regional_tac_extraction
+import petpal.preproc.standard_uptake_value
 from petpal.utils.bids_utils import gen_bids_like_dir_path, gen_bids_like_filename, gen_bids_like_filepath
 from petpal.utils.image_io import km_regional_fits_to_tsv
 from petpal.utils import useful_functions
@@ -199,13 +200,13 @@ def vat_protocol(subjstring: str,
     wss_file_path = vat_bids_filepath(suffix='pet',folder='pet',space='mpr',desc='WSS')
     suvr_file_path = vat_bids_filepath(suffix='pet',folder='pet',space='mpr',desc='SUVR')
     if 'suvr' not in skip:
-        useful_functions.weighted_series_sum(input_image_4d_path=pet_reg_anat_file,
+        useful_functions.weighted_series_sum(input_image_path=pet_reg_anat_file,
                                              half_life=half_life,
                                              verbose=True,
                                              start_time=suvr_start,
                                              end_time=suvr_end,
                                              out_image_path=wss_file_path)
-        image_operations_4d.suvr(input_image_path=wss_file_path,
+        petpal.preproc.standard_uptake_value.suvr(input_image_path=wss_file_path,
                                  out_image_path=suvr_file_path,
                                  segmentation_image_path=vat_wm_ref_segmentation_file,
                                  ref_region=1,

{petpal-0.5.5 → petpal-0.5.7}/petpal/pipelines/pipelines.py

@@ -4,7 +4,6 @@ import copy
 from typing import Union
 from .steps_base import *
 from .steps_containers import StepsContainer, StepsPipeline
-from ..utils.image_io import get_half_life_from_nifti
 from ..utils.bids_utils import gen_bids_like_dir_path, gen_bids_like_filepath
 
 
@@ -805,9 +804,7 @@ class BIDS_Pipeline(BIDSyPathsForPipelines, StepsPipeline):
         containers = obj.step_containers
         
         containers["preproc"][0].input_image_path = obj.pet_path
-        containers["preproc"][1].kwargs['half_life'] = get_half_life_from_nifti(obj.pet_path)
         containers["preproc"][2].kwargs['reference_image_path'] = obj.anat_path
-        containers["preproc"][2].kwargs['half_life'] = get_half_life_from_nifti(obj.pet_path)
         containers["preproc"][3].segmentation_label_map_path = obj.seg_table
         containers["preproc"][3].segmentation_image_path = obj.seg_img
         containers["preproc"][4].raw_blood_tac_path = obj.blood_path

{petpal-0.5.5 → petpal-0.5.7}/petpal/pipelines/preproc_steps.py

@@ -612,9 +612,12 @@ class ImageToImageStep(FunctionBasedStep):
         Returns:
             ImageToImageStep: A new instance for motion correction frames above mean value.
         """
-        defaults = dict(name=name, function=motion_corr_frames_above_mean_value,
-                        input_image_path='', output_image_path='', motion_target_option='mean_image', verbose=verbose,
-                        half_life=None, )
+        defaults = dict(name=name,
+                        function=motion_corr_frames_above_mean_value,
+                        input_image_path='',
+                        output_image_path='',
+                        motion_target_option='mean_image',
+                        verbose=verbose)
         override_dict = defaults | overrides
         try:
             return cls(**override_dict)
@@ -649,7 +652,7 @@ class ImageToImageStep(FunctionBasedStep):
             return cls(**defaults)
 
     @classmethod
-    def default_register_pet_to_t1(cls, name:str = 'register_pet_to_t1', reference_image_path='', half_life:float=None, verbose=False, **overrides):
+    def default_register_pet_to_t1(cls, name:str = 'register_pet_to_t1', reference_image_path='', verbose=False, **overrides):
         """
         Creates a default instance for registering PET to T1 image using :func:`register_pet<petpal.preproc.register.register_pet>`.
         All paths are empty-strings.
@@ -657,8 +660,6 @@ class ImageToImageStep(FunctionBasedStep):
         Args:
             name (str): Name of the step. Defaults to 'register_pet_to_t1'
             reference_image_path (str): Path to the reference image.
-            half_life (float): Half-life value, in seconds, for the radiotracer. Used to
-                generate a weighted_series_sum image.
             verbose (bool): Whether to run in verbose mode.
             **overrides: Override default parameters.
 
@@ -668,7 +669,7 @@ class ImageToImageStep(FunctionBasedStep):
         """
         defaults = dict(name=name, function=register_pet, input_image_path='', output_image_path='',
                         reference_image_path=reference_image_path, motion_target_option='weighted_series_sum',
-                        verbose=verbose, half_life=half_life)
+                        verbose=verbose)
         override_dict = defaults | overrides
         try:
             return cls(**override_dict)

{petpal-0.5.5 → petpal-0.5.7}/petpal/preproc/__init__.py

@@ -1,8 +1,10 @@
 """Tools for preparing PET data for kinetic modeling and visualization"""
+from . import motion_target
 from . import image_operations_4d
 from . import motion_corr
 from . import partial_volume_corrections
 from . import register
+from . import standard_uptake_value
 from . import symmetric_geometric_transfer_matrix
 from . import segmentation_tools
 from . import decay_correction