===============================
Filtering parameters management
===============================

.. figure:: /_static/filtering.png

-----------------
Filtering methods
-----------------
Filtering methods aim at attaching quality factors to each data point in the input dataset (see scheme above). Each :class:`FilteringMethod <palantir.filters.base.FilteringMethod>` class comes with a :class:`ParamSet <palantir.filters.base.Method.ParamsSet>` containing the necessary parameters.

As of now (September 2024), four filtering methods are implemented :

####################
Fat Filtering method
####################
The :class:`FatFilterMethod <palantir.filters.fat_filter.FatFilterMethod>` method consists in cutting out the data out of the bounds defined by the fat_filter parameter.

.. figure:: /_static/fat_filter.png

.. doctest::

   >>> import palantir.filters as filters

   >>> method = filters.fat_filter.FatFilterMethod()
   >>> method.getAsDict()

###################
Good periods method
###################
The :class:`GoodPeriodsMethod <palantir.filters.good_periods.GoodPeriodsMethod>` method removes bad periods from the trace detecting regions of non-stationary quality 

.. figure:: /_static/good_periods.png

.. doctest::

   >>> import palantir.filters as filters

   >>> method = filters.good_periods.GoodPeriodsMethod()
   >>> method.getAsDict()

###############
Restrict method
###############

:class:`RestrictMethod <palantir.filters.good_periods.RestrictMethod>`

.. doctest::

   >>> import palantir.filters as filters

   >>> method = filters.good_periods.RestrictMethod()
   >>> method.getAsDict()

##################
Cycle slips method
##################

:class:`CycleSlipsMethod <palantir.filters.cycle_slips.CycleSlipsMethod>`

.. doctest::

   >>> import palantir.filters as filters

   >>> method = filters.cycle_slips.CycleSlipsMethod()
   >>> method.getAsDict()

------------------
Default parameters
------------------
Each :class:`Observable <palantir.workflow.Observable>` instance has its own default filtering parameters attached in a .yml file on the computing server. `See the wiki <https://refimeve-wiki.obspm.fr/doku.php?id=wiki:supervision:welcome#parametrage_des_filtres_de_qualite_par_defaut>`_ for more information.

Given an :class:`Observable <palantir.workflow.Observable>` instance, here is how the filtering parameters can be read.

.. doctest::

   >>> observable.timeChunk.filteringMethods

--------------------
Customize parameters
--------------------

To customize filtering parameters, we must start from an existing :class:`Observable <palantir.workflow.Observable>` instance and its default associated filtering methods (`See the wiki <https://refimeve-wiki.obspm.fr/doku.php?id=wiki:supervision:welcome#parametrage_des_filtres_de_qualite_par_defaut>`_ for more information).

First, let's start from an :class:`Observable <palantir.workflow.Observable>` instance, here :class:`E2EObservable <palantir.links.E2EObservable>`

.. doctest::

   >>> import palantir.links as links
   
   >>> startDate = '240128'
   >>> endDate = '240128'
   >>> startTime = '000000'
   >>> endTime = '100000'
   
   >>> STH2_ID = 1
   >>> fiberLinkProcessor = links.E2E_Freelink(STH2_ID, startDate, endDate, startTime, endTime, 'UTC')
   >>> observable = fiberLinkProcessor.e2e

Then, we get its default :class:`TimeChunk <palantir.filters.base.TimeChunk>` as a dictionary, fed from its associated .yml file

.. doctest::

   >>> observable.loadDefaultTimeChunk()
   >>> timeChunkDict = observable.timeChunk.getAsDict()

Finally, let's update the __filter\_fat__ parameter of the dictionary that will later feed a :class:`FatFilterMethod <palantir.filters.fat_filter.FatFilterMethod>` instance.

.. doctest::

   >>> timeChunkDict["methods"][1]["parameters"]["filter_fat"] = 9e-16
   >>> observable.process(e2eTimeChunk=timeChunkDict)