:mod:`distancematrix.calculator`
================================

.. py:module:: distancematrix.calculator


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

Classes
~~~~~~~

.. autoapisummary::

   distancematrix.calculator.AbstractCalculator
   distancematrix.calculator.AnytimeCalculator
   distancematrix.calculator.StreamingCalculator



.. py:class:: AbstractCalculator(self_join, m, num_series_subseq, num_query_subseq, n_dim, trivial_match_buffer=None)

   Bases: :class:`abc.ABC`

   Base class for calculators. A calculator is repsonsible for managing
   consumers and generators for a distance matrix calculation. It provides
   a single point of interaction for the user.

   In order to do useful work, generators and consumers need to be added.
   Generators will use the input query and series to form a distance matrix.
   Consumers process these values in a way that is useful.

   .. method:: add_consumer(self, generator_ids, consumer)

      Adds a consumer that uses the distances calculated by the provided generators.

      :param generator_ids: list containing ids of the generators
      :param consumer: the consumer to add
      :return: the bound consumer


   .. method:: add_generator(self, input_dim, generator)
      :abstractmethod:

      Adds a generator that will use the data from the specified channel (from series/query).

      :param input_dim: index of the data channel
      :param generator: the generator to add
      :return: the bound generator


   .. method:: calculate_columns(self, start=None, upto=1.0, print_progress=False)

      Calculates columns of the distance matrix. The calculator keeps track of the rightmost column that was
      already calculated and will use it as starting position unless the start position is provided.

      Note that the generators are optimised for calculating consecutive columns from left to right.

      :param start: int for absolute position, float for relative position. The first column to calculate.
      If None, continues from the rightmost column that was calculated so far.
      :param upto: int for absolute position, float for relative position. The last column (exclusive) to calculate.
      :param print_progress: print progress to console?
      :return: None


   .. method:: num_dist_matrix_values(self)
      :property:


   .. method:: generators(self)
      :property:


   .. method:: consumers(self)
      :property:



.. py:class:: AnytimeCalculator(m, series, query=None, trivial_match_buffer=None)

   Bases: :class:`distancematrix.calculator.AbstractCalculator`

   Calculator that allows approximate calculations in a fraction of the time, but does not support
   data streaming.

   A calculator is repsonsible for managing
   consumers and generators for a distance matrix calculation. It provides
   a single point of interaction for the user.

   .. method:: add_generator(self, input_dim, generator)

      Adds a generator that will use the data from the specified channel (from series/query).

      :param input_dim: index of the data channel
      :param generator: the generator to add
      :return: the bound generator


   .. method:: calculate_diagonals(self, partial=1.0, print_progress=False)

      Calculates diagonals of the distance matrix. The advantage of calculating diagonals is that values are spread
      over the entire distance matrix, which can provide a quick approximation for any consumer.

      :param partial: int for a number of values, float for relative number of values. The number of distance
      matrix values that should be calculated (including the counts of previous diagonals calulated).
      :param print_progress: print progress to the console
      :return: None



.. py:class:: StreamingCalculator(m, series_window, query_window=None, n_dim=1, trivial_match_buffer=None)

   Bases: :class:`distancematrix.calculator.AbstractCalculator`

   Calculator that allows streaming data, but does not support anytime calculations.

   A calculator is repsonsible for managing
   consumers and generators for a distance matrix calculation. It provides
   a single point of interaction for the user.

   .. method:: add_generator(self, input_dim, generator)

      Adds a generator that will use the data from the specified channel (from series/query).

      :param input_dim: index of the data channel
      :param generator: the generator to add
      :return: the bound generator


   .. method:: append_series(self, values)

      Add more data points to series.

      As a side effect, the last calculated column index is shifted along with the data.

      :param values: 1D array for one data point on each channel, or 2D array of shape (num_dim, num_points)
      :return: None


   .. method:: append_query(self, values)

      Add more data points to query. Cannot be used if performing a self join.

      Note that appending query data does not adjust the last column calculated index.

      :param values: 1D array for one data point on each channel, or 2D array of shape (num_dim, num_points)
      :return: None