pesummary.gw.classification module

The pesummary.gw.classification module allows for classification probabilities to be generated directly from a set of posterior samples. We calculate probability that the source is a binary black hole (BBH), binary neutron star (BNS), neutron star black hole (NSBH) and/or lies within the lower mass gap (MassGap) by interacting with the PEPredicates package. We also calculate the probability that the binary contains at least one neutron star (HasNS) and the probability that the binary has a visible remnant (HasRemnant) by interacting with the p-astro package. pesummary provides 3 classes for calculating classification probabilities: pesummary.gw.classification.PEPredicates, pesummary.gw.classification.PAstro and pesummary.gw.classification.Classify as well as a helper pesummary.gw.classification.classify function. We discuss each of them below.

pesummary.gw.classification.PEPredicates

We may calculate the probability that the binary is a BBH, BNS, NSBH and/or lies within the lower mass gap by passing a set of posterior samples to the pesummary.gw.classification.PEPredicates class,

>>> from pesummary.gw.classification import PEPredicates
>>> x = PEPredicates(
...    {
...        "mass_1_source": [20, 30], "mass_2_source": [10, 20],
...        "a_1": [0.5, 0.2], "a_2": [0.3, 0.1], "redshift": [0.4, 0.2]
...    }
... )
>>> print(x.classification())
{'BNS': 0.0, 'NSBH': 0.0, 'BBH': 1.0, 'MassGap': 0.0}

We may also see how these probabilities change if we reweigh the posterior samples to a population inferred prior by passing the population=True kwarg,

>>> print(x.classification(population=True))
{'BNS': 0.0, 'NSBH': 0.0, 'BBH': 1.0, 'MassGap': 0.0}

If we wish to calculate the probabilities for both the raw samples and the reweighted posterior samples in a single command, we can use the dual_classification() method,

>>> print(x.dual_classification())
{'default': {'BNS': 0.0, 'NSBH': 0.0, 'BBH': 1.0, 'MassGap': 0.0}, 'population': {'BNS': 0.0, 'NSBH': 0.0, 'BBH': 1.0, 'MassGap': 0.0}}

class pesummary.gw.classification.PEPredicates(samples)[source]

Class for generating source classification probabilities, i.e. the probability that it is consistent with originating from a binary black hole, p(BBH), neutron star black hole, p(NSBH), binary neutron star, p(BNS), or a binary originating from the mass gap, p(MassGap)

Parameters:: samples (dict) – dictionary of posterior samples to use for generating classification probabilities

available_plots

list of available plotting types

Type:: list

classification:: return a dictionary containing the classification probabilities. These probabilities can either be generated from the raw samples or samples reweighted to a population inferred prior

dual_classification:: return a dictionary containing the classification probabilities generated from the raw samples (‘default’) and samples reweighted to a population inferred prior (‘population’)

plot:: generate a plot showing the classification probabilities

pesummary.gw.classification.PAstro

Similar to the pesummary.gw.classification.PEPredicates class the pesummary.gw.classification.PAstro class can be used to calculate the probability that the source has a neutron star and visible remnant by passing a set of posterior samples,

>>> from pesummary.gw.classification import PAstro
>>> x = PAstro(
...    {
...        "mass_1_source": [20, 30], "mass_2_source": [10, 20],
...        "a_1": [0.5, 0.2], "a_2": [0.3, 0.1], "redshift": [0.4, 0.2]
...    }
... )
>>> print(x.classification())
{'HasNS': 0.0, 'HasRemnant': 0.0}

We may again calculate the probabilities with samples reweighted to a population prior with,

>>> print(x.classification(population=True))
{'HasNS': 0.0, 'HasRemnant': 0.0}

and the combination can be printed with,

>>> print(x.dual_classification())
{'default': {'HasNS': 0.0, 'HasRemnant': 0.0}, 'population': {'HasNS': 0.0, 'HasRemnant': 0.0}}

class pesummary.gw.classification.PAstro(samples)[source]

Class for generating EM-Bright classification probabilities, i.e. the probability that the binary has a neutron star, p(HasNS), and the probability that the remnant is observable, p(HasRemnant).

Parameters:: samples (dict) – dictionary of posterior samples to use for generating classification probabilities

available_plots

list of available plotting types

Type:: list

classification:: return a dictionary containing the classification probabilities. These probabilities can either be generated from the raw samples or samples reweighted to a population inferred prior

dual_classification:: return a dictionary containing the classification probabilities generated from the raw samples (‘default’) and samples reweighted to a population inferred prior (‘population’)

plot:: generate a plot showing the classification probabilities

pesummary.gw.classification.Classify

The pesummary.gw.classification.Classify class combines the pesummary.gw.classification.PEPredicates and pesummary.gw.classification.PAstro classes into one and returns the probability that the binary is a BBH, BNS, NSBH and/or lies within the lower mass gap as well as probability that the source has a neutron star and visible remnant. For example,

>>> from pesummary.gw.classification import Classify
>>> x = Classify(
...    {
...        "mass_1_source": [20, 30], "mass_2_source": [10, 20],
...        "a_1": [0.5, 0.2], "a_2": [0.3, 0.1], "redshift": [0.4, 0.2]
...    }
... )
>>> print(x.classification())
{'BNS': 0.0, 'NSBH': 0.0, 'BBH': 1.0, 'MassGap': 0.0, 'HasNS': 0.0, 'HasRemnant': 0.0}
>>> print(x.classification(population=True))
{'BNS': 0.0, 'NSBH': 0.0, 'BBH': 1.0, 'MassGap': 0.0, 'HasNS': 0.0, 'HasRemnant': 0.0}
>>> print(x.dual_classification())
{'default': {'BNS': 0.0, 'NSBH': 0.0, 'BBH': 1.0, 'MassGap': 0.0, 'HasNS': 0.0, 'HasRemnant': 0.0}, 'population': {'BNS': 0.0, 'NSBH': 0.0, 'BBH': 1.0, 'MassGap': 0.0, 'HasNS': 0.0, 'HasRemnant': 0.0}}

class pesummary.gw.classification.Classify(samples)[source]

Class for generating source classification and EM-Bright probabilities, i.e. the probability that it is consistent with originating from a binary black hole, p(BBH), neutron star black hole, p(NSBH), binary neutron star, p(BNS), or a binary originating from the mass gap, p(MassGap), the probability that the binary has a neutron star, p(HasNS), and the probability that the remnant is observable, p(HasRemnant).

check_for_install(*args, **kwargs)[source]

Check that the required package is installed. If the package is not installed, raise an ImportError

Parameters:: package (str, optional) – name of package to check for install. Default None

classification(**kwargs)[source]

return a dictionary containing the classification probabilities. These probabilities can either be generated from the raw samples or samples reweighted to a population inferred prior

Parameters:

population (Bool, optional) – if True, reweight the samples to a population informed prior and then calculate classification probabilities. Default False
return_samples (Bool, optional) – if True, return the samples used as well as the classification probabilities

pesummary.gw.classification.classify

The pesummary.gw.classification.classify function provides an easy-to-use interface to the classification method provides by the pesummary.gw.classification.Classify class. For example,

. code-block:: python

>>> from pesummary.gw.classification import classify
>>> posterior = {
...     "mass_1_source": [20, 30], "mass_2_source": [10, 20],
...     "a_1": [0.5, 0.2], "a_2": [0.3, 0.1], "redshift": [0.4, 0.2]
... }
>>> print(classify(posterior))
{'BNS': 0.0, 'NSBH': 0.0, 'BBH': 1.0, 'MassGap': 0.0, 'HasNS': 0.0, 'HasRemnant': 0.0}
>>> print(classify(posterior, population=True))
{'BNS': 0.0, 'NSBH': 0.0, 'BBH': 1.0, 'MassGap': 0.0, 'HasNS': 0.0, 'HasRemnant': 0.0}