WriteRegionalTacs ======================================================== .. py: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 :ivar pet_arr: Numpy array containing 4D PET data. :vartype pet_arr: np.ndarray :ivar seg_arr: Numpy array containing 3D discrete segmentation data. :vartype seg_arr: np.ndarray :ivar tac_extraction_func: 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. :vartype tac_extraction_func: Callable :ivar scan_timing: Scan timing for the input PET image. :vartype scan_timing: ScanTimingInfo :ivar region_names: Names of regions to use in the analysis. :vartype region_names: list :ivar region_maps: Region mappings to use in the analysis, corresponding 1-1 with region_names. :vartype region_maps: list .. rubric:: Example .. code-block:: python 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. :param input_image_path: Path to input 4D PET image. :type input_image_path: str | pathlib.Path :param segmentation_path: Path to 3D discrete segmentation image. Must match input PET image space. :type segmentation_path: str | pathlib.Path :param label_map: 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 :class:`LabelMapLoader`. :type label_map: str | dict :param tac_extraction_func: Function to get TAC from 2D array of voxels. Default :func:`~petpal.preproc.regional_tac_extraction.voxel_average_w_uncertainty`. :type tac_extraction_func: Callable .. py:method:: 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. :param tac_extraction_func: 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. :type tac_extraction_func: Callable .. py:method:: 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. :param label: Label mapping for a region. :type label: int :returns: *region_name (str)* -- Name of the region corresponding to the provided label. .. py:method:: 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. :param pet_masked_region: Array of PET voxels masked to a specific region. :type pet_masked_region: np.ndarray :returns: *pet_masked_region_is_empty (bool)* -- If True, input region is empty. .. py:method:: 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. :param region_mapping: The integer ID or IDs corresponding to the ROI. :type region_mapping: int | list[int] :param \*\*tac_calc_kwargs: Additional keyword arguments passed on to tac_extraction_func. :returns: *region_tac (TimeActivityCurve)* -- The calculated TAC for the region. .. py:method:: 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. .. py:method:: 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. :param out_tac_prefix: Prefix for the output files, usually the BIDS subject and session ID. :type out_tac_prefix: str :param out_tac_dir: Output path where files are saved. :type out_tac_dir: str | pathlib.Path :param one_tsv_per_region: 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. :type one_tsv_per_region: bool :param \*\*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. .. py:method:: __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`. :param out_tac_prefix: Prefix for the output files, usually the BIDS subject and session ID. :type out_tac_prefix: str :param out_tac_dir: Output path where files are saved. :type out_tac_dir: str | pathlib.Path :param one_tsv_per_region: 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. :type one_tsv_per_region: bool :param \*\*tac_calc_kwargs: Additional keywords passed onto tac_extraction_func.