pysiral.l1preproc.procitems
===========================

.. py:module:: pysiral.l1preproc.procitems

.. autoapi-nested-parse::

   This module contains the basic functionality of Level-1 (pre-)processor items.

   A processor item is a class that is allowed to modify the Level-1 data object
   and can be called at different stages of the Level-1 pre-processor loop.
   The classes are initialized when the Level-1 processor is started and
   thus are allowed to map larger data sets to memory which are then applied
   for each Level-1 data set.

   Processing items can be anywhere in the pysiral namespace, but must
   inherit `pysiral.l1preproc.procitems.L1PProcItem` and overwrite the
   `apply(l1)` method, which receives the Level-1 data object as input.

   Level-1 processor items are instanced from the Level-1 pre-processor
   definition file (located in `pysiral/resources/pysiral-cfg/proc/l1`)
   and require an entry according to this format:

   ```yaml
   level1_preprocessor:

       ...

       options:

           ...

           processing_items:

               - label: <Label displayed in the log file>
                 stage: <stage name (see below)>
                 module_name: <the module where the class is located>
                 class_name: <class name>
                 options:
                     <custom option dictionary (can be nested)>
   ```

   The value (stage name) supplied to `stage` defined whne the processing item
   is run in the main loop of the Level-1 pre-processor. Following options
   are currently implemented:

   1. The processing item will be applied to the Level-1 data object, which
      is has the same extent as the source file (stage=`post_source_file`).
   2. The processing item will be applied to a list of all polar ocean segments
      of a source file (stage=`post_ocean_segment_extraction`). This option is
      recommended for computation intensive processing items.
   3. The processing item will be applied to the merged polar ocean segment
      (stage=`post_merge`)



Attributes
----------

.. autoapisummary::

   pysiral.l1preproc.procitems.L1PPROCITEM_CLS_TYPE


Classes
-------

.. autoapisummary::

   pysiral.l1preproc.procitems.L1PProcItem
   pysiral.l1preproc.procitems.L1PProcItemDef


Functions
---------

.. autoapisummary::

   pysiral.l1preproc.procitems.get_l1_proc_item


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

.. py:class:: L1PProcItem(**cfg: Dict)

   Bases: :py:obj:`object`


   .. py:attribute:: cfg


   .. py:method:: apply(l1: pysiral.l1data.Level1bData)
      :abstractmethod:


      Mandatory class for Level-1 processing item. Needs to be overwritten
      by the inheriting class.
      :param l1:
      :return:



   .. py:method:: __getattr__(item: str) -> Any

      Direct attribute access to the cfg dictionary. Required for historical reasons
      and readable code.

      :param item:
      :return:



.. py:data:: L1PPROCITEM_CLS_TYPE

.. py:class:: L1PProcItemDef(label: str, stage: str, module_name: str, class_name: str, options_dict: dict = None)

   Bases: :py:obj:`object`


   Class for validating and processing Level-1 Pre-Processor item definition


   .. py:attribute:: label


   .. py:attribute:: stage


   .. py:attribute:: module_name


   .. py:attribute:: class_name


   .. py:attribute:: option_dict


   .. py:method:: from_l1procdef_dict(procdef_dict: Union[dict, pysiral.core.legacy_classes.AttrDict]) -> L1PProcItemDef
      :classmethod:


      Initialize the class from the corresponding excerpt of the Level-1 processor
      configuration file.
      :param procdef_dict:
      :return:



   .. py:method:: get_initialized_processing_item_instance() -> L1PPROCITEM_CLS_TYPE

      Return an inialized instance of the processor item described by this
      configuration class

      :return: descendent of L1PProcItem



   .. py:property:: valid_stages


.. py:function:: get_l1_proc_item(module_name: str, class_name: str, **cfg: Dict) -> L1PPROCITEM_CLS_TYPE

   A function returning an initialized processor item class

   :param module_name:
   :param class_name:
   :param cfg:

   :return: The initialized processor item class

   :raises: ValueError