petpal 0.5.7__tar.gz → 0.5.8__tar.gz

{petpal-0.5.7 → petpal-0.5.8}/.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.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petpal
-Version: 0.5.7
+Version: 0.5.8
 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.8}/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.8}/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.8}/pyproject.toml

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

petpal-0.5.8/tests/test_register.py

@@ -0,0 +1,82 @@
+import pytest
+from types import SimpleNamespace
+from petpal.preproc.register import register_pet
+
+import petpal.preproc.register as reg_mod
+
+class DummyImage:
+    def __init__(self, dimension, name=None):
+        self.dimension = dimension
+        self.name = name
+
+def make_mocks(monkeypatch, pet_dim, recorded):
+    # Mock determine_motion_target to return a path string
+    monkeypatch.setattr(reg_mod, "determine_motion_target", lambda motion_target_option, input_image_path: "motion_target.nii")
+    # Mock ants.image_read to return DummyImage instances depending on path
+    def mock_image_read(path):
+        if path == "motion_target.nii":
+            img = DummyImage(dimension=3, name="motion_target")
+        elif path == "mri.nii":
+            img = DummyImage(dimension=3, name="mri")
+        elif path == "pet.nii":
+            img = DummyImage(dimension=pet_dim, name="pet")
+        else:
+            img = DummyImage(dimension=0, name=path)
+        recorded['image_reads'].append((path, img))
+        return img
+    monkeypatch.setattr(reg_mod.ants, "image_read", mock_image_read)
+    # Mock ants.registration to record args and return transforms
+    def mock_registration(*, moving, fixed, type_of_transform, write_composite_transform=True, **kwargs):
+        recorded['registration_calls'].append({
+            'moving': moving, 'fixed': fixed, 'type_of_transform': type_of_transform, 'kwargs': kwargs
+        })
+        return {'fwdtransforms': ['/fake/xfm']}
+    monkeypatch.setattr(reg_mod.ants, "registration", mock_registration)
+    # Mock ants.apply_transforms to record imagetype and return a dummy transformed image
+    def mock_apply_transforms(*, moving, fixed, transformlist, interpolator=None, imagetype=None, **kwargs):
+        recorded['apply_calls'].append({'moving': moving, 'fixed': fixed, 'transformlist': transformlist, 'imagetype': imagetype})
+        return SimpleNamespace(name="transformed_image", imagetype=imagetype)
+    monkeypatch.setattr(reg_mod.ants, "apply_transforms", mock_apply_transforms)
+    # Mock ants.image_write to record output path
+    monkeypatch.setattr(reg_mod.ants, "image_write", lambda img, out: recorded['written'].append((img, out)))
+    # Mock image_io.safe_copy_meta
+    monkeypatch.setattr(reg_mod.image_io, "safe_copy_meta", lambda input_image_path, out_image_path: recorded['meta_copied'].append((input_image_path, out_image_path)))
+
+@pytest.mark.parametrize("pet_dim, expected_imagetype", [
+    (4, 3),
+    (3, 0),
+])
+def test_register_pet_sets_imagetype_and_writes(monkeypatch, capsys, pet_dim, expected_imagetype):
+    recorded = {'image_reads': [], 'registration_calls': [], 'apply_calls': [], 'written': [], 'meta_copied': []}
+    make_mocks(monkeypatch, pet_dim=pet_dim, recorded=recorded)
+
+    # Call function under test
+    register_pet(input_reg_image_path="pet.nii",
+                 out_image_path="out.nii",
+                 reference_image_path="mri.nii",
+                 motion_target_option="some_option",
+                 verbose=True,
+                 type_of_transform="DenseRigid")
+
+    # Check registration was called with motion target as moving and mri as fixed
+    assert recorded['registration_calls'], "ants.registration was not called"
+    reg_call = recorded['registration_calls'][-1]
+    assert getattr(reg_call['moving'], "name", None) == "motion_target"
+    assert getattr(reg_call['fixed'], "name", None) == "mri"
+    assert reg_call['type_of_transform'] == "DenseRigid"
+
+    # Check apply_transforms was called with correct imagetype based on input dimension
+    assert recorded['apply_calls'], "ants.apply_transforms was not called"
+    apply_call = recorded['apply_calls'][-1]
+    assert apply_call['imagetype'] == expected_imagetype
+
+    # Check image was written and metadata copied
+    assert recorded['written'] and recorded['written'][-1][1] == "out.nii"
+    assert recorded['meta_copied'] and recorded['meta_copied'][-1] == ("pet.nii", "out.nii")
+
+    # Check verbose prints
+    captured = capsys.readouterr().out
+    print(captured)
+    assert "Registration computed transforming image motion_target.nii to mri.nii space" in captured
+    assert "Registration applied to pet.nii" in captured
+    assert "Transformed image saved to out.nii" in captured

petpal-0.5.8/tests/test_scan_timing_decay.py

@@ -0,0 +1,146 @@
+import numpy as np
+import pytest
+from petpal.utils.scan_timing import calculate_frame_reference_time
+from petpal.preproc.decay_correction import calculate_frame_decay_factor
+from petpal.utils.scan_timing import ScanTimingInfo
+
+
+def test_from_metadata_with_all_keys():
+    metadata = {
+        "FrameDuration": [60, 120, 180],
+        "FrameTimesStart": [0, 60, 180],
+        "FrameTimesEnd": [60, 180, 360],
+        "FrameReferenceTime": [30, 120, 270],
+        "DecayCorrectionFactor": [1.0, 0.95, 0.9],
+    }
+    sti = ScanTimingInfo.from_metadata(metadata)
+    np.testing.assert_allclose(sti.duration, np.array([60.0, 120.0, 180.0]))
+    np.testing.assert_allclose(sti.start, np.array([0.0, 60.0, 180.0]))
+    np.testing.assert_allclose(sti.end, np.array([60.0, 180.0, 360.0]))
+    np.testing.assert_allclose(sti.center, np.array([30.0, 120.0, 270.0]))
+    np.testing.assert_allclose(sti.decay, np.array([1.0, 0.95, 0.9]))
+    assert sti.duration.dtype.kind == "f"
+    assert sti.start.dtype.kind == "f"
+    assert sti.end.dtype.kind == "f"
+    assert sti.center.dtype.kind == "f"
+    assert sti.decay.dtype.kind == "f"
+
+
+def test_from_metadata_infers_start_end_and_center_and_uses_decayfactor():
+    metadata = {
+        "FrameDuration": [30, 30, 60],
+        # no FrameTimesStart, no FrameTimesEnd, no FrameReferenceTime
+        "DecayFactor": [1.0, 0.99, 0.98],
+    }
+    sti = ScanTimingInfo.from_metadata(metadata)
+    expected_starts = np.array([0.0, 30.0, 60.0])
+    expected_ends = np.array([30.0, 60.0, 120.0])
+    expected_centers = expected_starts + np.array([30.0, 30.0, 60.0]) / 2.0
+    np.testing.assert_allclose(sti.start, expected_starts)
+    np.testing.assert_allclose(sti.end, expected_ends)
+    np.testing.assert_allclose(sti.center, expected_centers)
+    np.testing.assert_allclose(sti.duration, np.array([30.0, 30.0, 60.0]))
+    np.testing.assert_allclose(sti.decay, np.array([1.0, 0.99, 0.98]))
+
+
+def test_from_metadata_prefers_decay_correction_over_decayfactor():
+    metadata = {
+        "FrameDuration": [10, 20],
+        "FrameTimesStart": [0, 10],
+        "FrameTimesEnd": [10, 30],
+        "DecayFactor": [0.5, 0.6],
+        "DecayCorrectionFactor": [0.9, 0.8],
+    }
+    sti = ScanTimingInfo.from_metadata(metadata)
+    # DecayCorrectionFactor should be used when present
+    np.testing.assert_allclose(sti.decay, np.array([0.9, 0.8]))
+
+
+def test_from_start_end_computes_duration_center_and_default_decay():
+    starts = np.array([0.0, 60.0, 180.0])
+    ends = np.array([60.0, 180.0, 360.0])
+    info = ScanTimingInfo.from_start_end(frame_starts=starts, frame_ends=ends)
+    np.testing.assert_allclose(info.duration, np.array([60.0, 120.0, 180.0]))
+    np.testing.assert_allclose(info.center, np.array([30.0, 120.0, 270.0]))
+    np.testing.assert_allclose(info.decay, np.ones_like(starts))
+
+def test_from_start_end_uses_provided_decay_list():
+    starts = np.array([0.0, 50.0])
+    ends = np.array([25.0, 100.0])
+    decay_list = [1.0, 0.9]
+    info = ScanTimingInfo.from_start_end(frame_starts=starts, frame_ends=ends, decay_correction_factor=decay_list)
+    np.testing.assert_allclose(info.duration, np.array([25.0, 50.0]))
+    np.testing.assert_allclose(info.center, np.array([12.5, 75.0]))
+    np.testing.assert_allclose(info.decay, np.array(decay_list))
+
+def test_ref_time_no_decay_returns_midpoint():
+    durations = np.array([5.0, 10.0])
+    starts = np.array([0.0, 5.0])
+    half_life = 1.0e8  # effectively no decay
+    res = calculate_frame_reference_time(durations, starts, half_life)
+    expected = starts + durations / 2.0
+    np.testing.assert_allclose(res, expected, rtol=1e-2, atol=1e-3)
+
+
+def test_ref_time_fast_decay_concentrates_near_start():
+    durations = np.array([60.0, 30.0, 15.0])
+    starts = np.array([0.0, 5.0, 10.0])
+    half_life = 1e-6  # very fast decay
+    res = calculate_frame_reference_time(durations, starts, half_life)
+    delays = res - starts
+    # For very fast decay, the reference time should be very close to frame start
+    assert np.all(delays < durations * 0.01)
+
+
+def test_ref_time_numeric_integration_agrees():
+    # compare against numeric integral definition of weighted average time
+    durations = np.array([5.0, 10.0, 60.0])
+    starts = np.array([0.0, 5.0, 15.0])
+    half_life = 1e4
+    res = calculate_frame_reference_time(durations, starts, half_life)
+
+    expected = []
+    for T, s in zip(durations, starts):
+        lam = np.log(2) / half_life
+        t = np.linspace(0.0, T, 20001)
+        w = np.exp(-lam * t)
+        num = np.trapezoid(t * w, t)
+        den = np.trapezoid(w, t)
+        delay = num / den
+        expected.append(s + delay)
+    expected = np.asarray(expected)
+
+    np.testing.assert_allclose(res, expected, rtol=1e-3, atol=1e-9)
+
+
+def test_ref_time_vectorized_shape_and_broadcast():
+    durations = np.array([10.0])
+    starts = np.array([2.0])
+    half_life = 1.0e3
+    res = calculate_frame_reference_time(durations, starts, half_life)
+    assert isinstance(res, np.ndarray)
+    assert res.shape == (1,)
+
+
+def test_basic_powers_of_two():
+    half_life = 2.0
+    times = np.array([0.0, half_life, 2 * half_life])
+    out = calculate_frame_decay_factor(times, half_life)
+    expected = np.array([1.0, 2.0, 4.0])
+    np.testing.assert_allclose(out, expected, rtol=1e-12, atol=0)
+
+
+def test_preserves_shape_and_dtype():
+    times = np.array([0.5])
+    out = calculate_frame_decay_factor(times, 1.0)
+    assert isinstance(out, np.ndarray)
+    assert out.shape == times.shape
+    np.testing.assert_allclose(out[0], 2 ** 0.5, rtol=1e-12)
+
+
+def test_negative_time_and_float_half_life():
+    half_life = 1.5
+    times = np.array([-half_life, 0.0, half_life])
+    out = calculate_frame_decay_factor(times, half_life)
+    expected = np.array([0.5, 1.0, 2.0])
+    np.testing.assert_allclose(out, expected, rtol=1e-12, atol=0)

petpal-0.5.8/tests/test_weighted_sum.py

@@ -0,0 +1,51 @@
+import numpy as np
+import pytest
+from petpal.utils.math_lib import weighted_sum_computation
+from petpal.utils.scan_timing import calculate_frame_reference_time
+from petpal.preproc.decay_correction import calculate_frame_decay_factor
+
+def test_weighted_sum_computation_all_ones_simple():
+    # simple case: all voxels = 1, decay_correction = 1, frame_start[0]=0
+    pet_series = np.ones((2, 2, 2, 3), dtype=float)
+    frame_duration = np.array([10.0, 20.0, 30.0])
+    half_life = 100.0
+    frame_start = np.array([0.0, 10.0, 30.0])
+    decay_correction = np.ones(3)
+
+    decay_constant = np.log(2.0) / half_life
+    image_total_duration = frame_duration.sum()
+    total_decay = decay_constant * image_total_duration
+    total_decay /= 1.0 - np.exp(-decay_constant * image_total_duration)
+    total_decay /= np.exp(-decay_constant * frame_start[0])
+
+    expected = np.full((2, 2, 2), total_decay)
+    out = weighted_sum_computation(pet_series, frame_duration, half_life, frame_start, decay_correction)
+    np.testing.assert_allclose(out, expected)
+
+def test_weighted_sum_computation_manual_computation():
+    # randomized small example, validate against manual numpy computation
+    rng = np.random.default_rng(0)
+    pet_series = rng.random((3, 2, 1, 4)).astype(float)
+    frame_duration = np.array([5.0, 5.0, 10.0, 300.0])
+    half_life = 50.0
+    frame_start = np.array([1.0, 6.0, 11.0, 21.0])
+    frame_ref_time = calculate_frame_reference_time(frame_duration=frame_duration,
+                                                    frame_start=frame_start,
+                                                    half_life=half_life)
+    decay_correction = calculate_frame_decay_factor(frame_reference_time=frame_ref_time,
+                                                    half_life=half_life)
+
+    # manual expected computation following function logic
+    decay_constant = np.log(2.0) / half_life
+    image_total_duration = frame_duration.sum()
+    total_decay = decay_constant * image_total_duration
+    total_decay /= 1.0 - np.exp(-decay_constant * image_total_duration)
+    total_decay /= np.exp(-decay_constant * frame_start[0])
+
+    # compute weighted sum: sum_t(pet[...,t] * frame_duration[t] / decay_correction[t])
+    scaled = pet_series * frame_duration / decay_correction  # broadcasting over last axis
+    pet_series_sum_scaled = scaled.sum(axis=3)
+    expected = pet_series_sum_scaled * total_decay / image_total_duration
+
+    out = weighted_sum_computation(pet_series, frame_duration, half_life, frame_start, decay_correction)
+    np.testing.assert_allclose(out, expected)