saftig.evaluation
=================

.. py:module:: saftig.evaluation

.. autoapi-nested-parse::

   Tooling to automate evaluation of filtering techniques on datasets.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/saftig/evaluation/common/index
   /autoapi/saftig/evaluation/evaluation/index


Classes
-------

.. autoapisummary::

   saftig.evaluation.TestDataGenerator


Functions
---------

.. autoapisummary::

   saftig.evaluation.rms
   saftig.evaluation.total_power
   saftig.evaluation.residual_power_ratio
   saftig.evaluation.residual_amplitude_ratio
   saftig.evaluation.measure_runtime


Package Contents
----------------

.. py:function:: rms(a)

   Calculate the root mean square value of an array


.. py:function:: total_power(a)

   calculate the total power of a signal (square or RMS)

   >>> import saftig, numpy
   >>> signal = numpy.ones(10) * 2
   >>> saftig.evaluation.total_power(signal)
   4.0



.. py:class:: TestDataGenerator(witness_noise_level = 0.1, target_noise_level = 0, transfer_function = 1, sample_rate = 1.0, rng_seed = None)

   Generate simple test data for correlated noise mitigation techniques
   The channel count is implicitly defined by the shape of witness_noise_level

   :param witness_noise_level: amplitude ratio of the sensor noise
               to the correlated noise in the witness sensor
               Scalar or 1D-vector for multiple sensors
   :param target_noise_level: amplitude ratio of the sensor noise
               to the correlated noise in the target sensor
   :param transfer_functon: ratio between the amplitude in the target and witness signals
   :param sample_rate: The outputs are referenced
               to an ASD of 1/sqrt(Hz) if a sample rate is provided

   >>> import saftig as sg
   >>> # create data with two witness sensors with relative noise amplitudes of 0.1
   >>> tdg = sg.evaluation.TestDataGenerator(witness_noise_level=[0.1, 0.1])
   >>> # generate a dataset with 1000 samples
   >>> witness, target = tdg.generate(1000)
   >>> witness.shape, target.shape
   ((2, 1000), (1000,))



   .. py:attribute:: rng
      :type:  Any


   .. py:attribute:: witness_noise_level


   .. py:attribute:: target_noise_level


   .. py:attribute:: transfer_function


   .. py:attribute:: sample_rate
      :value: 1.0



   .. py:method:: scaled_whitenoise(shape)

      Generate whitenoise with an ASD of one

      :param shape: shape of the new array

      :return: Array of white noise



   .. py:method:: generate(n)

      Generate sequences of samples

      :param N: number of samples

      :return: witness signal, target signal




.. py:function:: residual_power_ratio(target, prediction, start = None, stop = None, remove_dc = True)

   Calculate the ratio between residual power of the residual and the target signal

   :param target: target signal array
   :param prediction: prediction array (same length as target
   :param start: use only a section of the arrays, start at this index
   :param stop: use only a section of the arrays, stop at this index
   :param remove DC component: remove DC component before calculation


.. py:function:: residual_amplitude_ratio(*args, **kwargs)

   Calculate the ratio between residual amplitude of the residual and the target signal

   :param target: target signal array
   :param prediction: prediction array (same length as target
   :param start: use only a section of the arrays, start at this index
   :param stop: use only a section of the arrays, stop at this index
   :param remove DC component: remove DC component before calculation


.. py:function:: measure_runtime(filter_classes, n_samples = int(10000.0), n_filter = 128, idx_target = 0, n_channel = 1, additional_filter_settings = None, repititions = 1)

   Measure the runtime of filers for a specific scenario
   Be aware that this gives no feedback upon how much multithreading is used!

   :param n_samples: Length of the test data
   :param n_filter: Length of the FIR filters / input block size
   :param idx_target: Position of the prediction
   :param n_channel: Number of witness sensor channels
   :param additional_filter_settings: optional settings passed to the filters
   :param repititions: how manu repititions to perform during the timing measurement

   :return: (time_conditioning, time_apply) each in seconds