Feature Pipeline
================

TODO: Workflow description here.


Usage Example
-------------

TODO

.. code-block:: python

    from enstools.feature import FeaturePipeline
    from enstools.feature.identification.STRATEGY import SomeIdentification
    from enstools.feature.tracking.STRATEGY import SomeTracking

    # Configure suitable identification and tracking strategies
    ident_tech = SomeIdentification(...)
    track_tech = SomeTracking(...)

    # Configure the feature pipeline: apply the strategies chosen above and
    # provide an input dataset
    pipeline = FeaturePipeline(processing_mode="2d")
    pipeline.set_identification_strategy(ident_tech)
    pipeline.set_tracking_strategy(track_tech) # omit or set to None if no tracking desired
    pipeline.set_data_path("path/to/input/data.nc") # or directly provide a Dataset with set_data

    # Run the identification and tracking on the data
    pipeline.execute()

    # TODO: output handling


Quickstart
----------

Here is a usage example, if you want to apply existing strategies in the code base to your data set.
First, we need some imports, namely the

- :py:class:`enstools.feature.pipeline.FeaturePipeline`, which executes the identification pipeline
- :py:class:`enstools.feature.identification.template.IdentificationTemplate`, this is the identification strategy, edit this accordingly
- :py:class:`enstools.feature.tracking.template.TrackingTemplate`, this is the tracking strategy, edit this accordingly
- :py:class:`enstools.feature._proto_gen.template_pb2`, this is the on run auto-generated protobuf python file from the set description. Use the one that matches your detection strategy. They are named \*_pb2, where \* is the name of the identification module.

.. warning::

    [TODO] should not really need to set the template here, is specific to identification strategy!

.. code-block:: python

    from enstools.feature.pipeline import FeaturePipeline
    from enstools.feature.identification.template import IdentificationTemplate
    from enstools.feature.tracking.template import TrackingTemplate
    from enstools.feature.identification._proto_gen import template_pb2

Then, we initialize the pipeline with the protobuf description and optional the processing mode. For 3D data, this resembles if identification should be performed individual on 2D (latlon) or 3D subsets.

.. code-block:: python

    pipeline = FeaturePipeline(template_pb2, processing_mode='2d')

Then, we initialize and set our strategies. The tracking can be set to `None` to be ignored.

.. code-block:: python

    i_strat = IdentificationTemplate(some_parameter='foo')
    t_strat = TrackingCompareTemplate()
    pipeline.set_identification_strategy(i_strat)
    pipeline.set_tracking_strategy(t_strat) # or None as argument if no tracking

Next, set the data to process.

.. code-block:: python

    pipeline.set_data_path(path)

Then, the pipeline can be executed, starting the identification and subsequently the tracking.

.. code-block:: python

    pipeline.execute()
    # or separated...
    # pipeline.execute_identification()
    # pipeline.execute_tracking()

This generates an object description based on the set protobuf format. If tracking has been used, tracks based on a default simple heuristic can be generated. See docstrings for further details. The object description holds the objects, and if tracking has been executed a graph structure and the generated tracks respectively.

.. code-block:: python

    pipeline.generate_tracks()
    od = pipeline.get_object_desc()

The output data set and description can be saved:

.. code-block:: python

    pipeline.save_result(description_type='json', description_path=..., dataset_path=...)


Class Documentation
-------------------

.. autoclass:: enstools.feature.pipeline.FeaturePipeline