apply_mask_4d
====================================================

.. py:function:: petpal.preproc.regional_tac_extraction.apply_mask_4d(input_arr: numpy.ndarray, mask_arr: numpy.ndarray, verbose: bool = False) -> numpy.ndarray

   Function to extract ROI voxel tacs from an array using a mask array.

   This function applies a 3D mask to a 4D image, returning the time series for each voxel in a
   single flattened numpy array.

   :param input_arr: Input 4D-image from which to extract ROI voxel tacs.
   :type input_arr: np.ndarray
   :param mask_arr: Mask image which determines which voxels to extract.
   :type mask_arr: np.ndarray
   :param verbose: If True, prints information about the shape of extracted voxel
                   tacs.
   :type verbose: bool, optional

   :returns: *out_voxels (np.ndarray)* -- Time series of each voxel in the mask, as a flattened numpy array.

   :raises AssertionError: If input array is not 4D.
   :raises AssertionError: If input and mask array shapes are mismatched.

   .. rubric:: Example

   .. code-block:: python

       import ants
       import numpy as np

       from petpal.preproc.regional_tac_extraction import apply_mask_4d

       # Read images
       pet_img = ants.image_read("/path/to/pet.nii.gz")
       masked_region_img = ants.image_read("/path/to/mask_region.nii.gz")

       # Get underlying arrays
       pet_arr = pet_img.numpy()
       masked_region_arr = masked_region_img.numpy()

       # Run ROI extraction and save
       time_series = apply_mask_4d(input_arr=pet_arr, mask_arr=masked_region_arr).T
       np.savetxt("time_series.tsv", time_series, delimiter='      ')