GWForge.population_fisher.population_fisher_term_I
==================================================

.. py:module:: GWForge.population_fisher.population_fisher_term_I

.. autoapi-nested-parse::

   The Term-I population Fisher matrix.



Attributes
----------

.. autoapisummary::

   GWForge.population_fisher.population_fisher_term_I.CONDITION_NUMBER_WARNING
   GWForge.population_fisher.population_fisher_term_I.DEFAULT_RCOND
   GWForge.population_fisher.population_fisher_term_I.DEGENERACY_THRESHOLD


Classes
-------

.. autoapisummary::

   GWForge.population_fisher.population_fisher_term_I.PopulationFisherResult


Functions
---------

.. autoapisummary::

   GWForge.population_fisher.population_fisher_term_I.covariance_from_fisher
   GWForge.population_fisher.population_fisher_term_I.population_fisher


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

.. py:data:: CONDITION_NUMBER_WARNING
   :value: 100000000000000.0


.. py:data:: DEFAULT_RCOND
   :value: 1e-12


.. py:data:: DEGENERACY_THRESHOLD
   :value: 1e-10


.. py:class:: PopulationFisherResult(parameter_names, fixed_parameters, fiducial, fisher, covariance, condition_number, n_events, n_total, scores, mean_score, degenerate)

   Everything :func:`population_fisher` computed, and how to read it.

   :ivar parameter_names: Free hyper-parameters, in matrix order.
   :vartype parameter_names: list of str
   :ivar fixed_parameters: Hyper-parameters held fixed, excluded from the matrix.
   :vartype fixed_parameters: dict
   :ivar fiducial: Values the Fisher was evaluated at, free and fixed together.
   :vartype fiducial: dict
   :ivar fisher: ``(n, n)`` Term-I Fisher matrix.
   :vartype fisher: numpy.ndarray
   :ivar covariance: Its inverse (or pseudo-inverse).
   :vartype covariance: numpy.ndarray
   :ivar sigma: Name to one-sigma marginalised uncertainty.
   :vartype sigma: dict
   :ivar condition_number:
   :vartype condition_number: float
   :ivar n_events: Events with finite scores, i.e. those that entered the sum.
   :vartype n_events: int
   :ivar n_total: Events offered, before the support and finiteness cuts.
   :vartype n_total: int
   :ivar scores: ``(n_events, n)`` raw, uncentred scores.
   :vartype scores: numpy.ndarray
   :ivar mean_score: ``(n,)``; the Monte-Carlo estimate of ``d ln alpha / d Lambda``.
   :vartype mean_score: numpy.ndarray
   :ivar degenerate: Free parameters whose centred score vanished.

   :vartype degenerate: list of str


   .. py:attribute:: parameter_names


   .. py:attribute:: fixed_parameters


   .. py:attribute:: fiducial


   .. py:attribute:: fisher


   .. py:attribute:: covariance


   .. py:attribute:: condition_number


   .. py:attribute:: n_events


   .. py:attribute:: n_total


   .. py:attribute:: scores


   .. py:attribute:: mean_score


   .. py:attribute:: degenerate


   .. py:attribute:: sigma


   .. py:method:: from_pickle(path)
      :classmethod:


      Reload a forecast that :file:`bin/gwforge_population_fisher` saved.

      :param path: A pickle written by the CLI.
      :type path: str

      :rtype: PopulationFisherResult



   .. py:method:: correlation_matrix()

      Correlation matrix implied by :attr:`covariance`.



   .. py:method:: scaled_to(n_events)

      This forecast rescaled to a different number of detected events.

      :param n_events:
      :type n_events: int

      :rtype: PopulationFisherResult



   .. py:method:: summary()

      A plain-text table of the forecast.

      :rtype: str



.. py:function:: covariance_from_fisher(fisher, names=None, rcond=DEFAULT_RCOND)

   Invert a Fisher matrix, falling back to a pseudo-inverse when it is singular.

   :param fisher:
   :type fisher: numpy.ndarray
   :param names: Used only to name parameters in the warning.
   :type names: sequence of str or None
   :param rcond:
   :type rcond: float

   :returns: ``(covariance, condition_number)``.
   :rtype: tuple


.. py:function:: population_fisher(model, events, free_parameters=None, fixed_parameters=None, parameters=None, method='auto', rcond=DEFAULT_RCOND, n_total=None)

   Term-I population Fisher matrix for a detected catalogue.

   :param model:
   :type model: GWForge.population_fisher.base.PopulationModel
   :param events: Source parameters of the **detected** events. They must be drawn from
                  the population at ``parameters``, or the centred-score identity that
                  supplies the selection term does not hold.
   :type events: dict
   :param free_parameters: Hyper-parameters to vary. Defaults to every name the model has that is
                           not in ``fixed_parameters``.
   :type free_parameters: sequence of str or None
   :param fixed_parameters: Name to value, held fixed and excluded from the matrix.
   :type fixed_parameters: dict or None
   :param parameters: Fiducial point. Defaults to ``model.fiducial``.
   :type parameters: dict or None
   :param method: Passed to :meth:`~GWForge.population_fisher.base.PopulationModel.score`.
   :type method: str
   :param rcond: Pseudo-inverse threshold.
   :type rcond: float
   :param n_total: Events offered before cuts, for reporting. Defaults to ``len(events)``.
   :type n_total: int or None

   :rtype: PopulationFisherResult

   :raises ValueError: If no parameters are free, or no event has a finite score.