MultiTACTCMAnalysis#

class petpal.kinetic_modeling.tac_fitting.MultiTACTCMAnalysis(input_tac_path: str, roi_tacs_dir: str, output_directory: str, output_filename_prefix: str, compartment_model: str, parameter_bounds: None | numpy.ndarray = None, weights: float | None | numpy.ndarray = None, resample_num: int = 512, aif_fit_thresh_in_mins: float = 40.0, max_func_iters: int = 2500, ignore_blood_volume: bool = False)#

Bases: TCMAnalysis, petpal.utils.time_activity_curve.MultiTACAnalysisMixin

A class for performing tissue compartment model (TCM) analysis on multiple tissue TACs.

Variables:

  • input_tac_path (str) – Path to the input 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.

  • compartment_model (str) – Name of the compartment model to use.

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

  • weights (Union[float, None, np.ndarray], optional) – Weights for fitting. Defaults to None.

  • resample_num (int) – Number of resampling points. Defaults to 512.

  • aif_fit_thresh_in_mins (float) – Threshold in minutes for AIF fitting. Defaults to 40.0.

  • max_func_iters (int) – Maximum number of iterations for the fitting function. Defaults to 2500.

  • ignore_blood_volume (bool) – Whether to ignore blood volume in the analysis. Defaults to False.

Initializes the MultiTACTCMAnalysis object with required paths, model parameters, and fitting options.

Parameters:

  • input_tac_path (str) – Path to the input 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.

  • compartment_model (str) – Name of the compartment model to use.

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

  • weights (Union[float, None, np.ndarray], optional) – Weights for fitting. Defaults to None.

  • resample_num (int, optional) – Number of resampling points. Defaults to 512.

  • aif_fit_thresh_in_mins (float, optional) – Threshold in minutes for AIF fitting. Defaults to 40.0.

  • max_func_iters (int, optional) – Maximum number of iterations for the fitting function. Defaults to 2500.

  • ignore_blood_volume (bool, optional) – Whether to ignore blood volume in the analysis. Defaults to False.

init_analysis_props()#

Initializes analysis properties for each tissue TAC. Overrides TCMAnalysis.init_analysis_props().

Returns:

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

calculate_fit()#

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

calculate_fit_properties()#

Updates analysis properties with formatted fit values for each TAC. Overrides TCMAnalysis.calculate_fit_properties().

save_analysis()#

Saves the analysis results to a JSON file for each TAC. Overrides TCMAnalysis.save_analysis().

Raises:

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

static validated_tcm(compartment_model: str) → str#

Validates the type of tissue compartment model.

Runs resolve_model_name() for validation, and returns the normalized string by running normalize_name().

Parameters:

compartment_model (str) – The name of the compartment model.

Returns:

str – The transformed name of the validated compartment model if it was valid.

Raises:

KeyError – If the provided compartment model is not one of ‘1tcm’, ‘2tcm-k4zero’, ‘serial-2tcm’ or ‘2tcm’.

static _get_tcm_function(compartment_model: str) → Callable#

Returns the corresponding function for the provided tissue compartment model used for the fitting class. Runs resolve_model_name() for validation, and returns the appropriate function.

Parameters:

compartment_model – The name of the tissue compartment model.

Returns:

function – The corresponding function for the tissue compartment model.

Raises:

KeyError – If the provided tissue compartment model name does not correspond to any known models.

See also

  • gen_tac_1tcm_cpet_from_tac

  • gen_tac_2tcm_with_k4zero_cpet_from_tac

  • gen_tac_2tcm_cpet_from_tac

  • TACFitter

run_analysis()#

Runs the fitting analysis given the file-paths and method.

calculate_fit() and calculate_fit_properties() are run, and the analysis-has-been-fun flag is set to true.

This method first calculates the fit, then updates the analysis properties with the fit results and finally sets the flag denoting that analysis has been successfully run.

update_props_with_formatted_fit_values(fit_results, fit_props_dict: dict)#

Update the analysis properties dictionary with formatted fit results.

Extracts fit parameters and standard errors from fit results, formats them using pretty parameter names, and updates the provided properties dictionary.

Parameters:

  • fit_results (tuple) – Tuple containing (fit_params, fit_covariances) from the fitting process.

  • fit_props_dict (dict) – Dictionary to update with formatted fit values and errors.

Side Effects:

Updates the FitProperties section of fit_props_dict with formatted FitValues, FitStdErr, and Bounds.

_generate_pretty_params(results: numpy.ndarray) → dict#

Transforms array of results into a formatted dictionary.

This method formats the fitting results into a more human-readable form. If the fitting was done without blood volume, it formats all values as ‘k_i’: value. Otherwise it formats all but the last as ‘k_i’: value and the last as ‘vb’: value.

Parameters:

results (np.ndarray) – The array of fitting results.

Returns:

dict –

The formatted fitting results as {param: value} pairs. In the case of

TACFitterWithBloodVolume, the last parameter will be named ‘vb’, others ‘k_i’. In the case of TACFitterWithoutBloodVolume, parameters will be named ‘k_i’.

_generate_pretty_bounds(bounds: numpy.ndarray | None) → dict#

Transforms array of bounds into a formatted dictionary.

This method creates a dictionary of the fitting parameters and their corresponding initial values and lower and upper bounds. The keys of the dictionary are the names of the fitting parameters from _generate_pretty_params() method.

Parameters:

bounds (np.ndarray) – The array of parameter bounds.

Returns:

dict –

The fitting parameters with their corresponding initial values, and lower and

upper bounds, in the following format: {param: {‘initial’: val, ‘lo’: lo, ‘hi’: hi}}

__call__()#
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()