petpal 0.5.9__py3-none-any.whl → 0.6.0__py3-none-any.whl

petpal/cli/cli_preproc.py

@@ -83,7 +83,12 @@ Examples:
    .. code-block:: bash
 
        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
- 
+
+    * Crop segmentation to PET FOV:
+
+    .. code-block:: bash
+
+        petpal-preproc seg-crop -i /path/to/input_img.nii.gz -o petpal_cropped_seg.nii.gz --segmentation /path/to/segmentation.nii.gz
 
 See Also:
     * :mod:`~petpal.preproc.image_operations_4d` - module used for operations on 4D images.
@@ -99,7 +104,8 @@ from ..preproc import (image_operations_4d,
                        motion_corr,
                        register,
                        regional_tac_extraction,
-                       standard_uptake_value)
+                       standard_uptake_value,
+                       segmentation_tools)
 
 
 _PREPROC_EXAMPLES_ = r"""
@@ -126,6 +132,10 @@ Examples:
     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
+  - Crop segmentation image to PET FOV:
+    petpal-preproc seg-crop -i /path/to/input_img.nii.gz -o petpal_cropped_seg.nii.gz --segmentation /path/to/segmentation.nii.gz
+  - Add eroded white matter region to segmentation image:
+    petpal-preproc eroded-wm -i /path/to/input_segmentation.nii.gz -o petpal_seg_with_eroded_wm.nii.gz
 """
 
 
@@ -357,6 +367,19 @@ def _generate_args() -> argparse.ArgumentParser:
                             required=True,
                             help='End time for SUV calculation in seconds from scan start',
                             type=float)
+
+    parser_seg_crop = subparsers.add_parser('seg-crop',help='Crop segmentation image to PET FOV')
+    _add_common_args(parser_seg_crop)
+    parser_seg_crop.add_argument('-s',
+                                 '--segmentation',
+                                 required=True,
+                                 help='Path to segmentation image',
+                                 type=str)
+
+    parser_eroded_wm = subparsers.add_parser('eroded-wm',
+                                             help='Add eroded white matter region to segmentation image')
+    _add_common_args(parser_eroded_wm)
+
     return parser
 
 
@@ -454,6 +477,15 @@ def main():
                                       end_time=args.end_time,
                                       weight=args.weight,
                                       dose=args.dose)
+        case 'seg_crop':
+            input_img = ants.image_read(filename=args.input_img)
+            seg_img = ants.image_read(filename=args.segmentation)
+            seg_cropped = segmentation_tools.seg_crop_to_pet_fov(pet_img=input_img,
+                                                                 segmentation_img=seg_img)
+            ants.image_write(seg_cropped,args.out_img)
+        case 'eroded_wm':
+            segmentation_tools.eroded_wm_segmentation(input_segmentation_path=args.input_img,
+                                                      out_segmentation_path=args.out_img)
 
 if __name__ == "__main__":
     main()

petpal/preproc/image_operations_4d.py

@@ -64,10 +64,9 @@ def stitch_broken_scans(input_image_path: str,
     try:
         noninitial_time_zeroes = [meta['TimeZero'] for meta in noninitial_image_metadata_dicts]
         actual_time_zero = initial_image_metadata['TimeZero']
-    except KeyError:
-        raise KeyError(f'.json sidecar for one of your input images does not contain required BIDS key "TimeZero". '
-                       f'Aborting...')
-
+    except KeyError as exc:
+        raise KeyError('.json sidecar for one of your input images does not contain required BIDS '
+                       'key "TimeZero".') from exc
     initial_scan_time = datetime.time.fromisoformat(actual_time_zero)
     placeholder_date = datetime.date.today()
     initial_scan_datetime = datetime.datetime.combine(date=placeholder_date,

petpal/preproc/segmentation_tools.py

@@ -84,7 +84,9 @@ def segmentations_merge(segmentation_primary: np.ndarray,
             regions added.
     """
     for region in regions:
-        region_mask = (segmentation_secondary > region - 0.1) & (segmentation_secondary < region + 0.1)
+        condition_above = segmentation_secondary > region - 0.1
+        condition_below = segmentation_secondary < region + 0.1
+        region_mask = condition_above & condition_below
         segmentation_primary[region_mask] = region
     return segmentation_primary
 
@@ -229,8 +231,9 @@ def resample_segmentation(input_image_path: str,
     seg_image = nibabel.load(segmentation_image_path)
     pet_series = pet_image.get_fdata()
     image_first_frame = pet_series[:, :, :, 0]
+    to_vox_map_tuple = (image_first_frame.shape, pet_image.affine)
     seg_resampled = processing.resample_from_to(from_img=seg_image,
-                                                to_vox_map=(image_first_frame.shape, pet_image.affine),
+                                                to_vox_map=to_vox_map_tuple,
                                                 order=0)
     nibabel.save(seg_resampled, out_seg_path)
     if verbose:
@@ -238,23 +241,30 @@ def resample_segmentation(input_image_path: str,
 
 
 def vat_wm_ref_region(input_segmentation_path: str,
-                      out_segmentation_path: str):
+                      out_segmentation_path: str | None) -> ants.ANTsImage:
     """
     Generates the cortical white matter reference region described in O'Donnell
-    JL et al. (2024) PET Quantification of [18F]VAT in Human Brain and Its 
+    JL et al. (2024).
+     
+    Reference: O'Donnell JL et al. (2024). PET Quantification of [18F]VAT in Human Brain and Its 
     Test-Retest Reproducibility and Age Dependence. J Nucl Med. 2024 Jun 
     3;65(6):956-961. doi: 10.2967/jnumed.123.266860. PMID: 38604762; PMCID:
-    PMC11149597. Requires FreeSurfer segmentation with original label mappings.
+    PMC11149597.
+    
+    Requires FreeSurfer segmentation with original label mappings. 
 
     Args:
         input_segmentation_path (str): Path to segmentation on which white
             matter reference region is computed.
         out_segmentation_path (str): Path to which white matter reference
             region mask image is saved.
+
+    Returns:
+        wm_erode (ants.ANTsImage): Eroded white matter reference region mask image.
     """
     wm_regions = [2,41,251,252,253,254,255,77,3000,3001,3002,3003,3004,3005,
                   3006,3007,3008,3009,3010,3011,3012,3013,3014,3015,3016,3017,
-                  3018,3019,3020,3021,3022,3023,3024,3025,3026,3027,3018,3029,
+                  3018,3019,3020,3021,3022,3023,3024,3025,3026,3027,3028,3029,
                   3030,3031,3032,3033,3034,3035,4000,4001,4002,4003,4004,4005,
                   4006,4007,4008,4009,4010,4011,4012,4013,4014,4015,4016,4017,
                   4018,4019,4020,4021,4022,4023,4024,4025,4026,4027,4028,4029,
@@ -277,7 +287,45 @@ def vat_wm_ref_region(input_segmentation_path: str,
     wm_csf_eroded = ants.threshold_image(image=wm_csf_blurred, low_thresh=0.95, binary=True)
     wm_erode = ants.mask_image(image=wm_merged, mask=wm_csf_eroded)
 
-    ants.image_write(image=wm_erode, filename=out_segmentation_path)
+    if out_segmentation_path is not None:
+        ants.image_write(image=wm_erode, filename=out_segmentation_path)
+
+    return wm_erode
+
+
+def eroded_wm_segmentation(input_segmentation_path: str,
+                           out_segmentation_path: str | None,
+                           eroded_wm_region_mapping: int = 1) -> ants.ANTsImage:
+    """
+    Generates eroded white matter region on a segmentation image and merges it into the image,
+    saving result as a new segmentation image.
+
+    Requires FreeSurfer segmentation with original label mappings.
+    
+    Args:
+        input_segmentation_path (str): Path to input freesurfer segmentation, such as aparc+aseg or
+            wmparc.
+        out_segmentation_path (str): Path to output segmentation image with replaced values in
+            eroded whited matter region.
+        eroded_wm_region_mapping (int): Segmentation mapping for the eroded white matter region in
+            the output image. Default "1".
+
+    Returns:
+        seg_img (ants.ANTsImage): Input segmentation image with values in eroded white matter
+            replaced with `eroded_wm_region_mapping`.
+
+    See also:
+        :meth:`~petpal.preproc.segmentation_tools.vat_wm_ref_region` - function that generates the
+            eroded white matter region.
+    """
+    wm_erode = vat_wm_ref_region(input_segmentation_path=input_segmentation_path,
+                                 out_segmentation_path=None)
+    seg_img = ants.image_read(input_segmentation_path)
+    seg_img[wm_erode==1] = int(eroded_wm_region_mapping)
+    if out_segmentation_path is not None:
+        ants.image_write(image=seg_img, filename=out_segmentation_path)
+
+    return seg_img
 
 
 def vat_wm_region_merge(wmparc_segmentation_path: str,
@@ -500,7 +548,8 @@ def calc_vesselness_mask_from_quantiled_vesselness(input_image: ants.core.ANTsIm
                                                    morph_dil_radius: int = 0,
                                                    z_crop: int = 3) -> ants.core.ANTsImage:
     """
-    Generates a binary vesselness mask from a given vesselness image using quantile-based thresholding.
+    Generates a binary vesselness mask from a given vesselness image using quantile-based
+    thresholding.
 
     This function creates a binary mask by thresholding a vesselness image at a specified
     quantile of non-zero voxel values. Additionally, it allows for optional z-axis cropping

petpal/preproc/symmetric_geometric_transfer_matrix.py

@@ -9,6 +9,7 @@ import warnings
 import numpy as np
 from scipy.ndimage import gaussian_filter
 import ants
+import pandas as pd
 
 from ..meta.label_maps import LabelMapLoader
 from ..utils.useful_functions import check_physical_space_for_ants_image_pair
@@ -92,24 +93,33 @@ class Sgtm:
         elif self.input_image.dimension == 4:
             self.sgtm_result = self.run_sgtm_4d()
 
-    def save(self, output_path: str, out_tac_prefix: str | None = None):
+    def save(self, output_path: str, out_tac_prefix: str | None = None, one_tsv_per_region: bool = False):
         r"""Save sGTM results by writing the resulting array to one or more files.
 
-        The behavior depends on the input iamge provided. If input image is 3D, saves the average sGTM value for each
+        The behavior depends on the input image provided. If input image is 3D, saves the average sGTM value for each
         region in a TSV with one row per region. If input image is 4D, saves time series average values for each frame
-        within each region as a TAC file.
+        within each region. 4D operation saves a single file unless `one_tsv_per_region` is set to True.
 
         Args:
-            output_path (str): Path to save sGTM results. For 3D images, this should typically be a full path to a
-                .tsv file. For 4D images, this is the directory where the sGTM TACs will be saved.
+            output_path (str): Path to save sGTM results. For 3D images, this should typically be
+                the full path to a .tsv file. For 4D images, this is the directory where the sGTM
+                TACs will be saved.
             out_tac_prefix (Optional, str): Prefix of the TAC files. Typically, something like
                 ``'sub-001_ses-001_desc-sGTM'``. Defaults to None.
+            one_tsv_per_region (bool): If True, saves one tsv file for each unique region, as
+                opposed to one file containing all TACs if False. Default False.
         """
         if self.input_image.dimension == 3:
             self.save_results_3d(sgtm_result=self.sgtm_result, out_tsv_path=output_path)
         elif self.input_image.dimension == 4:
-            self.save_results_4d_tacs(sgtm_result=self.sgtm_result, out_tac_dir=output_path,
-                                      out_tac_prefix=out_tac_prefix)
+            if one_tsv_per_region:
+                self.save_results_4d_tacs(sgtm_result=self.sgtm_result,
+                                          out_tac_dir=output_path,
+                                          out_tac_prefix=out_tac_prefix)
+            else:
+                self.save_results_4d_multitacs(sgtm_result=self.sgtm_result,
+                                               out_tac_dir=output_path,
+                                               out_tac_prefix=out_tac_prefix)
 
     def __call__(self, output_path: str, out_tac_prefix: str | None = None):
         r"""Run sGTM and save results.
@@ -162,8 +172,20 @@ class Sgtm:
                           "segmentation to ensure this criteria is met, or use sGTM without "
                           "label map for automated complete region mapping.")
             seg_label_map = LabelMapLoader(label_map_option=self.label_map_option).label_map
-            region_index_map = list(seg_label_map.values())
-            region_short_names = list(seg_label_map.keys())
+            unique_mappings = unique_segmentation_labels(segmentation_img=self.segmentation_image,
+                                                       zeroth_roi=self.zeroth_roi)
+            region_index_map = []
+            region_short_names = []
+            label_map_labels = list(seg_label_map.keys())
+            label_map_mappings = list(seg_label_map.values())
+            for mapping in unique_mappings:
+                if mapping in label_map_mappings:
+                    id_mapping_index = label_map_mappings.index(mapping)
+                    region_index_map.append(label_map_mappings[id_mapping_index])
+                    region_short_names.append(label_map_labels[id_mapping_index])
+                else:
+                    region_index_map.append(mapping)
+                    region_short_names.append(f'UNK{mapping:05d}')
         return (region_index_map, region_short_names)
 
 
@@ -291,7 +313,6 @@ class Sgtm:
 
         return unique_labels, t_corrected, condition_number
 
-
     def run_sgtm_4d(self) -> np.ndarray:
         r"""Calculated partial volume corrected TACs on a 4D image by running sGTM on each frame in
         the 4D image.
@@ -326,7 +347,6 @@ class Sgtm:
 
         return np.asarray(frame_results)
 
-
     def save_results_3d(self, sgtm_result: tuple, out_tsv_path: str):
         r"""Saves the result of an sGTM calculation.
 
@@ -337,12 +357,10 @@ class Sgtm:
             sgtm_result (tuple): Output of :meth:`run_sgtm_3d`
             out_tsv_path (str): File path to which results are saved.
         """
-        sgtm_result_array = np.array([sgtm_result[0], sgtm_result[1]]).T
-        np.savetxt(out_tsv_path,sgtm_result_array,
-                   header='Region\tMean',
-                   fmt=['%.0f','%.2f'],
-                   comments='')
-
+        sgtm_result_to_write = pd.DataFrame(columns=['Region','Mean'])
+        sgtm_result_to_write['Region'] = self.unique_labels[1]
+        sgtm_result_to_write['Mean'] = sgtm_result[1]
+        sgtm_result_to_write.to_csv(out_tsv_path,sep='\t',index=False)
 
     def save_results_4d_tacs(self,
                              sgtm_result: np.ndarray,
@@ -368,3 +386,31 @@ class Sgtm:
                                         activity=tac_array[i,:])
             out_tac_path = os.path.join(f'{out_tac_dir}', f'{out_tac_prefix}_seg-{name}_tac.tsv')
             pvc_tac.to_tsv(filename=out_tac_path)
+
+    def save_results_4d_multitacs(self,
+                                  sgtm_result: np.ndarray,
+                                  out_tac_dir: str,
+                                  out_tac_prefix: str):
+        """Like :meth:`save_results_4d_tacs`, but saves all TACs to a single file.
+
+        Args:
+            sgtm_result (np.ndarray): Array of results from :meth:`run_sgtm_4d`
+            out_tac_dir (str): Path to folder where regional TACs will be saved.
+            out_tac_prefix (str): Prefix of the TAC files.
+        """
+        os.makedirs(out_tac_dir, exist_ok=True)
+        input_image_path = self.input_image_path
+        scan_timing = ScanTimingInfo.from_nifti(image_path=input_image_path)
+        tac_time_starts = scan_timing.start_in_mins
+        tac_time_ends = scan_timing.end_in_mins
+
+        tac_array = np.asarray(sgtm_result).T
+        tacs_data_columns = ['frame_start(min)','frame_end(min)']+self.unique_labels[1]
+        tacs_data = pd.DataFrame(columns=tacs_data_columns)
+
+        tacs_data['frame_start(min)'] = tac_time_starts
+        tacs_data['frame_end(min)'] = tac_time_ends
+        for i, (_label, name) in enumerate(zip(*self.unique_labels)):
+            tacs_data[name] = tac_array[i,:]
+            tacs_data[f'{name}_unc'] = np.full(tac_array.shape[1],np.nan)
+        tacs_data.to_csv(f'{out_tac_dir}/{out_tac_prefix}_multitacs.tsv', sep='\t', index=False)

{petpal-0.5.9.dist-info → petpal-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petpal
-Version: 0.5.9
+Version: 0.6.0
 Summary: PET-PAL (Positron Emission Tomography Processing and Analysis Library)
 Project-URL: Repository, https://github.com/PETPAL-WUSM/PETPAL.git
 Author-email: Noah Goldman <noahg@wustl.edu>, Bradley Judge <bjudge@wustl.edu>, Furqan Dar <dar@wustl.edu>, Kenan Oestreich <kenan.oestreich@wustl.edu>

{petpal-0.5.9.dist-info → petpal-0.6.0.dist-info}/RECORD

@@ -6,7 +6,7 @@ petpal/cli/cli_idif.py,sha256=6lh_kJHcGjlHDXZOvbiuHrNqpk5FovVV5_j7_dPHTHU,5145
 petpal/cli/cli_parametric_images.py,sha256=JBFb8QlxZoGOzqvCJPFuZ7czzGWntJP5ZcfeM5-QF4Y,7385
 petpal/cli/cli_pib_processing.py,sha256=ye_yw0ZQ4cSrMNemGR7cU9v6epD7Wbq1xaNAJwLzV_8,6889
 petpal/cli/cli_plot_tacs.py,sha256=XycaYQQl9Jp5jqDp3QXOlVT2sXHYYpYSraEArxsfJec,6479
-petpal/cli/cli_preproc.py,sha256=y5YvRliXC3zNY8oBJgTkzwPH9YNwWnEUWgiltUAv7AU,21850
+petpal/cli/cli_preproc.py,sha256=Wy0Y_2hTXg_Xyg2F7xOA93B4X4wzKX6QJDkB5mSikOI,23607
 petpal/cli/cli_pvc.py,sha256=DC0JZ6p1pkc5BDgQ006bi9y0Mz32ENrjUaOtSvFobP4,3967
 petpal/cli/cli_reference_tissue_models.py,sha256=18BlKN4rMehyFbdq_yr88oztqR99_gBtWKImhwf7CQY,13283
 petpal/cli/cli_stats.py,sha256=Mqbzc9yYo9SVAfxzaYbAbk7EheW472l1PY_ptlD1DOI,2050
@@ -38,15 +38,15 @@ petpal/pipelines/steps_base.py,sha256=W7GVN5-tsXe_7fvhoMRIlOk5ggY8V2wpSSmDONphLn
 petpal/pipelines/steps_containers.py,sha256=TV4LkPK48OnAds10vLcsPI3qtWjHsmwr6XGu3hup59Q,33767
 petpal/preproc/__init__.py,sha256=HmTVnCiKMxetDT_w-qU_62UOC39_A83LHXhZm07Q81I,504
 petpal/preproc/decay_correction.py,sha256=jT8X2lmMrdGf9-lo1ooKul_yomPqm1p24gB9On_GHl0,6872
-petpal/preproc/image_operations_4d.py,sha256=IqzwxaWxoWC1gmK00uuHIwlhx8e_eQ44C6yVFuu73W4,31371
+petpal/preproc/image_operations_4d.py,sha256=UEaMw9YwnX-TOvmKxsA2qsU5GRR1Tq46l7gQz7TVzdk,31372
 petpal/preproc/motion_corr.py,sha256=dz10qjXBVTF_RH5RPZ68drUVX2qyj-MnZ674_Ccwz2Y,28670
 petpal/preproc/motion_target.py,sha256=_OJp3NoYcyD3Ke3wl2KbfOhbJ6dp6ZduR9LLz0rIaC0,3945
 petpal/preproc/partial_volume_corrections.py,sha256=J06j_Y_lhj3b3b9M5FbB2r2EPWQvoymG3GRUffSlYdE,6799
 petpal/preproc/regional_tac_extraction.py,sha256=ZXo2u-EAUg5wZj7GGYLMEaOAfLv8OCOR-Gd0xvih6Y4,22358
 petpal/preproc/register.py,sha256=NKg8mt_XMGa5HBdxYZh3sMu_KMJ0W41VHlX4Zl8wlyE,14171
-petpal/preproc/segmentation_tools.py,sha256=Xi1ZnBs3sp23MHWPPOLjuXi6qp4-igwIPXFJ4B_Yzsk,27186
+petpal/preproc/segmentation_tools.py,sha256=CDD0NWV23rkNB56HjZGLsO4HbV61O57KsNzQsR4d06g,29106
 petpal/preproc/standard_uptake_value.py,sha256=YJIt0fl3fwMLl0tRYHpPPprMTaN4Q5JjQ5dx_CQX1nI,7494
-petpal/preproc/symmetric_geometric_transfer_matrix.py,sha256=ELkr7Mo233to1Rwml5YJ-aBvmTSk3LHNSdRhnX0WBDw,17575
+petpal/preproc/symmetric_geometric_transfer_matrix.py,sha256=Sr5qMTiNC76ZRKiGG5So7fceV_Lr0ql7UybO_kJgmNo,20360
 petpal/utils/__init__.py,sha256=PlxBIKUtNvtSFnNZqz8myszOysaYzS8nSILMK4haVGg,412
 petpal/utils/bids_utils.py,sha256=3eZAzwGpOBUQ5ShVBUJJpmUBUhr3VcOikR-KpGCsdE0,7664
 petpal/utils/constants.py,sha256=Bz0HooHVx_8blXrBagS7g6rcMm8PnCzbO0YY4qR0oSo,738
@@ -65,8 +65,8 @@ petpal/visualizations/graphical_plots.py,sha256=ZCKUeLX2TAQscuHjA4bzlFm1bACHIyCw
 petpal/visualizations/image_visualization.py,sha256=Ob6TD4Q0pIrxi0m9SznK1TRWbX1Ea9Pt4wNMdRrTfTs,9124
 petpal/visualizations/qc_plots.py,sha256=iaCPe-LWWyM3OZzDPZodHZhP-z5fRdpUgaH7QS9VxPM,1243
 petpal/visualizations/tac_plots.py,sha256=zSGdptL-EnqhfDViAX8LFunln5a1b-NJ5ft7ZDcxQ38,15116
-petpal-0.5.9.dist-info/METADATA,sha256=BVL0zucYR-sLQU16D61fSFD0_ADn97mcXz6Qva6a9UQ,2617
-petpal-0.5.9.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-petpal-0.5.9.dist-info/entry_points.txt,sha256=0SZmyXqBxKzQg2eerDA16n2BdUEXyixEm0_AUo2dFns,653
-petpal-0.5.9.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-petpal-0.5.9.dist-info/RECORD,,
+petpal-0.6.0.dist-info/METADATA,sha256=L5uinIwYmIUU0Ie_1wiLf-9TDeUeJrq6cHUuVXKSIq0,2617
+petpal-0.6.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+petpal-0.6.0.dist-info/entry_points.txt,sha256=0SZmyXqBxKzQg2eerDA16n2BdUEXyixEm0_AUo2dFns,653
+petpal-0.6.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+petpal-0.6.0.dist-info/RECORD,,