petpal 0.5.7__tar.gz → 0.5.9__tar.gz

{petpal-0.5.7 → petpal-0.5.9}/.gitignore

@@ -236,4 +236,7 @@ fabric.properties
 .idea/caches/build_file_checksums.ser
 
 # notebooks for testing new things
-debug_notebooks
+debug_notebooks
+
+# vscode
+.vscode

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petpal
-Version: 0.5.7
+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.7 → petpal-0.5.9}/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-0.5.7 → petpal-0.5.9}/petpal/preproc/decay_correction.py

@@ -129,21 +129,22 @@ def decay_correct(input_image_path: str,
     return corrected_image
 
 
-def calculate_frame_decay_factor(frame_reference_time: float,
-                                 half_life: float) -> float:
-    """Calculate decay factor for a single frame, given the frame reference time and half life.
+def calculate_frame_decay_factor(frame_reference_time: np.ndarray,
+                                 half_life: float) -> np.ndarray:
+    """Calculate decay correction factors for a scan given the frame reference time and half life.
     
     Important: 
         The frame reference time should be the time at which average activity occurs,
-        not simply the midpoint. See preproc.scan_timing.calculate_frame_reference_time for more info.
-        
+        not simply the midpoint. See
+        :meth:`~petpal.utils.scan_timing.calculate_frame_reference_time` for more info.
+
     Args: 
-        frame_reference_time (float): Time at which the average activity occurs for the frame.
+        frame_reference_time (np.ndarray): Time at which the average activity occurs for the frame.
         half_life (float): Radionuclide half life.
 
     Returns: 
-        float: Decay Correction Factor for the frame.     
+        np.ndarray: Decay Correction Factors for each frame in the scan.
     """
-    decay_constant = math.log(2)/half_life
-    frame_decay_factor = math.exp((decay_constant)*frame_reference_time)
-    return frame_decay_factor
+    decay_constant = np.log(2)/half_life
+    frame_decay_factor = np.exp((decay_constant)*frame_reference_time)
+    return frame_decay_factor

{petpal-0.5.7 → petpal-0.5.9}/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-0.5.7 → petpal-0.5.9}/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-0.5.7 → petpal-0.5.9}/petpal/utils/scan_timing.py

@@ -1,7 +1,7 @@
 """
 Module to handle timing information of PET scans.
 """
-import math
+from typing import Self
 from dataclasses import dataclass
 import numpy as np
 
@@ -82,8 +82,8 @@ class ScanTimingInfo:
 
     """
     duration: np.ndarray[float]
-    end: np.ndarray[float]
     start: np.ndarray[float]
+    end: np.ndarray[float]
     center: np.ndarray[float]
     decay: np.ndarray[float]
 
@@ -130,7 +130,7 @@ class ScanTimingInfo:
 
 
     @classmethod
-    def from_metadata(cls, metadata_dict: dict):
+    def from_metadata(cls, metadata_dict: dict) -> Self:
         r"""
         Extracts frame timing information and decay factors from a json metadata.
         Expects that the JSON metadata has ``FrameDuration`` and ``DecayFactor`` or
@@ -155,13 +155,13 @@ class ScanTimingInfo:
         """
         frm_dur = np.asarray(metadata_dict['FrameDuration'], float)
         try:
-            frm_ends = np.asarray(metadata_dict['FrameTimesEnd'], float)
+            frm_starts = np.asarray(metadata_dict['FrameTimesStart'], float)
         except KeyError:
-            frm_ends = np.cumsum(frm_dur)
+            frm_starts = np.cumsum(frm_dur)-frm_dur
         try:
-            frm_starts = np.asarray(metadata_dict['FrameTimesStart'], float)
+            frm_ends = np.asarray(metadata_dict['FrameTimesEnd'], float)
         except KeyError:
-            frm_starts = np.diff(frm_ends)
+            frm_ends = frm_starts+frm_dur
         try:
             decay = np.asarray(metadata_dict['DecayCorrectionFactor'], float)
         except KeyError:
@@ -178,7 +178,7 @@ class ScanTimingInfo:
                    decay=decay)
 
     @classmethod
-    def from_nifti(cls, image_path: str):
+    def from_nifti(cls, image_path: str) -> Self:
         r"""
         Extracts frame timing information and decay factors from a NIfTI image metadata.
         Expects that the JSON metadata file has ``FrameDuration`` and ``DecayFactor`` or
@@ -204,6 +204,49 @@ class ScanTimingInfo:
         _meta_data = load_metadata_for_nifti_with_same_filename(image_path=image_path)
         return cls.from_metadata(metadata_dict=_meta_data)
 
+    @classmethod
+    def from_start_end(cls,
+                       frame_starts: np.ndarray,
+                       frame_ends: np.ndarray,
+                       decay_correction_factor: np.ndarray | None=None) -> Self:
+        """Infer timing properties based on start and end time.
+        
+        Args:
+            frame_starts (np.ndarray): Start time of each frame.
+            frame_ends (np.ndarray): End time of each frame.
+            decay_correction_factor (np.ndarray | None): Decay correction factor, which can be
+                optionally provided based on the type of analysis being done. If None, frame decay
+                will be set to ones. Default None.
+
+        Returns:
+            scan_timing_info (ScanTimingInfo): ScanTimingInfo object with the correct start, end,
+                duration, midpoint, and (optionally) decay correction for each frame.
+
+        Raises:
+            ValueError: If frame_starts, frame_ends, and decay_correction_factor (if provided) are
+                not of identical shape.
+
+        """
+        if frame_starts.shape != frame_ends.shape:
+            raise ValueError("frame_ends must have the same shape as frame_starts")
+
+        frame_duration = frame_ends - frame_starts
+        frame_midpoint = frame_starts + frame_duration / 2
+        frame_decay = np.ones_like(frame_starts)
+
+        if decay_correction_factor is None:
+            frame_decay = np.ones_like(frame_starts, dtype=float)
+        else:
+            frame_decay = np.asarray(decay_correction_factor, dtype=float)
+            if frame_decay.shape != frame_starts.shape:
+                raise ValueError("decay_correction_factor must have the same shape as frame_starts")
+
+        return cls(duration=frame_duration,
+                   start=frame_starts,
+                   end=frame_ends,
+                   center=frame_midpoint,
+                   decay=frame_decay)
+
 
 def get_window_index_pairs_from_durations(frame_durations: np.ndarray, w_size: float):
     r"""
@@ -263,25 +306,29 @@ def get_window_index_pairs_for_image(image_path: str, w_size: float):
                                                  w_size=w_size)
 
 
-def calculate_frame_reference_time(frame_duration: float,
-                                   frame_start: float,
-                                   half_life: float) -> float:
+def calculate_frame_reference_time(frame_duration: np.ndarray,
+                                   frame_start: np.ndarray,
+                                   half_life: float) -> np.ndarray:
     r"""Compute frame reference time as the time at which the average activity occurs.
     
-    Equation comes from the `DICOM standard documentation <https://dicom.innolitics.com/ciods/positron-emission-tomography-image/pet-image/00541300>`_
+    Equation comes from the `DICOM standard documentation
+    <https://dicom.innolitics.com/ciods/positron-emission-tomography-image/pet-image/00541300>`_
 
     :math:`T_{ave}=\frac{1}{\lambda}ln\frac{\lambda T}{1-e^{-\lambda T}}`
 
-    where lambda is the decay constant, :math:`\frac{ln2}{T_{1/2}}`, :math:`T_{1/2}` is the half life, and :math:`T` is the frame duration.
+    where lambda is the decay constant, :math:`\frac{ln2}{T_{1/2}}`, :math:`T_{1/2}` is the half
+    life, and :math:`T` is the frame duration.
 
     Args:
-        frame_duration (float): Frame Duration in seconds
-        frame_start (float): Start time of frame relative to scan start, in seconds
-        half_life (float): Radionuclide half life
+        frame_duration (np.ndarray): Duration of each frame in seconds.
+        frame_start (np.ndarray): Start time of each frame relative to scan start, in seconds.
+        half_life (float): Radionuclide half life in seconds.
 
     Returns: 
-        float: Frame reference time
+        np.ndarray: Frame reference time for each frame in the scan in seconds.
     """
-    decay_constant = math.log(2)/half_life
-    frame_reference_time = frame_start + math.log((decay_constant*frame_duration)/(1-math.exp(-decay_constant*frame_duration)))/decay_constant
+    decay_constant = np.log(2)/half_life
+    decay_over_frame = decay_constant*frame_duration
+    reference_time_delay = np.log((decay_over_frame)/(1-np.exp(-decay_over_frame)))/decay_constant
+    frame_reference_time = frame_start + reference_time_delay
     return frame_reference_time

{petpal-0.5.7 → petpal-0.5.9}/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.7 → petpal-0.5.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "petpal"
-version = "0.5.7"
+version = "0.5.9"
 description = "PET-PAL (Positron Emission Tomography Processing and Analysis Library)"
 authors = [
     {name = "Noah Goldman", email = "noahg@wustl.edu"},

petpal-0.5.9/tests/test_graphical_analysis.py

@@ -0,0 +1,90 @@
+import os
+import warnings
+import pytest
+import pandas as pd
+
+from petpal.utils.image_io import flatten_metadata
+import petpal.kinetic_modeling.graphical_analysis as ga
+
+def _make_instance(rsquared):
+    inst = ga.MultiTACGraphicalAnalysis.__new__(ga.MultiTACGraphicalAnalysis)
+    inst.analysis_props = [{'RSquared': rsquared}]
+    inst.output_directory = "/tmp"
+    inst.output_filename_prefix = "prefix"
+    inst.method = "patlak"
+    inst.inferred_seg_labels = ["roi1", "roi2"]
+    return inst
+
+
+def test_save_analysis_raises_if_run_not_called():
+    inst = _make_instance(rsquared=None)
+    with pytest.raises(RuntimeError):
+        inst.save_analysis()
+
+def test_save_analysis_calls_tsv_and_json(monkeypatch):
+    inst = _make_instance(rsquared=0.95)
+    calls = {"tsv": 0, "json": 0}
+
+    def km_multifit_analysis_to_tsv_without_save_file(analysis_props: list[dict],
+                                    output_directory: str,
+                                    output_filename_prefix: str,
+                                    method: str,
+                                    inferred_seg_labels: list[str]):
+        filename = f'{output_filename_prefix}_desc-{method}_fitprops.tsv'
+        filepath = os.path.join(output_directory, filename)
+        fit_table = pd.DataFrame()
+        for seg_name, fit_props in zip(inferred_seg_labels, analysis_props):
+            tmp_table = pd.DataFrame(flatten_metadata(fit_props),index=[seg_name])
+            fit_table = pd.concat([fit_table,tmp_table])
+        calls["tsv"] += 1
+        assert isinstance(analysis_props, list)
+        assert isinstance(output_directory, str)
+        assert isinstance(output_filename_prefix, str)
+        assert isinstance(method, str)
+        assert isinstance(inferred_seg_labels, list)
+
+    def km_multifit_analysis_to_jsons_without_save_file(analysis_props: list[dict],
+                                    output_directory: str,
+                                    output_filename_prefix: str,
+                                    method: str,
+                                    inferred_seg_labels: list[str]):
+        for seg_name, fit_props in zip(inferred_seg_labels, analysis_props):
+            filename = [output_filename_prefix,
+                        f'desc-{method}',
+                        f'seg-{seg_name}',
+                        'fitprops.json']
+            filename = '_'.join(filename)
+            filepath = os.path.join(output_directory, filename)
+        calls["json"] += 1
+        assert isinstance(analysis_props, list)
+        assert isinstance(output_directory, str)
+        assert isinstance(output_filename_prefix, str)
+        assert isinstance(method, str)
+        assert isinstance(inferred_seg_labels, list)
+
+    monkeypatch.setattr(ga, "km_multifit_analysis_to_tsv", km_multifit_analysis_to_tsv_without_save_file)
+    monkeypatch.setattr(ga, "km_multifit_analysis_to_jsons", km_multifit_analysis_to_jsons_without_save_file)
+
+    # Default behavior: TSV only
+    calls["tsv"] = calls["json"] = 0
+    inst.save_analysis(output_as_tsv=True, output_as_json=False)
+    assert calls["tsv"] == 1 and calls["json"] == 0
+
+    # JSON only
+    calls["tsv"] = calls["json"] = 0
+    inst.save_analysis(output_as_tsv=False, output_as_json=True)
+    assert calls["tsv"] == 0 and calls["json"] == 1
+
+    # Both
+    calls["tsv"] = calls["json"] = 0
+    inst.save_analysis(output_as_tsv=True, output_as_json=True)
+    assert calls["tsv"] == 1 and calls["json"] == 1
+
+def test_save_analysis_warns_when_no_output_requested(monkeypatch):
+    inst = _make_instance(rsquared=0.5)
+    # prevent actual functions being called if mistakenly invoked
+    monkeypatch.setattr(ga, "km_multifit_analysis_to_tsv", lambda *a, **k: (_ for _ in ()).throw(AssertionError("should not be called")))
+    monkeypatch.setattr(ga, "km_multifit_analysis_to_jsons", lambda *a, **k: (_ for _ in ()).throw(AssertionError("should not be called")))
+
+    with pytest.warns(UserWarning):
+        inst.save_analysis(output_as_tsv=False, output_as_json=False)