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

petpal/cli/cli_graphical_analysis.py

@@ -59,7 +59,6 @@ def main():
     parser_multitac = subparsers.add_parser('graphical-analysis-multitac')
     _add_common_args(parser_multitac)
     parser_multitac.add_argument("-r", "--roi-tacs-dir", required=True, help="Path to directory containing ROI TTACs")
-    parser_multitac.add_argument("-x","--excel", action='store_true',help='Set to output an excel-compatible table in a single file.',default=False)
 
     args = parser.parse_args()
     command = str(args.command).replace('-','_')
@@ -90,7 +89,7 @@ def main():
                                                               output_filename_prefix=args.output_filename_prefix,
                                                               method=method,
                                                               fit_thresh_in_mins=args.threshold_in_mins)
-        graphical_analysis(one_file_per_region=not args.excel, **run_kwargs)
+        graphical_analysis(output_as_tsv=True, output_as_json=False, **run_kwargs)
 
     if args.print:
         for key, val in graphical_analysis.analysis_props.items():

petpal/kinetic_modeling/graphical_analysis.py

@@ -1103,13 +1103,13 @@ class MultiTACGraphicalAnalysis(GraphicalAnalysis, MultiTACAnalysisMixin):
         if self.analysis_props[0]['RSquared'] is None:
             raise RuntimeError("'run_analysis' method must be called before 'save_analysis'.")
 
-        if output_as_tsv:
+        if output_as_json:
             km_multifit_analysis_to_jsons(analysis_props=self.analysis_props,
                                           output_directory=self.output_directory,
                                           output_filename_prefix=self.output_filename_prefix,
                                           method=self.method,
                                           inferred_seg_labels=self.inferred_seg_labels)
-        if output_as_json:
+        if output_as_tsv:
             km_multifit_analysis_to_tsv(analysis_props=self.analysis_props,
                                         output_directory=self.output_directory,
                                         output_filename_prefix=self.output_filename_prefix,

petpal/preproc/regional_tac_extraction.py

@@ -1,6 +1,7 @@
 """
 Regional TAC extraction
 """
+from warnings import warn
 import os
 from collections.abc import Callable
 import pathlib
@@ -345,6 +346,20 @@ class WriteRegionalTacs:
             region_name = f'UNK{label:>04}'
         return region_name
 
+    def is_empty_region(self,pet_masked_region: np.ndarray) -> bool:
+        """Check if masked PET region has zero matched voxels, or is all NaNs. In either case,
+        return True, otherwise return False.
+        
+        Args:
+            pet_masked_region (np.ndarray): Array of PET voxels masked to a specific region.
+            
+        Returns:
+            pet_masked_region_is_empty (bool): If True, input region is empty."""
+        if pet_masked_region.size==0:
+            return True
+        if np.all(np.isnan(pet_masked_region)):
+            return True
+        return False
 
     def extract_tac(self,region_mapping: int | list[int], **tac_calc_kwargs) -> TimeActivityCurve:
         """
@@ -359,15 +374,46 @@ class WriteRegionalTacs:
         """
         region_mask = combine_regions_as_mask(segmentation_img=self.seg_arr,
                                               label=region_mapping)
+
         pet_masked_region = apply_mask_4d(input_arr=self.pet_arr,
                                           mask_arr=region_mask)
-        extracted_tac, uncertainty = self.tac_extraction_func(pet_voxels=pet_masked_region,
-                                                              **tac_calc_kwargs)
+
+        is_region_empty = self.is_empty_region(pet_masked_region=pet_masked_region)
+        if is_region_empty:
+            extracted_tac = np.empty_like(self.scan_timing.center_in_mins)
+            extracted_tac.fill(np.nan)
+            uncertainty = extracted_tac.copy()
+        else:
+            extracted_tac, uncertainty = self.tac_extraction_func(pet_voxels=pet_masked_region,
+                                                                  **tac_calc_kwargs)
         region_tac = TimeActivityCurve(times=self.scan_timing.center_in_mins,
                                        activity=extracted_tac,
                                        uncertainty=uncertainty)
         return region_tac
 
+    def gen_tacs_data_frame(self) -> pd.DataFrame:
+        """Get empty data frame to store TACs. Sets first two columns to frame start and end
+        times, and remaining columns are named by region activity and uncertainty, based on the
+        regions included in the label map.
+        
+        Returns:
+            tacs_data (pd.DataFrame): Data frame with columns set for frame start and end time,
+            and activity and uncertainty for each included region. Frame start and end time
+            columns filled with scan timing data.
+        """
+        activity_uncertainty_column_names = []
+        for region_name in self.region_names:
+            activity_uncertainty_column_names.append(region_name)
+            activity_uncertainty_column_names.append(f'{region_name}_unc')
+        cols_list = ['frame_start(min)','frame_end(min)'] + activity_uncertainty_column_names
+        tacs_data = pd.DataFrame(columns=cols_list)
+
+        tacs_data['frame_start(min)'] = self.scan_timing.start_in_mins
+        tacs_data['frame_end(min)'] = self.scan_timing.end_in_mins
+
+        return tacs_data
+
+
 
     def write_tacs(self,
                    out_tac_prefix: str,
@@ -378,7 +424,8 @@ class WriteRegionalTacs:
         Function to write Tissue Activity Curves for each region, given a segmentation,
         4D PET image, and label map. Computes the average of the PET image within each
         region. Writes TACs in TSV format with region name, frame start time, frame end time, and
-        activity and uncertainty within each region.
+        activity and uncertainty within each region. Skips writing regions without any matched
+        voxels.
 
         Args:
             out_tac_prefix (str): Prefix for the output files, usually the BIDS subject and
@@ -387,22 +434,34 @@ class WriteRegionalTacs:
             one_tsv_per_region (bool): If True, write one TSV TAC file for each region in the
                 image. If False, write one TSV file with all TACs in the image.
             **tac_calc_kwargs: Additional keywords passed onto tac_extraction_func.
-        """
-        tacs_data = pd.DataFrame()
 
-        tacs_data['frame_start(min)'] = self.scan_timing.start_in_mins
-        tacs_data['frame_end(min)'] = self.scan_timing.end_in_mins
+        Raises:
+            Warning: for each region without any matched voxels, warn user that TAC is skipped.
+        """
+        tacs_data = self.gen_tacs_data_frame()
 
+        empty_regions = []
         for i,region_name in enumerate(self.region_names):
             mappings = self.region_maps[i]
             tac = self.extract_tac(region_mapping=mappings, **tac_calc_kwargs)
+            if tac.contains_any_nan:
+                empty_regions.append(region_name)
+                continue
             if one_tsv_per_region:
+                os.makedirs(out_tac_dir, exist_ok=True)
                 tac.to_tsv(filename=f'{out_tac_dir}/{out_tac_prefix}_seg-{region_name}_tac.tsv')
             else:
                 tacs_data[region_name] = tac.activity
                 tacs_data[f'{region_name}_unc'] = tac.uncertainty
 
+        if len(empty_regions)>0:
+            warn("Empty regions were found during tac extraction. TACs for the following regions "
+                 f"were not saved: {empty_regions}")
+            tacs_data.drop(empty_regions,axis=1,inplace=True)
+            tacs_data.drop([f'{region}_unc' for region in empty_regions],axis=1,inplace=True)
+
         if not one_tsv_per_region:
+            os.makedirs(out_tac_dir, exist_ok=True)
             tacs_data.to_csv(f'{out_tac_dir}/{out_tac_prefix}_multitacs.tsv', sep='\t', index=False)
 
     def __call__(self,

petpal/preproc/segmentation_tools.py

@@ -14,7 +14,9 @@ import nibabel
 from nibabel import processing
 import pandas as pd
 
-from ..utils.useful_functions import gen_nd_image_based_on_image_list
+from ..utils.useful_functions import (gen_nd_image_based_on_image_list,
+                                      check_physical_space_for_ants_image_pair,
+                                      get_average_of_timeseries)
 from ..utils import math_lib
 
 
@@ -571,3 +573,28 @@ def unique_segmentation_labels(segmentation_img: ants.core.ANTsImage | np.ndarra
     if not zeroth_roi:
         labels = labels[labels != 0]
     return labels
+
+def seg_crop_to_pet_fov(pet_img: ants.ANTsImage,
+                        segmentation_img: ants.ANTsImage,
+                        pet_thresh_value: float=np.finfo(float).eps) -> ants.ANTsImage:
+    """Zero out segmentation values that lie outside of the PET FOV.
+    
+    Especially applicable to scanners with limited FOV (field of view). PET voxels with values less
+    than 1e-36 are considered outside of the FOV.
+    
+    Args:
+        pet_img (ants.ANTsImage): PET image in anatomical space used to crop segmentation
+        segmentation_img (ants.ANTsImage): Segmentation image in anatomical space such as
+            FreeSurfer to which FOV cropping is applied.
+        pet_thresh_value (float): Lower threshold for the PET image by which the segmentation image
+            is masked. Should be <<1. Default machine epsilon for `float`.
+
+    Returns:
+        segmentation_masked_img (ants.ANTsImage): Segmentation image masked to PET FOV.
+    """
+    if not check_physical_space_for_ants_image_pair(pet_img, segmentation_img):
+        raise ValueError("PET and segmentation image must share physical space.")
+    pet_mean_img = get_average_of_timeseries(input_image=pet_img)
+    pet_mask = ants.threshold_image(pet_mean_img, pet_thresh_value)
+    seg_masked = ants.mask_image(segmentation_img, pet_mask)
+    return seg_masked

petpal/utils/time_activity_curve.py

@@ -75,6 +75,7 @@ class TimeActivityCurve:
         return len(self.times)
 
     def __post_init__(self):
+        self.validate_activity()
         if self.uncertainty.size == 0:
             self.uncertainty = np.empty_like(self.times)
             self.uncertainty[:] = np.nan
@@ -82,6 +83,33 @@ class TimeActivityCurve:
             f"TAC fields must have the same shapes.\ntimes:{self.times.shape}"
             "activity:{self.activity.shape} uncertainty:{self.uncertainty.shape}")
 
+    def validate_activity(self):
+        """Validates that the activity attribute is defined correctly.
+        
+        `self.activity` must have the following properties:
+        1) It must exist and not be None
+        2) It must be a numpy array
+        3) It must have dtype float
+        4) It must be 1D
+
+        This function raises a ValueError if self.activity does not meet the first criteria, and
+        attempts to coerce self.activity into a 1D, numeric numpy array with dtype float if
+        criteria 2-4 are not met.
+        """
+        if not hasattr(self, "activity") or self.activity is None:
+            raise ValueError("TimeActivityCurve.activity must be provided and not be None")
+
+        try:
+            arr = np.asarray(self.activity, dtype=float)
+        except (TypeError, ValueError) as exc:
+            error_message = "TimeActivityCurve.activity must be numeric or convertible to numeric"
+            raise TypeError(error_message) from exc
+
+        if arr.ndim != 1:
+            arr = arr.ravel()
+
+        self.activity = arr
+
     @classmethod
     def from_tsv(cls, filename: str):
         """
@@ -509,29 +537,29 @@ class TimeActivityCurve:
                                                           kind='linear',
                                                           fill_value='extrapolate')(tac.times)
             return TimeActivityCurve(tac.times, shifted_vals_on_tac_times)
-        else:
-            return shifted_tac
+        return shifted_tac
 
     @staticmethod
     def tac_dispersion(tac: 'TimeActivityCurve',
-                       disp_func: Callable[[np.ndarray, ...], np.ndarray],
+                       disp_func: Callable[..., np.ndarray],
                        disp_kwargs: dict,
                        num_samples: int = 4096):
         r"""
         Applies a dispersion function to a time-activity curve (TAC) and returns the convolved TAC.
 
-        This method evaluates the specified dispersion function `disp_func` at supersampled time points.
-        It performs convolution (using :func:`scipy.signal.convolve`)of the supersampled TAC with
-        the dispersion function, and the result is sampled back at the original TAC time points
-        to form the new convolved TAC.
+        This method evaluates the specified dispersion function `disp_func` at supersampled time
+        points. It performs convolution (using :func:`scipy.signal.convolve`) of the supersampled
+        TAC with the dispersion function, and the result is sampled back at the original TAC time
+        points to form the new convolved TAC.
 
         .. note::
-            We perform the supersampling to ensure that the TACs are sampled evenly before performing
-            the convolution. Convolving non-evenly sampled arrays produces nonsense values.
+            We perform the supersampling to ensure that the TACs are sampled evenly before
+            performing the convolution. Convolving non-evenly sampled arrays produces nonsense
+            values.
 
         Args:
             tac (TimeActivityCurve): The original time-activity curve to be convolved.
-            disp_func (Callable[[np.ndarray, ...], np.ndarray]):
+            disp_func (Callable[..., np.ndarray]):
                 The dispersion function to be applied. This function must accept an array of
                 times as its first argument, followed by any additional arguments specified
                 in `disp_kwargs`.
@@ -541,8 +569,8 @@ class TimeActivityCurve:
                 Defaults to 4096.
 
         Returns:
-            TimeActivityCurve: A new `TimeActivityCurve` instance with the convolved activity values,
-            resampled at the original TAC time points.
+            TimeActivityCurve: A new `TimeActivityCurve` instance with the convolved activity
+            values, resampled at the original TAC time points.
 
         Example:
             .. code-block:: python
@@ -592,6 +620,12 @@ class TimeActivityCurve:
 
         return disp_tac.set_activity_non_negative()
 
+    @property
+    def contains_any_nan(self):
+        """Return True if TAC has any NaN activity values."""
+        any_nan = np.isnan(self.activity).any()
+        return any_nan
+
 def safe_load_tac(filename: str,
                   with_uncertainty: bool = False,
                   **kwargs) -> np.ndarray:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petpal
-Version: 0.5.8
+Version: 0.5.9
 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.8.dist-info → petpal-0.5.9.dist-info}/RECORD

@@ -1,6 +1,6 @@
 petpal/__init__.py,sha256=rYYNkBkSkHGE18JIZPeVK8YBP7Z9c4mpQfKN0cdS75k,318
 petpal/cli/__init__.py,sha256=RiQTAOhSeqw5BTVvdancX3JQj4CG8F9Qe4qWZR9nKio,434
-petpal/cli/cli_graphical_analysis.py,sha256=nGb0afMAigJgvbyEj5EXOCt6WNU35LNo3h3KLC8_f84,5529
+petpal/cli/cli_graphical_analysis.py,sha256=L-YhkKkjmf6WLaAt8GDt1VmXaJXOsjMrbVvPhiTViYM,5386
 petpal/cli/cli_graphical_plots.py,sha256=_2tlGtZ0hIVyEYtGviEzGZMNhFymUPg4ZvSVyMtT_dA,3211
 petpal/cli/cli_idif.py,sha256=6lh_kJHcGjlHDXZOvbiuHrNqpk5FovVV5_j7_dPHTHU,5145
 petpal/cli/cli_parametric_images.py,sha256=JBFb8QlxZoGOzqvCJPFuZ7czzGWntJP5ZcfeM5-QF4Y,7385
@@ -19,7 +19,7 @@ petpal/input_function/idif_necktangle.py,sha256=o5kyAqyT4C6o7zELY4EjyHrkJyX1BWcx
 petpal/input_function/pca_guided_idif.py,sha256=MPB59K5Z5oyIunIWFqFQts61z647xawLNkv8wICrKYM,44821
 petpal/kinetic_modeling/__init__.py,sha256=tW4yRH3TwaXPwKPqdkrbQmSk9hjrF1yRkV_C59PPboQ,382
 petpal/kinetic_modeling/fit_tac_with_rtms.py,sha256=HpK7VWVCCNoSQABY9i28vYpZsMRmvgs4vdcM_ZbdaYE,20971
-petpal/kinetic_modeling/graphical_analysis.py,sha256=a7IOwYnG3Wao2XTjFgsPK563txm7s4lpMbaqUMQ5wUQ,51003
+petpal/kinetic_modeling/graphical_analysis.py,sha256=e3ZXP8jA3ZgvC2T718-gukeBPlxCmOedCb2KlcGTUp8,51003
 petpal/kinetic_modeling/parametric_images.py,sha256=sXYracBFUtFyttO-6oiDAldnU8hPN6Y4vKOD1V-DnlE,47301
 petpal/kinetic_modeling/reference_tissue_models.py,sha256=FkLziIgtpA8tOL2gZJFg_nB8VPEBs40T7RsDAJ3nJ-A,39510
 petpal/kinetic_modeling/rtm_analysis.py,sha256=e3EuaHXml4PDALEczwyOPpnThINAGh41UKNlOQHAPqc,25945
@@ -42,9 +42,9 @@ petpal/preproc/image_operations_4d.py,sha256=IqzwxaWxoWC1gmK00uuHIwlhx8e_eQ44C6y
 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=qQDD9Z9p21DVUKokh_en2chOGP7F01wnDN156_74X8Q,19704
+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=BUy8ij45mmetenvWzODVwNIThDkYiEtY6gTAqI8sIak,25703
+petpal/preproc/segmentation_tools.py,sha256=Xi1ZnBs3sp23MHWPPOLjuXi6qp4-igwIPXFJ4B_Yzsk,27186
 petpal/preproc/standard_uptake_value.py,sha256=YJIt0fl3fwMLl0tRYHpPPprMTaN4Q5JjQ5dx_CQX1nI,7494
 petpal/preproc/symmetric_geometric_transfer_matrix.py,sha256=ELkr7Mo233to1Rwml5YJ-aBvmTSk3LHNSdRhnX0WBDw,17575
 petpal/utils/__init__.py,sha256=PlxBIKUtNvtSFnNZqz8myszOysaYzS8nSILMK4haVGg,412
@@ -58,15 +58,15 @@ petpal/utils/metadata.py,sha256=O9exRDlqAmPAEcO9v7dsqzkYcSVLgRA207owEvNXXJ8,6129
 petpal/utils/scan_timing.py,sha256=CYtYuFquAnOQ2QfjXdeLjWrBDPM_k4vBI9oHQdpmVZ0,13908
 petpal/utils/stats.py,sha256=paFdwVPIjlAi0wh5xU4x5WeydjKsEHuwzMLcDG_WzPc,6449
 petpal/utils/testing_utils.py,sha256=eMt1kklxK3rl8tm74I3yVNDotKh1CnYWLINDT7rzboM,9557
-petpal/utils/time_activity_curve.py,sha256=gX3PDYbeWblycvtvyiuFtnv1mBml_-93sIXKh2EmglM,39137
+petpal/utils/time_activity_curve.py,sha256=ZjirIVy6rxG1cEZhYzFhbi9FEixlgdBpVqcZXXz6c3U,40379
 petpal/utils/useful_functions.py,sha256=md2kTLbs45MhrjdMhvDYcbflPTRNPspRSIHiOeIxEqY,21361
 petpal/visualizations/__init__.py,sha256=bd0NHDVl6Z2BDhisEcob2iIcqfxUfgKJ4DEmlrXJRP4,205
 petpal/visualizations/graphical_plots.py,sha256=ZCKUeLX2TAQscuHjA4bzlFm1bACHIyCwDuNnjCakVWU,47297
 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.8.dist-info/METADATA,sha256=p2q6Rl726zTvyMW39Uw3j4jw0dXYKFhIDvkGG9nXqKk,2617
-petpal-0.5.8.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-petpal-0.5.8.dist-info/entry_points.txt,sha256=0SZmyXqBxKzQg2eerDA16n2BdUEXyixEm0_AUo2dFns,653
-petpal-0.5.8.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-petpal-0.5.8.dist-info/RECORD,,
+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,,