MultiTACRTMAnalysis#

class petpal.kinetic_modeling.rtm_analysis.MultiTACRTMAnalysis(ref_tac_path: str, roi_tacs_dir: str, output_directory: str, output_filename_prefix: str, method: str)#

Bases: RTMAnalysis, petpal.utils.time_activity_curve.MultiTACAnalysisMixin

A class for performing reference tissue model (RTM) analysis on multiple tissue TACs.

Variables:

  • ref_tac_path (str) – Path to the reference TAC file.

  • roi_tacs_dir (str) – Directory containing region of interest TAC files.

  • output_directory (str) – Directory for saving analysis results.

  • output_filename_prefix (str) – Prefix for output filenames.

  • method (str) – Method used for RTM analysis.

Initializes the MultiTACRTMAnalysis object with required paths and analysis method.

Parameters:

  • ref_tac_path (str) – Path to the reference TAC file.

  • roi_tacs_dir (str) – Directory containing region of interest TAC files.

  • output_directory (str) – Directory for saving analysis results.

  • output_filename_prefix (str) – Prefix for output filenames.

  • method (str) – Method used for RTM analysis.

init_analysis_props(method: str) → list[dict]#

Initializes analysis properties for each tissue TAC using the specified method. Overrides RTMAnalysis.init_analysis_props().

Parameters:

method (str) – Method used for initializing analysis properties.

Returns:

list[dict] – A list of analysis property dictionaries for each TAC.

calculate_fit(bounds: None | numpy.ndarray = None, t_thresh_in_mins: float = None, k2_prime: float = None) → list#

Calculates the fit for each TAC, updating the analysis properties with model fit results. Overrides RTMAnalysis.calculate_fit().

Parameters:

  • bounds (Union[None, np.ndarray], optional) – Bounds for the fitting parameters. Defaults to None.

  • t_thresh_in_mins (float, optional) – Threshold in minutes for fit calculation. Defaults to None.

  • k2_prime (float, optional) – A reference tissue model parameter. Defaults to None.

  • **tac_load_kwargs – Additional keyword arguments for TAC loading.

Returns:

list – A list of fit results for each TAC.

calculate_fit_properties(fit_results: list[numpy.ndarray], t_thresh_in_mins: float = None, k2_prime: float = None)#

Calculates additional properties of the fit based on the fit results and threshold for each TAC. Overrides RTMAnalysis.calculate_fit_properties().

Parameters:

  • fit_results (list[np.ndarray]) – Results from the fitting procedure.

  • t_thresh_in_mins (float, optional) – Threshold in minutes used for fitting. Defaults to None.

  • k2_prime (float, optional) – A reference tissue model parameter. Defaults to None.

save_analysis(output_as_tsv: bool = True, output_as_json: bool = False)#

Saves the analysis results to a TSV file as a table with fit parameters for each ROI.

Parameters:

  • output_as_tsv (bool) – Set True to write results to TSV table. Default True.

  • output_as_json (bool) – Set True to write results to a folder with one JSON file per region. Default False.

Raises:

RuntimeError – If ‘run_analysis’ method has not been called before save_analysis.

__call__(output_as_tsv: bool = True, output_as_json: bool = False, **run_kwargs)#

Runs run_analysis() and save_analysis() to run the analysis and save the analysis properties.

Parameters:

  • output_as_tsv (bool) – Set True to write results to TSV table. Default True.

  • output_as_json (bool) – Set True to write results to a folder with one JSON file per region. Default False.

  • run_kwargs – Additional keyword arguments used in the analysis. These are passed on to run_analysis().

run_analysis(bounds: None | numpy.ndarray = None, t_thresh_in_mins: float = None, k2_prime: float = None, **tac_load_kwargs)#

Runs the full RTM analysis process which involves validating inputs, calculation fits, and deducing fit properties.

Specifically, it executes the following sequence:

  1. validate_analysis_inputs()

  2. calculate_fit()

  3. calculate_fit_properties()

Parameters:

  • bounds (Union[None, np.ndarray], optional) – Optional boundaries for parameters for fitting function.

  • t_thresh_in_mins (float, optional) – Threshold time in minutes for the MRTM analyses.

  • k2_prime (float, optional) – Input for the modified RTM (MRTM2, FRTM2, and SRTM2) analyses.

Returns:

None

validate_analysis_inputs(k2_prime, t_thresh_in_mins)#

Validates the provided inputs for the RTM analysis.

If MRTM type of analysis is being run, it ensures that t_thresh_in_mins is not None. If modified analysis is being done (MRTM2, FRTM2, SRTM2), it ensures k2_prime is not None.

Parameters:

  • k2_prime (float) – k2 prime value.

  • t_thresh_in_mins (float) – Threshold time for MRTM analyses.

Raises:

ValueError – If an input required for the selected method is None.

_calc_mrtm_fit_props(fit_results: numpy.ndarray | tuple[numpy.ndarray, numpy.ndarray], k2_prime: float, t_thresh_in_mins: float, props_dict: dict, write_simulated: bool = False)#

Internal function used to calculate additional fitting properties for ‘mrtm’ type analyses.

This method is used internally within calculate_fit_properties().

Parameters:

  • fit_results (np.ndarray) – Resulting fit parameters.

  • k2_prime (float) – k2 prime value for ‘mrtm’ based methods.

  • t_thresh_in_mins (float) – Threshold time for MRTM analyses.

_calc_frtm_or_srtm_fit_props(fit_results: tuple[numpy.ndarray, numpy.ndarray], k2_prime: float, props_dict: dict)#

Internal function used to calculate additional fitting properties for ‘frtm’ and ‘srtm’ type analyses.

This method is used internally within calculate_fit_properties().

Parameters:

fit_results (tuple[np.ndarray, np.ndarray]) – Tuple containing the fit parameters and their corresponding fit covariances.

static _get_pretty_srtm_fit_param_vals(param_fits: numpy.ndarray, reduced: bool = False) → dict#

Utility function to get nicely formatted fit parameters for ‘srtm(2)’ analysis.

Returns a dictionary with keys: ‘R1’, ‘k2’, and ‘BP’ and the corresponding values from param_fits.

Parameters:

param_fits (np.ndarray) – array containing the fit parameters.

Returns:

dict – Dictionary of fit parameters and their corresponding values.

static _get_pretty_frtm_fit_param_vals(param_fits: numpy.ndarray, reduced: bool = False) → dict#

Utility function to get nicely formatted fit parameters for ‘frtm(2)’ analysis.

Returns a dictionary with keys: ‘R1’, ‘k2’, ‘k3’, and ‘k4’ and the corresponding values from param_fits.

Parameters:

param_fits (np.ndarray) – array containing the fit parameters.

Returns:

dict – Dictionary of fit parameters and their corresponding values.

property input_tac_path#

Gets the input TAC file path.

property tacs_dir#

Gets the TAC directory path.

property reference_tac_path#

Gets the reference TAC file path.

is_valid_tacs_dir(tacs_dir: str)#

Validates the TAC directory by checking for TAC files.

Parameters:

tacs_dir (str) – Directory to validate.

Returns:

bool – True if valid, otherwise False.

static get_tacs_list_from_dir(tacs_dir: str) → list[str]#

Retrieves a sorted list of TAC file paths from a directory.

Parameters:

tacs_dir (str) – Directory from which to retrieve TAC files.

Returns:

list[str] – Sorted list of TAC file paths.

static get_tacs_objects_dict_from_files_list(tacs_files_list: list[str])#

Creates a dict of TAC objects from a list of file paths.

Parameters:

tacs_files_list (list[str]) – List of TAC file paths.

Returns:

dict – Dictionary of region name-TAC object pairs.

static get_tacs_objects_dict_from_dir(tacs_dir: str) → dict#

Creates a dict of TAC objects from a directory of TAC files.

Parameters:

tacs_dir (str) – A directory of TAC files.

Returns:

dict – Dictionary of region name-TAC object pairs.

static get_tacs_objects_list_from_files_list(tacs_files_list: list[str])#

Creates a list of TAC objects from a list of file paths.

Parameters:

tacs_files_list (list[str]) – List of TAC file paths.

Returns:

list[TimeActivityCurve] – List of TAC objects.

static get_tacs_vals_from_objs_list(tacs_objects_list: list[TimeActivityCurve])#

Extracts TAC values from a list of TAC objects.

Parameters:

tacs_objects_list (list[TimeActivityCurve]) – List of TAC objects.

Returns:

list – List of TAC values.

get_tacs_vals_from_dir(tacs_dir: str)#

Retrieves TAC values from files in a specified directory.

Parameters:

tacs_dir (str) – Directory containing TAC files.

Returns:

list – List of TAC values.

static capitalize_first_char_of_str(input_str: str)#

Capitalize only the first character of a string, leaving the remainder unchanged.

Parameters:

input_str (str) – The string to capitalize the first character of.

Returns:

output_str (str) – The string with only the first character capitalized.

static infer_segmentation_label_from_tac_path(tac_path: str, tac_id: int)#

Infers a segmentation label from a TAC file path by analyzing the filename.

This method extracts a segment label from the filename of a TAC file. It checks the presence of a seg- marker in the filename, which is followed by the segment name. This segment name is then formatted with each part capitalized. If no segment label is found, a default unknown label is generated using the TAC’s ID.

Parameters:

  • tac_path (str) – Path of the TAC file.

  • tac_id (int) – ID of the TAC.

Returns:

str – Inferred segmentation label.

infer_segmentation_labels_for_tacs()#

Infers segmentation labels for TACs.

Returns:

list[str] – List of inferred segmentation labels.

See also

infer_segmentation_label_from_tac_path()