RegionalStats
================================

.. py:class:: petpal.utils.stats.RegionalStats(input_image_path: str, segmentation_image_path: str, label_map_option: str | dict)

   Run statistics on each region in a parametric 3D PET kinetic model or other image.

   Options:
       * RegionalStats.mean: Mean value within each region
       * RegionalStats.std: Standard devation of values within each region.
       * RegionalStats.nvox: Number of voxels in each region.
       * RegionalStats.max: Maximum value in each region.
       * RegionalStats.min: Minimum value in each region.
       * RegionalStats.median: Median value in each region.
       * RegionalStats.get_stats(stats_func): Get a generic statistic run on each region. Runs
         function `stats_func` on each region, which must take a 1D array as the only argument.

   .. rubric:: Example

   .. code-block:: python

       import numpy as np
       from petpal.utils.stats import RegionalStats
       from petpal.utils.image_io import write_dict_to_json

       # Set up class
       input_image_path = 'sub-001_ses-01_space-mpr_desc-SUVR_pet.nii.gz'
       segmentation_image_path = 'sub-001_ses-01_seg.nii.gz'
       region_stats_obj = RegionalStats(input_image_path = input_image_path,
                                        segmentation_image_path = segmentation_image_path,
                                        label_map_option = 'freesurfer')

       # Preset statistic: get mean in each region
       region_means = region_stats_obj.mean
       write_dict_to_json(region_means,'sub-001_ses-01_RegionMeanSUVR.json')

       # Create function to get 95th percentile value for each region
       def calc_95th_percentile(arr: np.ndarray):
           return np.percentile(arr,95)
       region_95th = region_stats_obj.get_stats(calc_95th_percentile)
       write_dict_to_json(region_95th,'sub-001_ses-01_Region95thPercentileSUVR.json')

   :ivar pet_img: 3D PET image on which to get statistics for each region.
   :ivar seg_img: Segmentation image in same space as `pet_img` defining regions.
   :ivar label_map: Dictionary that assigns labels to regions in `seg_img`.


   .. py:method:: get_voxels(label: str) -> numpy.ndarray

      Get the voxel array for the selected label.

      :param label: Name of the region from which to extract voxels.
      :type label: str

      :returns: *voxel_arr (np.ndarray)* -- Voxels in region as a flattened array.



   .. py:method:: get_stats(stats_func: collections.abc.Callable, dtype: object = float) -> dict

      Get stats for all regions. Applies `stats_func` to the `voxel_arr` to return a
      value for each region. Set `dtype` depending on what type the output is (e.g. float or
      int).

      :param stats_func: The function to run on each region's voxels. Must take a 1D
                         array as the only required positional argument and return a value or np.ndarray.
      :type stats_func: Callable
      :param dtype: The dtype that `stats_func` returns, if not float. Typically float or
                    int. Default float.
      :type dtype: object

      :returns: *region_stats (dict)* -- The statistics for each region of interest.



   .. py:property:: mean
      :type: dict


      Get mean value for each region.


   .. py:property:: std
      :type: dict


      Get standard deviation of values for each region.


   .. py:property:: nvox
      :type: dict


      Get number of voxels in each region.


   .. py:property:: max
      :type: dict


      Get maximum value in each region.


   .. py:property:: min
      :type: dict


      Get minimum value in each region.


   .. py:property:: median
      :type: dict


      Get median value in each region.