pysiral.auxdata.region
======================

.. py:module:: pysiral.auxdata.region

.. autoapi-nested-parse::

   Important Note:

       All region data handlers must be subclasses of pysiral.auxdata.AuxdataBaseClass in order to work
       for the Level-2 Processor. If the auxiliary class is based on a static dataset, this should be parsed
       in `__init__`.

       Please review the variables and properties in the parent class, as well as the corresponding config and
       support classes for grid track interpolation in the pysiral.auxdata module for additional guidance.

       The only other hard requirements is the presence of on specific method in order to be a valid subclass of
       AuxdataBaseClass:


           get_l2_track_vars(l2)

               This method will be called during the Level-2 processor. The argument is the Level-2 data object and
               the purpose of the method is to compute the auxilary variable(s) and associated uncertainty. These
               variable need to be registered using the `register_auxvar(id, name, value, uncertainty)` method of
               the base class. All MSS subclasses need to register at minimum the following variable:

               region code (integer):
                   id: reg_code
                   name: region_code

               e.g., this code line is mandatory for `get_l2_track_vars` (uncertainty is None):

                   # Register Variables
                   self.register_auxvar("reg_code", "region_code", value, None)



Classes
-------

.. autoapisummary::

   pysiral.auxdata.region.NSIDCRegionMask
   pysiral.auxdata.region.NSIDCRegionMask2021
   pysiral.auxdata.region.AntarcticSeas


Module Contents
---------------

.. py:class:: NSIDCRegionMask(*args: Optional[Any], **kwargs: Optional[Any])

   Bases: :py:obj:`pysiral.auxdata.AuxdataBaseClass`


   Provides region codes from NSIDC style region grids 


   .. py:attribute:: nc


   .. py:method:: get_l2_track_vars(l2: Level2Data) -> None

      API method to map gridded region id on the trajectory
      :param l2:
      :return:



.. py:class:: NSIDCRegionMask2021(*args: Optional[Any], **kwargs: Optional[Any])

   Bases: :py:obj:`pysiral.auxdata.AuxdataBaseClass`


   Provides region codes from NSIDC regions grids in version 2021 


   .. py:attribute:: filepath


   .. py:attribute:: nc


   .. py:attribute:: attr_dict
      :type:  Dict


   .. py:attribute:: grid_def
      :type:  Dict


   .. py:method:: get_l2_track_vars(l2: Level2Data) -> None

      API method to map gridded region id on the trajectory
      :param l2:
      :return:



   .. py:method:: get_trajectory(longitude: numpy.ndarray, latitude: numpy.ndarray) -> numpy.ndarray

      Extract the region code along a trajectory defined by longitude & latitude.

      :param longitude: Longitude of the trajectory points
      :param latitude: Latitude of the trajectory points

      :raises None:

      :return: The region code extracted along the trajectory



   .. py:method:: _get_filepath_from_config() -> pathlib.Path

      Get the full file path from the options dictionary

      :return: Full path to the mask file



   .. py:method:: _extract_grid_information() -> Dict

      Extract the grid definition from the netCDF file.

      Example for a grid definition dictionary

          projection:
              proj: stere
              lon_0: -45
              lat_0: 90
              lat_ts: 70
              a: 6378273
              b: 6356889.44891
          dimension:
              n_cols: 304
              n_lines: 448
              dx: 25000
              dy: 25000

      :return: grid definition dictionary



   .. py:method:: _extract_grid_attributes() -> Dict

      Extract the attributes for the region id variable from the netCDF file

      :return: grid variable attribute dictionary



.. py:class:: AntarcticSeas(*args: Optional[Any], **kwargs: Optional[Any])

   Bases: :py:obj:`pysiral.auxdata.AuxdataBaseClass`


   Provides region codes for the *southern hemisphere only* based on longitude ranges
   from Antarctic Seas (source: Stefanie Arndt, AWI, pers comm).


   .. py:method:: get_l2_track_vars(l2: Level2Data) -> None

      API method, will return the region cose based on longitude and latitude values.
      The location of the sea, the corresponding code and names are defined in the
      auxiliary data catalog `auxdata_def.yaml` in the pysiral resources directory.

      The expected structure of the options is:

      options:
          ice_free_ocean_code: 1
          region_def:
              # To be read as: [region code, region label, lon_min, lon_max, lat_limit]
              - [1, "Indian Ocean", 20.0,  90.0, -50.]
              - ...

      :param l2:
      :return:



   .. py:method:: get_angular_distance(lon1: Union[float, int, numpy.array], lon2: Union[float, int, numpy.array]) -> Union[float, int, numpy.array]
      :staticmethod:


      Return the angular distance between two longitude values that
      follow come in units of degrees east and degrees west
      :param lon1:
      :param lon2:
      :return: angular distance