=================
SamplesDict class
=================

`pesummary`'s gw package provides extra functionality to the core
`pesummary.utils.samples_dict.SamplesDict` class. For details about
initializing the `SamplesDict` class and using the core `SamplesDict`
properties, see the `core SamplesDict docs <../core/SamplesDict.html>`_.

Parameter descriptions
----------------------

`pesummary` provides a set of parameter descriptions for most gravitational
wave specific parameters (see `here <./parameters.html>`_). You can access
these descriptions directly from the `SamplesDict` class,

.. code-block:: python

    >>> from pesummary.utils.samples_dict import SamplesDict
    >>> samplesdict = SamplesDict.from_file("path_to_file.hdf5")
    >>> parameters = samplesdict.keys()
    >>> print(parameters[0])
    'mass_1'
    >>> print(parameters[0].description)
    the detector-frame (redshifted) mass of the heavier object

Source classifications
----------------------

`pesummary` provides wrappers for the
`PEPredicates <https://git.ligo.org/will-farr/pepredicates>`_ and
`ligo.em-bright <https://pypi.org/project/ligo.em-bright/`_ packages to calculate
classification probabilities from the samples. We may calculate the
classification probabilities with,

.. code-block:: python

    >>> from pesummary.utils.samples_dict import SamplesDict
    >>> samplesdict = SamplesDict.from_file("path_to_file.hdf5")
    >>> samplesdict.classification()
    {'default': {'BNS': 0.0, 'NSBH': 0.0, 'BBH': 1.0, 'MassGap': 0.0, 'HasNS': 0.0, 'HasRemnant': 1.0}, 'population': {'BNS': 0.0, 'NSBH': 0.0, 'BBH': 1.0, 'MassGap': 0.0, 'HasNS': 0.0, 'HasRemnant': 1.0}}

Where the `default` classification is generated by using the samples directly,
and the `population` classification is generated by reweighing the samples to a
population based prior.
