WriteRegionalTacs#

class petpal.preproc.regional_tac_extraction.WriteRegionalTacs(input_image_path: str | pathlib.Path, segmentation_path: str | pathlib.Path, label_map: str | dict, tac_extraction_func: collections.abc.Callable = voxel_average_w_uncertainty)#

Write regional TACs

Variables:

pet_arr (np.ndarray) – Numpy array containing 4D PET data.
seg_arr (np.ndarray) – Numpy array containing 3D discrete segmentation data.
tac_extraction_func (Callable) – A function that takes a 2D M x N numpy array with M voxels and N time frames as well as any number of optional keyword arguments and returns a tuple of 1D N-length numpy arrays with the calculated TAC and uncertainty.
scan_timing (ScanTimingInfo) – Scan timing for the input PET image.
region_names (list) – Names of regions to use in the analysis.
region_maps (list) – Region mappings to use in the analysis, corresponding 1-1 with region_names.

Example

from petpal.preproc.regional_tac_extraction import WriteRegionalTacs
from petpal.utils.bids_utils import gen_bids_like_filepath, gen_bids_like_dir_path

pet_image_path = gen_bids_like_filepath(sub_id='001',
                                        ses_id='01',
                                        suffix='pet',
                                        ext='.nii.gz')
seg_image_path = gen_bids_like_filepath(sub_id='001',
                                        ses_id='01',
                                        bids_dir='../derivatives/petpal/'
                                        suffix='seg',
                                        modality='seg',
                                        space='pet',
                                        ext='.nii.gz')
tac_output_dir = gen_bids_like_dir_path(sub_id='001',
                                        ses_id='01',
                                        modality='tacs',
                                        sup_dir='../derivatives/petpal/')
tac_calculator = WriteRegionalTacs(input_image_path=pet_image_path,
                                   segmentation_path=seg_image_path,
                                   label_map_path='dseg.tsv')
tac_calculator(out_tac_dir=tac_output_dir,
               out_tac_prefix='sub-001_ses-01',
               one_tsv_per_region=False)

Initialize WriteRegionalTacs.

Parameters:

input_image_path (str | pathlib.Path) – Path to input 4D PET image.
segmentation_path (str | pathlib.Path) – Path to 3D discrete segmentation image. Must match input PET image space.
label_map (str | dict) – Label map for use in the study. Provide name of a preset label map option such as ‘freesurfer’, the path to a label map JSON file, or a Python dictionary with region mappings. For more details, see LabelMapLoader.
tac_extraction_func (Callable) – Function to get TAC from 2D array of voxels. Default voxel_average_w_uncertainty().

set_tac_extraction_func(tac_extraction_func: collections.abc.Callable)#

Sets the tac extraction function used to a different function.

The selected function must take a 2D array of the masked voxels as input, and return the calculated activity and uncertainty across the masked voxels outputs.

Parameters:: tac_extraction_func (Callable) – Function that takes a 2D M x N numpy array with M voxels and N time frames as well as any number of optional keyword arguments and returns a tuple of 1D N-length numpy arrays with the calculated TAC and uncertainty.

find_label_name(label: int) → str#

Find the name for a label based on the provided label map. If a name is not found, return ‘UNK’ followed by the label index.

Parameters:: label (int) – Label mapping for a region.
Returns:: region_name (str) – Name of the region corresponding to the provided label.

is_empty_region(pet_masked_region: numpy.ndarray) → bool#

Check if masked PET region has zero matched voxels, or is all NaNs. In either case, return True, otherwise return False.

Parameters:: pet_masked_region (np.ndarray) – Array of PET voxels masked to a specific region.
Returns:: pet_masked_region_is_empty (bool) – If True, input region is empty.

extract_tac(region_mapping: int | list[int], **tac_calc_kwargs) → petpal.utils.time_activity_curve.TimeActivityCurve#

Run self.tac_extraction_func on one region and return the TAC.

Parameters:

region_mapping (int | list[int]) – The integer ID or IDs corresponding to the ROI.
**tac_calc_kwargs – Additional keyword arguments passed on to tac_extraction_func.

Returns:

region_tac (TimeActivityCurve) – The calculated TAC for the region.

gen_tacs_data_frame() → pandas.DataFrame#

Get empty data frame to store TACs. Sets first two columns to frame start and end times, and remaining columns are named by region activity and uncertainty, based on the regions included in the label map.

Returns:: tacs_data (pd.DataFrame) – Data frame with columns set for frame start and end time, and activity and uncertainty for each included region. Frame start and end time columns filled with scan timing data.

write_tacs(out_tac_prefix: str, out_tac_dir: str | pathlib.Path, one_tsv_per_region: bool = True, **tac_calc_kwargs)#

Function to write Tissue Activity Curves for each region, given a segmentation, 4D PET image, and label map. Computes the average of the PET image within each region. Writes TACs in TSV format with region name, frame start time, frame end time, and activity and uncertainty within each region. Skips writing regions without any matched voxels.

Parameters:

out_tac_prefix (str) – Prefix for the output files, usually the BIDS subject and session ID.
out_tac_dir (str | pathlib.Path) – Output path where files are saved.
one_tsv_per_region (bool) – If True, write one TSV TAC file for each region in the image. If False, write one TSV file with all TACs in the image.
**tac_calc_kwargs – Additional keywords passed onto tac_extraction_func.

Raises:

Warning – for each region without any matched voxels, warn user that TAC is skipped.

__call__(out_tac_prefix: str, out_tac_dir: str | pathlib.Path, one_tsv_per_region: bool = True, **tac_calc_kwargs)#

Runs TAC computation and writing by running self.write_tacs.

Parameters:

out_tac_prefix (str) – Prefix for the output files, usually the BIDS subject and session ID.
out_tac_dir (str | pathlib.Path) – Output path where files are saved.
one_tsv_per_region (bool) – If True, write one TSV TAC file for each region in the image. If False, write one TSV file with all TACs in the image.
**tac_calc_kwargs – Additional keywords passed onto tac_extraction_func.

WriteRegionalTacs#

This Page