pysiral.mask
============

.. py:module:: pysiral.mask

.. autoapi-nested-parse::

   All about mask files

   Created on Thu Sep 28 14:00:52 2017

   @author: shendric



Classes
-------

.. autoapisummary::

   pysiral.mask.MaskSourceBase
   pysiral.mask.MaskLandSea2Min
   pysiral.mask.MaskW99Valid
   pysiral.mask.L3Mask
   pysiral.mask.L1PHighResolutionLandMask


Functions
---------

.. autoapisummary::

   pysiral.mask.MaskSourceFile


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

.. py:function:: MaskSourceFile(mask_name, mask_cfg)

   Wrapper method for different mask source file classes 


.. py:class:: MaskSourceBase(mask_dir, mask_name, cfg)

   Bases: :py:obj:`pysiral.core.legacy_classes.DefaultLoggingClass`


   Parent class for various source masks. Main functionality is to
   create gridded mask netCDF for level-3 grid definitions 


   .. py:attribute:: _cfg


   .. py:attribute:: _mask_dir


   .. py:attribute:: _mask_name


   .. py:attribute:: _mask
      :value: None



   .. py:attribute:: _area_def
      :value: None



   .. py:attribute:: _post_flipud
      :value: False



   .. py:method:: set_mask(mask, area_def)

      Set grid definition for the mask source grid using pyresample.
      The argument area_def needs to have the attributes needed as arguments
      for pyresample.geometry.AreaDefinition or be of the pyresampe types
      (geometry.AreaDefinition, geometry.GridDefinition) 



   .. py:method:: export_l3_mask(griddef, nc_filepath=None)

      Create a gridded mask product in pysiral compliant filenaming.
      The argument griddef is needs to be a pysiral.grid.GridDefinition
      instance 



   .. py:method:: _write_netcdf(nc_filepath, griddef, mask)

      Write a netCDF file with the mask in the target
      grid projections



   .. py:property:: cfg


   .. py:property:: mask_name


   .. py:property:: mask_dir


   .. py:property:: source_mask


   .. py:property:: source_area_def


.. py:class:: MaskLandSea2Min(mask_dir, mask_name, cfg)

   Bases: :py:obj:`MaskSourceBase`


   A land/sea mask based on a binary file on a 2 minute grid.
   Content of orignial mask: (0: sea, 1: lakes, 2: land ice: 3: land)
   There seems to be a few issues with the land ice mask in some places,
   therefore we limit the mask to 0: sea, 1: mixed, 2: non-sea (land) 


   .. py:method:: construct_source_mask()

      Read the binary file and set the mask 



   .. py:method:: pp_classify(resampled_mask, *args)
      :staticmethod:


      Post-processing method after resampling to target grid
      The resampled mask contains a land fraction (datatype float), which
      needs to be simplified to the flags (0: ocean, 1: mixed, 2: land) 



   .. py:property:: mask_filepath


.. py:class:: MaskW99Valid(mask_dir, mask_name, cfg)

   Bases: :py:obj:`MaskSourceBase`


   A valid mask for the Warren climatology  


   .. py:method:: pp_limit_lat(resampled_mask, griddef)
      :staticmethod:


      There are some artefacts in the source mask that need to be
      filtered out based on a simple latitude threshold filter.
      We also set all NaN values to 0 and fix a small problem at the
      north pole 



   .. py:property:: mask_filepath


.. py:class:: L3Mask(mask_name, grid_id, flipud=False)

   Bases: :py:obj:`pysiral.core.legacy_classes.DefaultLoggingClass`


   Container for Level-3 mask compliant netCDF files
   (see output of pysiral.mask.MaskSourceBase.export_l3_mask) 


   .. py:attribute:: error


   .. py:attribute:: _mask_name


   .. py:attribute:: _grid_id


   .. py:attribute:: _flipud
      :value: False



   .. py:method:: _read_mask_netcdf()

      Read the mask 



   .. py:property:: mask


   .. py:property:: lat


   .. py:property:: lon


   .. py:property:: mask_name


   .. py:property:: grid_id


   .. py:property:: mask_filepath


.. py:class:: L1PHighResolutionLandMask(**cfg)

   Bases: :py:obj:`pysiral.l1preproc.procitems.L1PProcItem`


   Level-1 processor item providing access to a high resolution
   land mask and distance to land fields


   .. py:method:: apply(l1: pysiral.l1data.Level1bData) -> None

      Extract land/ocean flag and distance to coast along the l1p trajectory if a mask exists
      for the corresponding hemisphere of the l1p data object.

      The parameters are stored in the classifier data group among the original surface type
      value, which is then update for the mask coverage

      :param l1:
      :return: None



   .. py:method:: get_trajectory(longitude: numpy.typing.NDArray, latitude: numpy.typing.NDArray) -> Tuple[numpy.typing.NDArray, numpy.typing.NDArray]

      Get extract of the land/ocean flag and the distance to coast value for an
      array of (longitude, latitude) positions.

      If longitude, latitude is outside the grid, a pre-defined dummy value will
      be returned.

      :param longitude: Longitude values in degrees
      :param latitude: latitude values in degrees

      :raises None:

      :return: land ocean flag & distance to coast values for longitude, latitude positions