ScanTimingInfo#

class petpal.utils.scan_timing.ScanTimingInfo#

A data structure to represent and streamline access to timing information for image scans.

This class encapsulates details about a scan’s timing, including: - Start and end times of each scan frame. - Duration and center times of the frames. - Decay values (if applicable).

Additionally, the class provides properties for easy conversion of timing values to minutes if the times are given in seconds and exceed a threshold (assumed to be 200.0 seconds).

Variables:

  • duration (np.ndarray[float]) – Array of frame durations.

  • end (np.ndarray[float]) – Array of frame end times.

  • start (np.ndarray[float]) – Array of frame start times.

  • center (np.ndarray[float]) – Array of frame center times (midpoints).

  • decay (np.ndarray[float]) – Array of decay coefficients for the scan frames.

Properties:
duration_in_mins (np.ndarray[float]):

Returns the frame durations converted to minutes if end is >= 200.0 seconds. Otherwise, returns the original durations.

end_in_mins (np.ndarray[float]):

Returns the frame end times converted to minutes if end is >= 200.0 seconds. Otherwise, returns the original end times.

start_in_mins (np.ndarray[float]):

Returns the frame start times converted to minutes if end is >= 200.0 seconds. Otherwise, returns the original start times.

center_in_mins (np.ndarray[float]):

Returns the frame center times converted to minutes if end is >= 200.0 seconds. Otherwise, returns the original center times.

Examples

import numpy as np
from petpal.utils.scan_timing import ScanTimingInfo

# Explicitly setting the attributes
## Define scan timing information
duration = np.array([60.0, 120.0, 180.0])  # seconds
start = np.array([0.0, 60.0, 180.0])
end = np.array([60.0, 180.0, 360.0])
center = (start + end) / 2.0  # Calculate the midpoints
decay = np.array([1.0, 0.9, 0.8])  # Example decay values

## Create an instance of ScanTimingInfo
scan_timing_info = ScanTimingInfo(duration=duration, end=end, start=start, center=center, decay=decay)

## Access original timing information
print(scan_timing_info.duration)  # [ 60. 120. 180.]
print(scan_timing_info.center)    # [30.  120. 270.]

## Access timing as minutes (when times exceed 200.0 seconds)
print(scan_timing_info.duration_in_mins)  # [ 60. 120. 180.] (Unchanged)
print(scan_timing_info.center_in_mins)    # [30. 120. 270.] (Unchanged)

## Example when `end` is greater than 200.0:
scan_timing_info.end = np.array([300.0, 400.0, 500.0])  # Update end times
print(scan_timing_info.end_in_mins)  # [5. 6.66666667 8.33333333] (Converted to minutes)
print(scan_timing_info.start_in_mins)  # [0. 1. 3.] (Converted to minutes)

# Getting the object directly from a nifti image file
# assuming the metadata shares the name
scan_timing_info = ScanTimingInfo.from_nifti("/path/to/image.nii.gz")
property duration_in_mins: numpy.ndarray[float]#

Returns the frame durations in minutes. Validates values by checking if the final frame value is greater than 200: if so, then assumes values are in seconds and divides by 60.

property end_in_mins: numpy.ndarray[float]#

Returns the frame time ends in minutes. Validates values by checking if the final frame value is greater than 200: if so, then assumes values are in seconds and divides by 60.

property start_in_mins: numpy.ndarray[float]#

Returns the frame time starts in minutes. Validates values by checking if the final frame value is greater than 200: if so, then assumes values are in seconds and divides by 60.

property center_in_mins: numpy.ndarray[float]#

Returns the frame reference times in minutes. Validates values by checking if the final frame value is greater than 200: if so, then assumes values are in seconds and divides by 60.

classmethod from_metadata(metadata_dict: dict) → Self#

Extracts frame timing information and decay factors from a json metadata. Expects that the JSON metadata has FrameDuration and DecayFactor or DecayCorrectionFactor keys.

Important

This function tries to infer FrameTimesEnd and FrameTimesStart from the frame durations if those keys are not present in the metadata file. If the scan is broken, this might generate incorrect results.

Parameters:

metadata_dict (dict) – The metadata dictionary, loaded into memory.

Returns:

ScanTimingInfo –

Frame timing information with the following elements:

  • duration (np.ndarray): Frame durations in seconds.

  • start (np.ndarray): Frame start times in seconds.

  • end (np.ndarray): Frame end times in seconds.

  • center (np.ndarray): Frame center times in seconds.

  • decay (np.ndarray): Decay factors for each frame.

classmethod from_nifti(image_path: str) → Self#

Extracts frame timing information and decay factors from a NIfTI image metadata. Expects that the JSON metadata file has FrameDuration and DecayFactor or DecayCorrectionFactor keys.

Important

This function tries to infer FrameTimesEnd and FrameTimesStart from the frame durations if those keys are not present in the metadata file. If the scan is broken, this might generate incorrect results.

Parameters:

image_path (str) – Path to the NIfTI image file.

Returns:

ScanTimingInfo –

Frame timing information with the following elements:

  • duration (np.ndarray): Frame durations in seconds.

  • start (np.ndarray): Frame start times in seconds.

  • end (np.ndarray): Frame end times in seconds.

  • center (np.ndarray): Frame center times in seconds.

  • decay (np.ndarray): Decay factors for each frame.

classmethod from_start_end(frame_starts: numpy.ndarray, frame_ends: numpy.ndarray, decay_correction_factor: numpy.ndarray | None = None) → Self#

Infer timing properties based on start and end time.

Parameters:

  • 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.