firecrown.likelihood.statistic
==============================

.. py:module:: firecrown.likelihood.statistic

.. autoapi-nested-parse::

   Gaussian Family Statistic Module.

   The Statistic class describing objects that implement methods to compute the
   data and theory vectors for a :class:`GaussFamily` subclass.



Exceptions
----------

.. autoapisummary::

   firecrown.likelihood.statistic.StatisticUnreadError


Classes
-------

.. autoapisummary::

   firecrown.likelihood.statistic.Statistic
   firecrown.likelihood.statistic.GuardedStatistic
   firecrown.likelihood.statistic.TrivialStatistic


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

.. py:exception:: StatisticUnreadError(stat)

   Bases: :py:obj:`RuntimeError`

   .. autoapi-inheritance-diagram:: firecrown.likelihood.statistic.StatisticUnreadError
      :parts: 1


   Error raised when accessing an un-read statistic.

   Run-time error indicating an attempt has been made to use a statistic
   that has not had `read` called in it.


   .. py:attribute:: statistic


.. py:class:: Statistic(parameter_prefix = None)

   Bases: :py:obj:`firecrown.updatable.Updatable`

   .. autoapi-inheritance-diagram:: firecrown.likelihood.statistic.Statistic
      :parts: 1


   The abstract base class for all physics-related statistics.

   Statistics read data from a SACC object as part of a multi-phase
   initialization. They manage a :class:`DataVector` and, given a
   :class:`ModelingTools` object, can compute a :class:`TheoryVector`.

   Statistics represent things like two-point functions and mass functions.


   .. py:attribute:: sacc_indices
      :type:  None | numpy.typing.NDArray[numpy.int64]


   .. py:attribute:: ready
      :value: False



   .. py:attribute:: computed_theory_vector
      :value: False



   .. py:attribute:: theory_vector
      :type:  None | firecrown.data_types.TheoryVector
      :value: None



   .. py:method:: read(_)

      Read the data for this statistic and mark it as ready for use.

      Derived classes that override this function should make sure to call the
      base class method using:

      .. code-block:: python

          super().read(sacc_data)

      as the last thing they do.

      :param _: currently unused, but required by the interface.



   .. py:method:: get_data_vector()
      :abstractmethod:


      Gets the statistic data vector.

      :return: The data vector.



   .. py:method:: compute_theory_vector(tools)

      Compute a statistic from sources, applying any systematics.

      :param tools: the modeling tools used to compute the theory vector.
      :return: The computed theory vector.



   .. py:method:: get_theory_vector()

      Returns the last computed theory vector.

      Raises a RuntimeError if the vector has not been computed.

      :return: The already-computed theory vector.



.. py:class:: GuardedStatistic(stat)

   Bases: :py:obj:`firecrown.updatable.Updatable`

   .. autoapi-inheritance-diagram:: firecrown.likelihood.statistic.GuardedStatistic
      :parts: 1


   An internal class used to maintain state on statistics.

   :class:`GuardedStatistic` is used by the framework to maintain and
   validate the state of instances of classes derived from :class:`Statistic`.


   .. py:attribute:: statistic


   .. py:method:: read(sacc_data)

      Read whatever data is needed from the given :class:`sacc.Sacc` object.

      After this function is called, the object should be prepared for the
      calling of the methods :meth:`get_data_vector` and
      :meth:`compute_theory_vector`.

      :param sacc_data: The SACC data object to read from.



   .. py:method:: get_data_vector()

      Return the contained :class:`Statistic`'s data vector.

      :class:`GuardedStatistic` ensures that :meth:`read` has been called.
      first.

      :return: The most recently calculated  data vector.



   .. py:method:: compute_theory_vector(tools)

      Return the contained :class:`Statistic`'s computed theory vector.

      :class:`GuardedStatistic` ensures that :meth:`read` has been called.
      first.

      :param tools: the modeling tools used to compute the theory vector.
      :return: The computed theory vector.



.. py:class:: TrivialStatistic

   Bases: :py:obj:`Statistic`

   .. autoapi-inheritance-diagram:: firecrown.likelihood.statistic.TrivialStatistic
      :parts: 1


   A minimal statistic only to be used for testing Gaussian likelihoods.

   It returns a :class:`DataVector` and :class:`TheoryVector` each of which is
   three elements long. The SACC data provided to :meth:`TrivialStatistic.read`
   must supply the necessary values.


   .. py:attribute:: count
      :value: 3



   .. py:attribute:: data_vector
      :type:  None | firecrown.data_types.DataVector
      :value: None



   .. py:attribute:: mean


   .. py:attribute:: computed_theory_vector
      :value: False



   .. py:method:: read(sacc_data)

      Read the necessary items from the sacc data.

      :param sacc_data: The SACC data object to be read



   .. py:method:: get_data_vector()

      Return the data vector; raise exception if there is none.

      :return: The data vector.