LabelMapLoader
=====================================

.. py:class:: petpal.meta.label_maps.LabelMapLoader(label_map_option: str | dict)

   Class for loading label map data to convert between segmentation mappings and region
   labels.

   There are three ways to load label maps, using argument `label_map_option`:

   1. (str) Load a preset option implemented in PETPAL. These include `freesurfer`,
      `freesurfer_merge_lr`, `perlcyno`, `perlcyno_merge_lr`. See
      :meth:`~LabelMapLoader.from_petpal`.
   #. (str) Load a json file that maps regions used in your study. Provide the path to the
      .json file. See :meth:`~LabelMapLoader.from_json`.
   #. (dict) Load a Python dictionary that implements a label map for region in your study. See
      :meth:`~LabelMapLoader.from_dict`.

   :ivar loader_method: A string or dictionary to load as a label map.
   :ivar label_map: The label map to use in PETPAL methods.


   .. py:method:: from_petpal(label_map_name: str) -> dict

      Loads a label map based on an existing list of label maps implemented in PETPAL.

      Options include:

      * `freesurfer`: The regions corresponding to the aparc+aseg segmentation image.
      * `freesurfer_merge_lr`: The regions corresponding to the aparc+aseg segmentation image.
        Unilateral map combining each left/right split into one region.
      * `perlcyno`: Bilateral regions in the PerlCyno primate atlas.
      * `perlcyno_merge_lr`: Unilateral map combining left/right regions in the PerlCyno
        primate atlas.

      :param label_map_name: A name matching a preset option for a label map.
      :type label_map_name: str

      :returns: *label_map (dict)* -- The label map selected.



   .. py:method:: from_dict(label_map: dict) -> dict

      Provide a label map implemented in Python.

      :param label_map: The label map implemented for use in the PET study.
      :type label_map: dict

      :returns: *label_map (dict)* -- The label map selected.



   .. py:method:: from_json(label_map_path: str) -> dict

      Load a label map from a .json file.

      :param label_map_path: Path to the label map for use in the PET study.
      :type label_map_path: str

      :returns: *label_map (dict)* -- The label map loaded from file.



   .. py:method:: from_dseg_tsv(label_map_path: str) -> dict

      Load a label map from a .tsv file.

      :param label_map_path: Path to the label map for use in the PET study.
      :type label_map_path: str

      :returns: *label_map (dict)* -- The label map loaded from file.



   .. py:method:: detect_option(label_map_option: dict | str) -> collections.abc.Callable

      Determine the label map loading method to use based on the provided option.

      :raises FileNotFoundError: If the label_map_option looks like a path but doesn't point to an
          existing file.
      :raises TypeError: If the label_map_option is not a str or dict instance.



   .. py:method:: labels_to_camel_case()

      Convert all label map labels to camel case and update label map.



   .. py:method:: validate_mappings()

      Validate mapping values for integer mappings in the label map. Mappings can be an
      integer or a list of integers.

      :raises TypeError: If one of the mappings is not an integer or a list of integers.