API

feldcous module

Stats functions for use in analysis of faint signals in the low-count regime

Dependencies:

numpy 1.17.3 scipy 1.3.1

Sophia Flury 2021.02.20

calc_conf

feldcous.calc_conf(gross, bkg, p_conf, p_det=0.1587)

Name:

calc_conf

Purpose:

Calculate the confidence intervals on a Poisson source with background using Feldman & Cousins if gross > background, bootstrapping if gross < background, or sqrt(gross+background) if source gross > 256.

Arguments:

gross (float):

gross measured counts

bkg (float):

estiamted background counts

p_conf (float):

probability intervals of the desired confidence intervals (e.g., 0.68 for 1-sigma confidence interval)

Keyword Arguments:

p_det (float):

threshold probability for detection. Default is 0.1587.

Returns:

conf_lower (ndarray):

lower confidences on source counts

conf_upper (ndarray):

upper confidences on source counts

calc_det_prob

feldcous.calc_det_prob(sig, bkg)

Name:

calc_det_prob

Purpose:

Calculate the probability that measured counts were sampled from the distribution of background counts.

Arguments:

sig (float):

gross signal counts

bkg (float):

background counts

Returns:

p_nb (float):

probability that the signal is sampled from the background

signif (float):

normal significance corresponding to P(>N|B) assuming a normal distribution

calc_source

feldcous.calc_source(gross, bkg, p_det=0.1587, sigma=1.0)

Name:

calc_source

Purpose:

calculate the confidence intervals on a Poisson source with background using Feldman & Cousins if gross > background, bootstrapping if gross < background, or sqrt(gross+background) if source gross-background > 100.

Arguments:

gross (float):

gross measured counts

bkg (float):

estiamted background counts

bkg_err (float):

uncertainty in background counts

Keyword Arguments:

p_det (float):

threshold probability for detection. Default is 0.1587.

Returns:

src (float):

source counts

src_lower (float):

15.87th percentile error on source counts

src_upper (float):

84.13th percentile error on source counts

cumtrapz

feldcous.cumtrapz(x, y, norm=True)

Name:

cumtrapz

Purpose:

Compute the cumulative integral of a given integrand using trapezoid rule. Optionally normalizes so that the integral goes to 1 over the range of x.

Arguments:

x (ndarray):

integrand abscissa

y (ndarray):

integrand ordinate

Keyword Arguments:

norm (bool):

Optional normalization so that total integral over x is 1.

Returns:

cumint (ndarray):

cumulative integral at each value of x

feldman_cousins

feldcous.feldman_cousins(gross, bkg, p_conf, delta_mu=0.01)

Name:

feldman_cousins

Purpose:

Compute Neyman-Pearson confidence intervals following Feldman & Cousins 1998, Phys.Rev.D.,57,3873, as originally implemented by Worseck et al 2016, ApJ 825, 144, and Makan et al 2020, in C.

Arguments:

gross (float):

measured gross counts

bkg (float):

measured/model background counts

p_conf (float, list, or np.ndarray):

probability confidence interval(s) to evaluate mu

Keyword Arguments:

delta_mu (float):

resolution in the simulated measurements mu. Small values will improve contraints but require much more computation time. Lower limit of 1e-4 and upper limit of sqrt(gross) are imposed for speed and sufficient sampling. Default is delta_mu = 0.01

Returns:

conf_lower (np.ndarray):

1xN array of lower confidence intervals where N is the number of provided confidence values

conf_upper (np.ndarray):

1xN array of upper confidence intervals where N is the number of provided confidence values

invtrans_interp

feldcous.invtrans_interp(x, ll, n_samp=100000)

Name:

inv_trans_interp

Purpose:

Use inverse transform method to sample deviates from a log likelihood function given only a set of nodes defining the log likelihood. CDF is calculated using trapezoid rule. Variable x is interpolated with respect to the CDF to translate uniform deviates into the desired distribution.

Arguments:

x (ndarray):

nodes of variable x at which the log likelihood is known

ll (ndarray):

log likelihood nodes of values x

Keyword Arguments:

n_samp (int):

number of deviates to sample from the interpolated log likelihood distribution

Returns:

samples (ndarray):

samples of log likelihood

poiss_conf_lim

feldcous.poiss_conf_lim(mu, p_conf)

Name:

poiss_conf_lim

Purpose:

Compute confidence limits on a measured/known background for given quantiles assuming the background is the mean of a Poisson distribution.

Arguments:

mu (float):

known/measured counts

p_conf (float or ndarray):

probability intervals of the desired confidence intervals

Returns:

conf_lower (ndarray):

lower confidence intervals

conf_upper (ndarray):

upper confidence intervals

poisson_pmf

feldcous.poisson_pmf(n, mu)

Name:

poisson_pmf

Purpose:

Compute the Poisson probability of getting counts n given some mean mu.

Arguments:

n (float):

number of counts

mu (float):

mean counts of distribution

Returns:

cdf (float):

Poisson probability mass function at n

sample_source

feldcous.sample_source(gross, bkg, p_conf, n_samp=100000, p_det=0.1587)

Name:

sample_source

Purpose:

Sample variates from the likelihood distribution of a measured signal given the gross signal and the background. Determines confidence intervals of the source signal given the gross signal, background, and a range of probabilities for the desired confidence ratios. Builds log likelihood distribution from the confidence intervals and probabilities and samples this likelihood distribution a given number of times.

Arguments:

gross (float):

gross signal

bkg (float):

background noise in signal

p_conf (float or ndarray):

probability intervals of the desired confidence intervals

Keyword Arguments:

n_samp (int):

number of samples to draw from the likelihood distribution

p_det (float):

threshold probability for detection. Default is 0.1587.

Returns:

samples (ndarray):

1xn_samp array of samples of the likelihood distribution for source = gross - background

skellam_cdf

feldcous.skellam_cdf(n, mu1, mu2)

skellam_conf_lim

feldcous.skellam_conf_lim(mu1, mu2, p_conf)

Name:

skellam_conf_lim

Purpose:

Compute confidence limits on a measured/known difference of Poisson variates for given quantiles assuming.

Arguments:

mu1 (float):

known/measured counts 1 (gross signal)

mu1 (float):

known/measured counts 2 (background)

p_conf (float or ndarray):

probability intervals of the desired confidence intervals

Returns:

conf_lower (ndarray):

lower confidence intervals

conf_upper (ndarray):

upper confidence intervals

skellam_pmf

feldcous.skellam_pmf(n, mu1, mu2)

Name:

skellam_pmf

Purpose:

Compute the Skellam probability of getting some difference n between counts given means mu1 and mu2 for two Poisson distributions.

Arguments:

n (float):

number of counts

mu1 (float):

mean counts of distribution 1

mu2 (float):

mean counts of distribution 3

Returns:

pmf (float):

Skellam probability mass function n ~ mu1 - mu2