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}}
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, category_data=None, distance_prior=None, cosmology='Planck15', terrestrial_probability=None, catch_terrestrial_probability_error=False)[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). We use a rate and evidence based estimate, as detailed in https://dcc.ligo.org/LIGO-G2301521 and described below:
The probability for a given classification is simply:
- ..math ::
fraction =
- rac{R_{lpha}Z_{lpha}}{sum_{eta}R_{eta}Z_{eta}}
P(H_{lpha}|d) = (1 - P_{ ext{Terr}}^{pipeline}) fraction
where
- ..math ::
fraction =
rac{p(m_{1s,i},m_{2s,i},z_i|lpha)}{p(m_{1d,i}m_{2d,i},d_{L,i}) imes rac{dd_L}{dz} rac{1}{(1+z_i)^2}}
Z_{lpha}=
rac{Z_{PE}}{N_{samp}}sum_{isim ext{posterior}}^{N_{samp}} fraction
and we use the following straw-person population prior for classifying the sources into different astrophysical categories
- ..math ::
fraction =
- rac{m_{1s}^{lpha}m_{2s}^{eta}}{ ext{min}(m_{1s},m_{2s,max})^{eta+1}-m_{2s,min}^{eta+1}}
p(m_{1s},m_{2s},z|lpha) propto fraction
rac{dV_c}{dz} rac{1}{1+z}
- samples: dict
dictionary of posterior samples to use for generating classification probabilities
- category_data: dict, optional
dictionary of summary data (rates and population hyper parameters) for each category. Default None
- distance_prior: class, optional
class describing the distance prior used when generating the posterior samples. It must have a method ln_prob for returning the log prior probability for a given distance. Default bilby.gw.prior.UniformSourceFrame
- cosmology: str, optional
cosmology you wish to use. Default Planck15
- terrestrial_probability: float, optional
probability that the observed gravitational-wave is of terrestrial origin. Default None.
- catch_terrestrial_probability_error: bool, optional
catch the ValueError raised when no terrestrial_probability is provided. If True, terrestrial_probability is set to 0. Default False
- available_plots: list
list of available plotting types
- classification:
return a dictionary containing 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), 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(rounding=5, **kwargs)[source]
return a dictionary containing the classification probabilities.
- classmethod classification_from_file(filename, **kwargs)[source]
Initiate the classification class with samples stored in file and return a dictionary containing the classification probabilities
- Parameters:
filename (str) – path to file you wish to initiate the classification class with path to file you wish to initiate the classification class with
**kwargs (dict, optional) – all kwargs passed to cls.from_file()
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}