:py:mod:`tape.analysis.base`
============================

.. py:module:: tape.analysis.base

.. autoapi-nested-parse::

   Contains the base class for analysis functions.



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

Classes
~~~~~~~

.. autoapisummary::

   tape.analysis.base.AnalysisFunction




.. py:class:: AnalysisFunction


   Bases: :py:obj:`abc.ABC`, :py:obj:`Callable`

   Base class for analysis functions.

   Analysis functions are functions that take few arrays representing
   an object and return a single pandas.Series representing the result.

   .. method:: cols(ens) -> List[str]

      Return the columns that the analysis function takes as input.

   .. method:: meta(ens) -> pd.DataFrame

      Return the metadata pandas.DataFrame required by Dask to pre-build
      a computation graph. It is basically the schema for calculate() method
      output.

   .. method:: on(ens) -> List[str]

      Return the columns to group source table by.
      Typically, `[ens._id_col]`.

   .. method:: __call__(*cols, \*\*kwargs)

      Calculate the analysis function.


   .. py:method:: cols(ens: Ensemble) -> List[str]
      :abstractmethod:

      Return the column names that the analysis function takes as input.

      :param ens: The ensemble object, it could be required to get column names of
                  the "special" columns like `ens._time_col` or `ens._err_col`.
      :type ens: Ensemble

      :returns: The column names to select and pass to .calculate() method.
                For example `[ens._time_col, ens._flux_col]`.
      :rtype: List[str]


   .. py:method:: meta(ens: Ensemble)
      :abstractmethod:

      Return the schema of the analysis function output.

      :param ens: The ensemble object.
      :type ens: Ensemble

      :returns: **pd.DataFrame or (str, dtype) tuple or {str** -- Dask meta, for example
                `pd.DataFrame(columns=['x', 'y'], dtype=float)`.
      :rtype: dtype} dictionary


   .. py:method:: on(ens: Ensemble) -> List[str]
      :abstractmethod:

      Return the columns to group source table by.

      :param ens: The ensemble object.
      :type ens: Ensemble

      :returns: The column names to group by. Typically, `[ens._id_col]`.
      :rtype: List[str]


   .. py:method:: __call__(*cols, **kwargs)
      :abstractmethod:

      Calculate the analysis function.

      :param \*cols: The columns to calculate the analysis function on. It must be
                     consistent with .cols(ens) output.
      :type \*cols: array_like
      :param \*\*kwargs: Additional keyword arguments.

      :returns: The result, it must be consistent with .meta() output.
      :rtype: pd.Series or pd.DataFrame or array or value