ligo.p_astro module

Module containing the computation of p_astro by source category

class ligo.p_astro.CountPosteriorElements(f_divby_b, buff=1e-15, verbose=True)

Bases: object

Class that collects information of the candidate events on which the FGMC counts posterior is to be built. This information is not specific to a source type.

class ligo.p_astro.MarginalizedPosterior(f_divby_b, prior_type, terr_source, fix_sources={}, buff=1e-15, mcmc=False, verbose=True, **astro_sources)

Bases: ligo.p_astro.Posterior

Class that provides the marginalized FGMC posterior on counts, for any number of dimensions up to the max dimensions allowed by the original multidimensional FGMC posterior. Inherits from the Posterior class. Computes astrophysical probability p_astro, by source category.

getCovariance(categories, posterior='Default', fix_sources='Default')

Function to determine covariance of counts

Parameters

• categories (list of strings) – Keys must match labels of instances of SourceType

• posterior (callable function) – User-defined counts posterior function. Must be constructed in the same way as the posterior function defined in this class, i.e, must take as input a dictionary of counts keyed on labels, etc. The “Default” is to use the posterior function defined in this class.

• fix_sources (dictionary) – Dictionary of pinned sources, with source type labels as keys and numbers (to pin to) as values. Defaults to fix_sources supplied to instantiate this class.

Returns

covariance between Poisson expected counts

Return type

float

getOneDimMean(category, posterior='Default', fix_sources='Default')

Function to determine mean of 1-dimensional marginalized posterior on counts

Parameters

• category (string) – Source category whose marginalized counts posterior is sought. Must match one of the labels of non-pinned sources.

• posterior (callable function) – User-defined counts posterior function. Must be constructed in the same way as the posterior function defined in this class, i.e, must take as input a dictionary of counts keyed on labels, etc. The “Default” is to use the posterior function defined in this class.

• fix_sources (dictionary) – dictionary of pinned sources, with source type labels as keys and numbers (to pin to) as values. Defaults to fix_sources supplied to instantiate this class.

Returns

mean of 1D marginalized posterior

Return type

float

mean(categories, posterior='Default', fix_sources='Default')

Function to determine mean of posterior.

Parameters

• categories (list of strings) – Keys must match labels of instances of SourceType

• posterior (callabel function) – User-defined counts posterior function. Must be constructed in the same way as the posterior function defined in this class, i.e, must take as input a dictionary of counts keyed on labels, etc. The “Default” is to use the posterior function defined in this class.

• fix_sources (dictionary) – dictionary of pinned sources, with source type labels as keys and numbers (to pin to) as values. Defaults to fix_sources supplied to instantiate this class.

Returns

• float – mean of posterior

• Example mean(["BNS"])

• returns <lambda_BNS>

• Example mean(["BNS","BBH"])

• returns <lambda_BNS*lambda_BBH>

• etc.

p_denominator(trigger_idx, **lambdas)

Function returns \(\Lambda_{\mathrm{terr}}w_\mathrm{terr}(j)+\frac{f(j)}{b(j)}\sum_{\alpha}\Lambda_{\alpha}w_{\alpha}(j))\)

Parameters

• trigger_idx (int or numpy array of int) – index of trigger whose p_astro value is sought

• lambdas (dict) – Counts dictionary. Keys must match labels of instances of SourceType class.

Returns

value of p_denominator

Return type

int or numpy array of ints

p_integrand(trigger_idx, categories, **lambdas)

Function combines meth:p_numerator and meth:p_denominator, along with posterior, to construct the integrand for p(astro).

Parameters

• trigger_idx (int or numpy array of ints:) – index (indices) of trigger(s) whose p(astro) value is sought indices correspond to those of f_divby_b numpy array

• categories (list) – list of category labels. Labels must match labels of instances of class:SourceType.

• lambdas (dict) – Counts dictionary. Keys must match labels of instances of class:SourceType.

Returns

Value of p_integrand

Return type

float or numpy array of floats

p_numerator(trigger_idx, categories, **lambdas)

Function combines pastro_numerator and pterr_numerator, depending on list of categories over which p_astro is to be computed

Parameters

• trigger_idx (int or numpy array of ints:) – index (indices) of trigger(s) whose p(astro) value is sought indices map to the foreground/background values in the f_divby_b vector supplied

• categories (list) – list of category labels. Labels must match labels of instances of SourceType class

• lambdas (dict) – Counts dictionary. Keys must match labels of instances of SourceType class.

Returns

Value of p_numerator evaluated at lambdas.values()

Return type

float or numpy array of floats

pastro(trigger_idx, categories)

Function invokes marginalize_gq to integrate p_integrand and thus determine p(astro)

Parameters

• trigger_idx (int or numpy array of ints) – index (indices) of trigger(s) whose p_astro value is sought indices correspond to those of f_divby_b numpy array

• categories (list) – Category labels. These labels must match those of the instances of the SourceType.

Returns

Value of p_astro

Return type

float or numpy array of floats

pastro_numerator(trigger_idx, categories, **lambdas)

Function returns \(\sum_{\alpha}\Lambda_{\alpha}w_{\alpha}(j)\frac{f(j)}{b(j)}\)

for a trigger j.

Parameters

• trigger_idx (int or array of ints:) – index (indices) of trigger(s) whose p(astro) value is sought indices map to the foreground/background values in the f_divby_b vector supplied

• categories (list) – list of category labels. Labels must match labels of instances of SourceType class

• lambdas (dict) – Counts dictionary. Keys must match labels of instances of SourceType.

Returns

Value of pastro_numerator evaluated at lambdas.values()

Return type

float

pastro_update(categories, bayesfac_dict, mean_values_dict)

Function returns pastro of new candidate event(s), given posterior constructed from events not involving the new candidate event(s).

Parameters

• categories (list) – Category labels. These labels must match those of the instances of the SourceType class.

• bayesfac_dict (dictionary) – Bayesfactor values of the new candidate event, keyed on SourceType labels. There should be a value associated with each astrophysical SourceType used to construct the FGMC posterior.

• mean_values_dict (dictionary) – Mean values of Poisson expected counts of each astrophysical SourceType. There should be a value associated with each astrophysical SourceType used to construct the FGMC posterior.

Returns

Value of p_astro

Return type

float or numpy array of floats

posterior(**lambdas)

FGMC Counts Posterior function. Takes dictionary of counts. Keys must match labels of instances of SourceType.

Posterior can have any dimensionality up to max allowable dimensionality, as determined by the number of SourceType instances passed to the MarginalizedPosterior class.

Parameters

lambdas (dict) – counts:value dictionary pairs. Keys must match labels of instances of SourceType class.

Returns

• float – posterior evaluated at values supplied in the lambda dictionary

• Example (posterior(BNS=5))

• This will give the value for the

• corresponding 1-dimensional marginalized posterior

• Example (posterior(BBH=1,NSBH=3))

• This will give the value for the

• corresponding 2-dimensional marginalized posterior.

pterr_numerator(trigger_idx, lambda_terr)

Function returns \(\Lambda_{\mathrm{terr}}w_{\mathrm{terr}}(j)\) for a trigger j.

Parameters

• trigger_idx (int or array of ints:) – index (indices) of trigger(s) whose p(astro) value is sought indices map to the foreground/background values in the f_divby_b vector supplied

• lambda_terr (float) – value of terrestrial count

Returns

Value of pterr_numerator evaluated at lambda_terr

Return type

float

class ligo.p_astro.Posterior(f_divby_b, prior_type, terr_source, fix_sources={}, buff=1e-15, mcmc=False, verbose=True, **astro_sources)

Bases: ligo.p_astro.CountPosteriorElements

Class that constructs the FGMC counts posterior.

args_fixed

list of object instances whose labels match keys of fix_sources dictionary.

Type

list

args_free

list of object instances whose labels do not match the keys of fix_sources dictionary.

Type

list

arg_terr

pertaining to the terrestrial source

Type

SourceType

args_astro

instances of SourceType that correspond to astrophysical categories.

Type

tuple

keys_all

list of labels of instances of all SourceType instances.

Type

list

key_terr

subset of key_all with terrestrial source type

Type

list

keys_astro

subset of key_all with astrophysical source type

Type

list

keys_fixed

list of labels of pinned SourceType instances.

Type

list

keys_free

list of labels of free SourceType instances.

Type

list

n

number of terms in the gauss-laguerre and gauss-hermite quadrature integrals, hard coded to 20.

Type

int

N

number of candidate events

Type

int

roots

abcissa of gauss-laguerre quadrature

Type

iter

weights

weights of gauss-laguerre quadrature

Type

iter

hroots

abcissa of gauss-hermite quadrature

Type

iter

hweights

weights of gauss-hermite quadrature

Type

iter

reg_const

regularization constant to avoid numerical over/under flows

Type

float

norm

normalization constant for counts posterior, determined post regularization

Type

float

terr_jacobian

constant to be tacked on when integrating terrestrial counts via gauss-hermite quadrature This can only be done after variable transformation.

Type

float

priorDict

dictionary of priors keyed on Uniform and Jeffreys

Type

dict

TerrVarTransform(x, shift_amount='Default')

Variable transformation for lambda_terr. Used when marginalizing over lambda_terr via Gauss-Hermite quadrature.

Parameters

• x (float) – Variable to be transformed

• shift_amount (float) – If shift amount is a, function will transform a Gaussian with mu=a, sigma=np.sqrt(a) to a Gaussian that goes like exp(-x**2)

Returns

transformed variable

Return type

float

gaussianLogWeight(terr_count)

Function that returns the log of the Hermite weights: log(e^(-(x-N)^2/(2N)))

Parameters

terr_count (float) – terrestrial count value

Returns

log of the Gaussian with mean and variance N

Return type

float

marginalize_gq(func, categories, shift_amount='Default', **pinned_lambdas)

Function to marginalize posterior on counts using Gaussian quadrature Gauss-Laguerre for marginalization over astrophysical counts Gauss-Hermite for marginalization over terrestrial counts

Notes

Astrophyical Counts Marginalization (Gauss-Laguerre Quadrature):

\(f(x) = P(x)e^{-x}\)

\(\int_{0}^{\infty}f(x)dx = \sum_{i=1}^{n}w_iP(r_i) = \sum_{i=1}^{n}e^{\log(w_i)+\log(P(r_i))}\)

where \(w_i, r_i\) are the Gauss-Laguerre weights and abscissa.

Terrestrial Counts Marginalization (Gauss-Hermite):

\(f(x) = P(x)e^{-x^2}\)

\(\int_{-\infty}^{+\infty}f(x)dx = \sum_{i=1}^{n}w_iP(r_i) = \sum_{i=1}^{n}e^{\log(w_i)+\log(P(r_i))}\)

where \(w_i, r_i\) are the Gauss-Hermite weights and abscissa.

Parameters

• func (callable) – log of function to be marginalized divided by the Gauss-Laguerre weighting factor.

• categories (list) – list of source types to be marginalized over. Strings must match labels of instances of SourceType.

• shift_amount (float) – same as shift amount in TerrVarTransform(), used for marginalizing over lambda_terr

• pinned_lambdas (dict) – values of lambdas that are not to be marginalized over. keys must match labels of instances of SourceType class.

Returns

list of values, which when exponentiated and summed, give the value of the marginalized posterior.

Return type

list

normalize()

Function to normalize FGMC posterior. This is simply the sum of the array (exponentiated) returned by the regularize function, with the regularization constant removed.

poissonLogWeight(**lambdas)

Function that returns the log of the Poisson weights: log(e^(-x)) = -x

Parameters

lambdas (dict) – dictionary of counts and their values

Returns

log of the Poisson weights

Return type

float

static priorJeffreys(**lambdas)

Jeffreys Prior on Counts. Takes dictionary of counts. Keys must match labels of instances of SourceType class.

static priorUniform(**lambdas)

Uniform Prior on Counts. Takes dictionary of counts. Keys must match labels of instances of SourceType class.

reduced_log_likelihood_astro(**lambdas)

The log of the FGMC posterior divided by (np.exp(-np.sum(lambdas))*((N**N)*exp(-N))) Takes the lambdas as input variables. One of the lambdas must be lambda_terr. Also, the keys on lambdas must match the labels of the SourceType instances. So, evaluating the reduced posterior at lambda_bns = 5 will need to be passed as BNS=5, if “BNS” is the label of the corresponding instance of SourceType. Returns the value of the reduced log posterior for a set of lambda values.

reduced_log_likelihood_terr(**lambdas)

The log of the FGMC posterior divided by (np.exp(-np.sum(lambdas))*lambda_terr**N) Takes the lambdas as input variables. One of the lambdas must be lambda_terr. Also, the keys on lambdas must match the labels of the SourceType instances.

Evaluating the reduced posterior at lambda_bns = 5 will need to be passed as BNS=5, if “BNS” is the label of the corresponding instance of SourceType. Returns the value of the reduced log posterior for a set of lambda values.

regularize()

Function to regularize FGMC posterior to avoid numerical over-/under-flows. It simply invokes marginalize_gq and applies it on the reduced log posterior. The regularization constant is simply the max value of the array returned by this function.

class ligo.p_astro.SourceType(label, w_fgmc)

Bases: object

Class that collects source-type specific information of candidate events. Instances of this class will be passed to the Posterior class to instantiate the latter.