petpal 0.6.0__tar.gz → 0.6.1__tar.gz

{petpal-0.6.0 → petpal-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petpal
-Version: 0.6.0
+Version: 0.6.1
 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.6.0 → petpal-0.6.1}/petpal/__init__.py

@@ -5,6 +5,7 @@ from . import utils
 from . import visualizations
 from . import pipelines
 from . import meta
+from . import io
 
 def main():
     print("PET-PAL (Positron Emission Tomography Processing and Analysis Library)")

{petpal-0.6.0 → petpal-0.6.1}/petpal/cli/cli_preproc.py

@@ -321,12 +321,11 @@ def _generate_args() -> argparse.ArgumentParser:
                                                help='Windowed motion correction for 4D PET'
                                                     ' using ANTS')
     _add_common_args(parser_window_moco)
-    parser_window_moco.add_argument('-t',
-                                    '--motion-target',
-                                    default='weighted_series_sum',
-                                    type=str,
-                                    help="Motion target option. Can be an image path , "
-                                         "'weighted_series_sum' or 'mean_image'")
+    parser_window_moco.add_argument('--motion-target', default=None, nargs='+',
+                            help="Motion target option. Can be an image path, "
+                                 "'weighted_series_sum' or a tuple "
+                                 "(i.e. '--motion-target 0 600' for first ten minutes).",
+                            required=True)
     parser_window_moco.add_argument('-w', '--window-size', default=60.0, type=float,
                                     help="Window size in seconds.",)
     xfm_types = ['QuickRigid', 'Rigid', 'DenseRigid', 'Affine', 'AffineFast']
@@ -460,11 +459,11 @@ def main():
                                        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)
+            motion_corrector = motion_corr.MotionCorrect()
+            motion_corrector(input_image_path=args.input_img,
+                             output_image_path=args.out_img,
+                             motion_target_option=motion_target,
+                             window_duration=args.window_size)
         case 'rescale_image':
             input_img = ants.image_read(filename=args.input_img)
             out_img = image_operations_4d.rescale_image(input_image=input_img,

petpal-0.6.1/petpal/io/__init__.py

@@ -0,0 +1,9 @@
+from . import table
+from . import image
+
+def main():
+    print("PETPAL - Load and Save Module")
+
+
+if __name__ == "__main__":
+    main()

petpal-0.6.1/petpal/io/image.py

@@ -0,0 +1,39 @@
+"""
+Module for loading and saving images
+"""
+from typing import Optional
+from collections.abc import Callable
+import ants
+
+
+class ImageLoader:
+    """Class for reading image files, with extensions such as Nifti or MGZ.
+
+    See also: :py:docs:`~ants.image_read`.
+
+    Example:
+
+        .. code-block:: python
+
+            from petpal.io.image import ImageLoader
+
+            image_loader = ImageLoader()
+            my_img = image_loader.load('/path/to/img.nii.gz')
+
+    :ivar _loader: Function that loads an image file as an ants.ANTsImage object.
+    """
+    def __init__(self, loader: Optional[Callable[[str], ants.ANTsImage]] = None):
+        self._loader = loader or ants.image_read
+
+    def load(self, filename: str) -> ants.ANTsImage:
+        """Public read API that delegates to the configured reader.
+        
+        Args:
+            filename (str): Path to file that will be loaded as ANTsImage.
+    
+        Returns:
+            img (ants.ANTsImage): Image object loaded into Python."""
+        return self._loader(filename)
+
+    def __call__(self, filename: str) -> ants.ANTsImage:
+        return self.load(filename=filename)

petpal-0.6.1/petpal/io/table.py

@@ -0,0 +1,94 @@
+"""
+Module for reading and writing tables as TSV and CSV files.
+"""
+import os
+import tempfile
+from typing import Optional
+from collections.abc import Callable
+from pathlib import Path
+import dataclasses
+import pandas as pd
+
+
+def get_tabular_separator(ext: str) -> str:
+    """Get the separator corresponding to a given tabular data filetype.
+    
+    '.csv' will return ',' while '.tsv' and '.txt' will return '\t'. Any other input will raise a
+    ValueError.
+    
+    Args:
+        ext (str): Extension to get matching separator for.
+    
+    Returns:
+        sep (str): Separator matched from extension.
+    
+    Raises:
+        ValueError: If extension is not .csv or .tsv.
+    """
+    matching_separators = {'.csv': ',', '.tsv': '\t', '.txt': '\t'}
+    try:
+        return matching_separators[ext]
+    except ValueError as exc:
+        error_msg = f"Only accepted extensions are {matching_separators.keys()}. Got {ext}."
+        raise ValueError(error_msg) from exc
+
+
+@dataclasses.dataclass
+class TableSaver:
+    """
+    Class for saving Pandas Database objects as CSV or TSV files based on a provided path.
+
+    - Default behavior writes atomically (write temp file + os.replace) to avoid partial files.
+    - Accepts an injectable writer callable for testing or alternative persistence backends.
+
+    Example:
+
+        .. code-block:: python
+
+            import pandas as pd
+            from petpal.io.table import TableSaver
+
+            table_saver = TableSaver()
+            my_data = pd.DataFrame(data={'time': [0, 1, 2], 'value': [1, 4, 9]})
+            
+            # when file extension is .csv, uses commas to separate values
+            table_saver.save(my_data, 'table.csv')
+
+            # when file extension is .tsv or .txt, uses tabs to separate values
+            table_saver.save(my_data, 'table.txt')
+
+    :ivar _saver: Injectable tabular data saving function that saves a dataframe to a file.
+    """
+    def __init__(self, saver: Optional[Callable[[pd.DataFrame, str], None]] = None):
+        self._saver = saver or self._atomic_save
+
+    def _atomic_save(self, df: pd.DataFrame, path: str):
+        """Saves the data from a Pandas DataFrame object as a tabular file, such as CSV or TSV.
+        
+        Args:
+            df (pd.DataFrame): Pandas DataFrame with data to be saved.
+            path (str): Path to file where data is saved.
+        """
+        dirpath = os.path.dirname(os.path.abspath(path)) or "."
+        suffix = Path(path).suffix
+        sep = get_tabular_separator(ext=suffix)
+        fd, tmp_path = tempfile.mkstemp(prefix="tmp_petpal_", dir=dirpath, suffix=suffix)
+        os.close(fd)
+        try:
+            df.to_csv(tmp_path, sep=sep)
+            os.replace(tmp_path, path)
+        finally:
+            if os.path.exists(tmp_path):
+                try:
+                    os.remove(tmp_path)
+                except OSError:
+                    pass
+
+    def save(self, df: pd.DataFrame, path: str) -> None:
+        """API that applies the table saving function assigned to `self._saver`.
+        
+        Args:
+            df (pd.DataFrame): Pandas DataFrame with data to be saved.
+            path (str): Path to file where data is saved.
+        """
+        self._saver(df, path)

{petpal-0.6.0 → petpal-0.6.1}/petpal/pipelines/preproc_steps.py

@@ -642,7 +642,7 @@ class ImageToImageStep(FunctionBasedStep):
         """
         defaults = dict(name=name, function=windowed_motion_corr_to_target,
                         input_image_path='', output_image_path='',
-                        motion_target_option='weighted_series_sum', w_size=60.0,
+                        motion_target_option='weighted_series_sum', window_duration=60.0,
                         verbose=verbose)
         override_dict = defaults | overrides
         try:

{petpal-0.6.0 → petpal-0.6.1}/petpal/preproc/motion_corr.py

@@ -4,17 +4,23 @@ Provides methods to motion correct 4D PET data. Includes method
 4D input data to optimize contrast when computing motion correction or
 registration.
 """
+from typing import Optional
 import ants
 import numpy as np
+import pandas as pd
+from scipy.spatial.transform import Rotation
 
 from petpal.utils.useful_functions import gen_nd_image_based_on_image_list
-
-
 from .motion_target import determine_motion_target
 from ..utils import image_io
-from ..utils.scan_timing import ScanTimingInfo, get_window_index_pairs_for_image
-from ..utils.useful_functions import weighted_series_sum_over_window_indecies
-from ..utils.image_io import get_half_life_from_nifti
+from ..utils.scan_timing import (ScanTimingInfo,
+                                 get_window_index_pairs_from_durations,
+                                 get_window_index_pairs_for_image)
+from ..utils.useful_functions import (weighted_series_sum_over_window_indices,
+                                      coerce_outpath_extension)
+from ..utils.image_io import get_half_life_from_nifti, safe_copy_meta
+from ..io.table import TableSaver
+from ..io.image import ImageLoader
 
 
 def motion_corr(input_image_path: str,
@@ -425,11 +431,230 @@ def motion_corr_frames_above_mean_value_to_t1(input_image_path: str,
                                  type_of_transform=type_of_transform,
                                  transform_metric=transform_metric)
 
+class MotionCorrect:
+    """Run windowed motion correction on an image and save the result"""
+    def __init__(self,
+                 image_loader: Optional[ImageLoader] = None,
+                 table_saver: Optional[TableSaver] = None):
+        self.image_loader = image_loader or ImageLoader()
+        self.table_saver = table_saver or TableSaver()
+        self.input_img = None
+        self.target_img = None
+        self.scan_timing = None
+        self.half_life = None
+        self.reg_kwargs = self.default_reg_kwargs
+
+    @property
+    def default_reg_kwargs(self) -> dict:
+        """Default registration arguments passed on to :py:func:`~ants.registration`."""
+        reg_kwargs_default = {'aff_metric'               : 'mattes',
+                              'write_composite_transform': True,
+                              'interpolator'             : 'linear',
+                              'type_of_transform'        : 'DenseRigid'}
+        return reg_kwargs_default
+
+    def set_reg_kwargs(self, **reg_kwargs):
+        """Modify the registration arguments passed on to :py:func:`~ants.registration`."""
+        self.reg_kwargs.update(**reg_kwargs)
+
+    def get_input_scan_properties(self, input_image_path: str):
+        """Load input image and get half life and scan timing."""
+        self.input_img = self.image_loader.load(filename=input_image_path)
+        self.half_life = get_half_life_from_nifti(image_path=input_image_path)
+        self.scan_timing = ScanTimingInfo.from_nifti(image_path=input_image_path)
+
+    def get_target_img(self, input_image_path: str, motion_target_option: str | tuple):
+        """Get the motion target and load it as an image."""
+        motion_target_path = determine_motion_target(motion_target_option=motion_target_option,
+                                                     input_image_path=input_image_path)
+        self.target_img = self.image_loader.load(filename=motion_target_path)
+
+    def window_index_pairs(self, window_duration: float=300):
+        """The pair of indices corresponding to each window in the image."""
+        return get_window_index_pairs_from_durations(frame_durations=self.scan_timing.duration,
+                                                     window_duration=window_duration)
+
+    def window_target_img(self, start_index: int, end_index: int):
+        """Calculates the sum over frames in the target image within the provided time window."""
+        return weighted_series_sum_over_window_indices(input_image_4d=self.input_img,
+                                                        output_image_path=None,
+                                                        window_start_id=start_index,
+                                                        window_end_id=end_index,
+                                                        half_life=self.half_life,
+                                                        image_frame_info=self.scan_timing)
+
+    @staticmethod
+    def ants_xfm_to_rigid_pars(ants_xfm: ants.ANTsTransform):
+        """Convert an ants transform object to six parameters (3 translation, 3 rotation) and the
+        center reference point."""
+        xfm_in = np.reshape(ants_xfm.parameters,(4,3))
+        rot_matrix = xfm_in[:3,:]
+        translate_matrix = xfm_in[3,:]
+
+        scipy_rotation = Rotation.from_matrix(rot_matrix)
+        rot_pars = -scipy_rotation.as_euler('xyz',degrees=True)
+
+        xfm_out = list(rot_pars)+list(translate_matrix)+list(ants_xfm.fixed_parameters)
+        return xfm_out
+
+    def run_motion_correct(self, window_duration: float=300):
+        """Run motion correction on the input image to the target image."""
+        moco_img_stack = []
+        window_xfm_stack = []
+        input_img_list = ants.ndimage_to_list(self.input_img)
+        for _, (st_id, end_id) in enumerate(zip(*self.window_index_pairs(window_duration=window_duration))):
+            window_target_img = self.window_target_img(start_index=st_id, end_index=end_id)
+            window_registration = ants.registration(fixed=self.target_img,
+                                                    moving=window_target_img,
+                                                    **self.reg_kwargs)
+            window_xfm = ants.read_transform(window_registration['fwdtransforms'])
+            window_xfm_stack.append(self.ants_xfm_to_rigid_pars(window_xfm))
+            for frm_id in range(st_id, end_id):
+                moco_img_stack.append(ants.apply_transforms(fixed=self.target_img,
+                                      moving=input_img_list[frm_id],
+                                      transformlist=window_registration['fwdtransforms']))
+        moco_img = gen_timeseries_from_image_list(moco_img_stack)
+        return moco_img, np.asarray(window_xfm_stack)
+
+    def save_xfm_parameters(self, window_xfms: np.ndarray, filename: str):
+        """Save window transform parameters as a table.
+
+        Args:
+            window_xfms (np.ndarray): Rigid transform parameters ordered as rotation, translation,
+                centerpoint, then X, Y, Z axis, totalling 9 parameters for each window.
+            filename (str): Path to where table will be saved, including extension.
+
+        Raises:
+            ValueError: If transform type does not containt 'Rigid'. Saving transform parameters is
+                currently only available for rigid transforms."""
+        if 'Rigid' not in self.reg_kwargs['type_of_transform']:
+            raise ValueError("Saving transform parameters is only available for rigid "
+                             "registrations. Current transform type: "
+                             f"{self.reg_kwargs['type_of_transform']}")
+        xfm_columns = ['rot_x',
+                       'rot_y',
+                       'rot_z',
+                       'tra_x',
+                       'tra_y',
+                       'tra_z',
+                       'cen_x',
+                       'cen_y',
+                       'cen_z']
+        xfms_df = pd.DataFrame(data=window_xfms,
+                               columns=xfm_columns)
+        xfms_df.index.name = 'window'
+        csv_filename = coerce_outpath_extension(path=filename, ext='.csv')
+        self.table_saver.save(xfms_df,csv_filename)
+
+    def __call__(self, input_image_path: str,
+                 output_image_path: str,
+                 motion_target_option: str | tuple,
+                 window_duration: float = 300,
+                 copy_metadata: bool = True,
+                 save_xfm: bool = True,
+                 **reg_kwargs):
+        """Motion correct a dynamic PET image.
+
+        Divides image into segments of duration in seconds `window_duration` and register each frame
+        to a target image, using the same transformation on for every frame in each window.
+
+        Args:
+            input_image_path (str): Path to dynamic PET image.
+            output_image_path (str): Path to which motion corrected image is saved.
+            motion_target_option (str | tuple): Path to motion target image, or specify time window
+                such as (0,600) or preset option such as 'mean_image'. See
+                :py:func:`~petpal.preproc.motion_target.determine_motion_target`.
+            window_duration (float): Duration of each window in seconds. Default 300.
+            copy_metadata (bool): Copies metadata info from input image to output image. Default
+                True.
+            save_xfm (bool): Saves motion correction transform parameters for translation,
+                rotation, and rotation center point. Only compatible with rigid transforms. Default
+                True.
+        """
+        self.get_input_scan_properties(input_image_path=input_image_path)
+        self.get_target_img(input_image_path=input_image_path,
+                            motion_target_option=motion_target_option)
+
+        self.set_reg_kwargs(**reg_kwargs)
+
+        moco_img, window_xfms = self.run_motion_correct(window_duration=window_duration)
+
+        if save_xfm:
+            self.save_xfm_parameters(window_xfms=window_xfms, filename=output_image_path)
+        ants.image_write(image=moco_img, filename=output_image_path)
+        if copy_metadata:
+            safe_copy_meta(input_image_path=input_image_path, out_image_path=output_image_path)
+
+        return moco_img
+
+def gen_timeseries_from_image_list(image_list: list[ants.core.ANTsImage]) -> ants.core.ANTsImage:
+    r"""
+    Takes a list of ANTs ndimages, and generates a 4D ndimage. Undoes :func:`ants.ndimage_to_list`
+    so that we take a list of 3D images and generates a 4D image.
+
+    Args:
+        image_list (list[ants.core.ANTsImage]): A list of ndimages.
+
+    Returns:
+        ants.core.ANTsImage: 4D ndimage.
+    """
+    tmp_image = gen_nd_image_based_on_image_list(image_list)
+    return ants.list_to_ndimage(tmp_image, image_list)
+
+
+def _get_list_of_frames_above_total_mean(image_4d_path: str,
+                                         scale_factor: float = 1.0):
+    """
+    Get the frame indices where the frame mean is higher than the total mean of a 4D image.
+
+    This function calculates the mean voxel value of each frame in a 4D image and returns the
+        indices of the frames whose mean voxel value is greater than or equal to the mean voxel
+        value of the entire image, optionally scaled by a provided factor.
+
+    Args:
+        image_4d_path (str): Path to the input 4D PET image file.
+        scale_factor (float, optional): Scale factor applied to the mean voxel value of the entire
+            image for comparison. Must be greater than 0. Default is 1.0.
+
+    Returns:
+        list: A list of frame indices where the frame mean voxel value is greater than or equal to
+            the scaled total mean voxel value.
+
+    Example:
+
+        .. code-block:: python
+
+            from petpal.preproc.motion_corr import _get_list_of_frames_above_total_mean
+
+            frame_ids = _get_list_of_frames_above_total_mean(image_4d_path='/path/to/image.nii.gz',
+                                                                                  scale_factor=1.2)
+
+            print(frame_ids)  # Output: [0, 3, 5, ...]
+
+    Notes:
+        - The :func:`ants.image_read` from ANTsPy is used to read the 4D image into memory.
+        - The mean voxel value of the entire image is scaled by `scale_factor` for comparison with
+            individual frame means.
+        - The function uses the :func:`ants.ndimage_to_list` method from ANTsPy to convert the 4D
+            image into a list of 3D frames.
+
+    """
+    assert scale_factor > 0
+    image = ants.image_read(image_4d_path)
+    total_mean = scale_factor * image.mean()
+
+    frames_list = []
+    for frame_id, a_frame in enumerate(image.ndimage_to_list()):
+        if a_frame.mean() >= total_mean:
+            frames_list.append(frame_id)
+
+    return frames_list
+
 
 def windowed_motion_corr_to_target(input_image_path: str,
                                    out_image_path: str | None,
                                    motion_target_option: str | tuple,
-                                   w_size: float,
+                                   window_duration: float,
                                    type_of_transform: str = 'QuickRigid',
                                    interpolator: str = 'linear',
                                    copy_metadata: bool = True,
@@ -445,6 +670,10 @@ def windowed_motion_corr_to_target(input_image_path: str,
         The motion-target will determine the space of the output image. If we provide a T1 image
         as the `motion_target_option`, the output image will be in T1-space.
 
+    Note:
+        This function is deprecated. Use :py:func:`~petpal.preproc.motion_corr.MotionCorrect`
+        instead.
+
     Args:
         input_image_path (str): Path to the input 4D PET image file.
         out_image_path (str | None): Path to save the resulting motion-corrected image. If
@@ -452,7 +681,7 @@ def windowed_motion_corr_to_target(input_image_path: str,
         motion_target_option (str | tuple): Option to determine the motion target. This can
             be a path to a specific image file, a tuple of frame indices to generate a target, or
             specific options recognized by :func:`determine_motion_target`.
-        w_size (float): Window size in seconds for dividing the image into time sections.
+        window_duration (float): Window size in seconds for dividing the image into time sections.
         type_of_transform (str): Type of transformation to use in registration (default: 'QuickRigid').
         interpolator (str): Interpolation method for the transformation (default: 'linear').
         **kwargs: Additional arguments passed to :func:`ants.registration`.
@@ -462,7 +691,7 @@ def windowed_motion_corr_to_target(input_image_path: str,
 
     Workflow:
         1. Reads the input 4D image and splits it into individual frames.
-        2. Computes index windows based on the specified window size (`w_size`).
+        2. Computes index windows based on the specified window size (`window_duration`).
         3. Extracts necessary frame timing information and the tracer's half-life.
         4. For each window:
             - Calculates a weighted sum image for the window.
@@ -477,7 +706,7 @@ def windowed_motion_corr_to_target(input_image_path: str,
     """
     input_image = ants.image_read(filename=input_image_path)
     input_image_list = ants.ndimage_to_list(input_image)
-    window_idx_pairs = get_window_index_pairs_for_image(image_path=input_image_path, w_size=w_size)
+    window_idx_pairs = get_window_index_pairs_for_image(image_path=input_image_path, window_duration=window_duration)
     half_life = get_half_life_from_nifti(image_path=input_image_path)
     frame_timing_info = ScanTimingInfo.from_nifti(image_path=input_image_path)
 
@@ -490,13 +719,13 @@ def windowed_motion_corr_to_target(input_image_path: str,
     reg_kwargs = {**reg_kwargs_default, **kwargs}
 
     out_image = []
-    for win_id, (st_id, end_id) in enumerate(zip(*window_idx_pairs)):
-        window_tgt_image = weighted_series_sum_over_window_indecies(input_image_4d=input_image,
-                                                                    output_image_path=None,
-                                                                    window_start_id=st_id,
-                                                                    window_end_id=end_id,
-                                                                    half_life=half_life,
-                                                                    image_frame_info=frame_timing_info)
+    for _, (st_id, end_id) in enumerate(zip(*window_idx_pairs)):
+        window_tgt_image = weighted_series_sum_over_window_indices(input_image_4d=input_image,
+                                                                   output_image_path=None,
+                                                                   window_start_id=st_id,
+                                                                   window_end_id=end_id,
+                                                                   half_life=half_life,
+                                                                   image_frame_info=frame_timing_info)
         window_registration = ants.registration(fixed=target_image,
                                                 moving=window_tgt_image,
                                                 type_of_transform=type_of_transform,
@@ -516,66 +745,3 @@ def windowed_motion_corr_to_target(input_image_path: str,
         image_io.safe_copy_meta(input_image_path=input_image_path,
                                 out_image_path=out_image_path)
     return out_image
-
-def gen_timeseries_from_image_list(image_list: list[ants.core.ANTsImage]) -> ants.core.ANTsImage:
-    r"""
-    Takes a list of ANTs ndimages, and generates a 4D ndimage. Undoes :func:`ants.ndimage_to_list`
-    so that we take a list of 3D images and generates a 4D image.
-
-    Args:
-        image_list (list[ants.core.ANTsImage]): A list of ndimages.
-
-    Returns:
-        ants.core.ANTsImage: 4D ndimage.
-    """
-    tmp_image = gen_nd_image_based_on_image_list(image_list)
-    return ants.list_to_ndimage(tmp_image, image_list)
-
-
-def _get_list_of_frames_above_total_mean(image_4d_path: str,
-                                         scale_factor: float = 1.0):
-    """
-    Get the frame indices where the frame mean is higher than the total mean of a 4D image.
-
-    This function calculates the mean voxel value of each frame in a 4D image and returns the
-        indices of the frames whose mean voxel value is greater than or equal to the mean voxel
-        value of the entire image, optionally scaled by a provided factor.
-
-    Args:
-        image_4d_path (str): Path to the input 4D PET image file.
-        scale_factor (float, optional): Scale factor applied to the mean voxel value of the entire
-            image for comparison. Must be greater than 0. Default is 1.0.
-
-    Returns:
-        list: A list of frame indices where the frame mean voxel value is greater than or equal to
-            the scaled total mean voxel value.
-
-    Example:
-
-        .. code-block:: python
-
-            from petpal.preproc.motion_corr import _get_list_of_frames_above_total_mean
-
-            frame_ids = _get_list_of_frames_above_total_mean(image_4d_path='/path/to/image.nii.gz',
-                                                                                  scale_factor=1.2)
-
-            print(frame_ids)  # Output: [0, 3, 5, ...]
-
-    Notes:
-        - The :func:`ants.image_read` from ANTsPy is used to read the 4D image into memory.
-        - The mean voxel value of the entire image is scaled by `scale_factor` for comparison with
-            individual frame means.
-        - The function uses the :func:`ants.ndimage_to_list` method from ANTsPy to convert the 4D
-            image into a list of 3D frames.
-
-    """
-    assert scale_factor > 0
-    image = ants.image_read(image_4d_path)
-    total_mean = scale_factor * image.mean()
-
-    frames_list = []
-    for frame_id, a_frame in enumerate(image.ndimage_to_list()):
-        if a_frame.mean() >= total_mean:
-            frames_list.append(frame_id)
-
-    return frames_list