poissonregime module¶

poissonregime module.

poissonregime.significance_from_pvalue(pvalue)[source]¶

Return the significance (i.e., the z-score) for a given probability, i.e., the number of standard deviations (sigma) corresponding to the probability

poissonregime.pvalue_from_significance(zscore)[source]¶

Return the probability for a given significance.

poissonregime.significance(n, b, alpha, k=0)[source]¶

Returns the significance for detecting n counts when alpha * b are expected. If k=0 (default), the classic result of Li & Ma (1983) is used. Example:

# expected a 10% success rate in 70 tries. Got 10 hits.
significance(n=10, b=70, alpha=0.1)

If k>0 then eq.7 from Vianello (2018) is used, which assumes that k is the upper boundary on the fractional systematic uncertainty. Example:

# expected a 10% +- 10% success rate in 70 tries. Got 10 hits.
significance(n=10, b=70, alpha=0.1, k=0.1)

If k<0, then alpha * b is assumed to have no uncertainties.

Parameters

n – observed counts (can be an array)
b – expected background counts (can be an array)
alpha – ratio of the source observation efficiency and background observation efficiency (either a float, or an array of the same shape of n)
k – maximum fractional systematic uncertainty expected (either a float, or an array of the same shape of n)

Returns

the significance (z score) for the measurement(s)

poissonregime.posterior(rate, n, b, alpha, exposure=1.0)[source]¶

Returns the posterior of a source count rate for detecting n counts when alpha * b are expected.

Parameters

rate – count rate (can be an array)
n – observed counts (can be an array)
b – expected background counts (can be an array)
alpha – ratio of the source observation efficiency and background observation efficiency
exposure – exposure time, area, volume, or similar to convert the rate to expected source counts. (either a float, or an array of the same shape of n)

Returns

the probability

Knoetig2014, appendix C. A flat prior on the background rate is assumed. https://ui.adsabs.harvard.edu/abs/2014ApJ…790..106K/abstract

poissonregime.uncertainties_rate(k, q=array([0.5, 0.84134475, 0.15865525]), exposure=1.0)[source]¶

Give error bars on the number of events, given k detections.

Parameters

k – number of hits, events, detections or sources.
q – quantile(s) to consider. 0.5 is the median, use pvalue_from_significance to convert from sigma units.
exposure – exposure time, area, volume, or similar to normalise to a rate.

Returns

error bars on the number of events. By default, the median, lower and upper 1 sigma estimates.

Caveat: this assumes a uniform prior on the number of events.

poissonregime.uncertainties_fraction(k, n, q=array([0.5, 0.84134475, 0.15865525]))[source]¶

Give error bars on a fraction, given k positives out of n possible.

Parameters

k – number of hits, events, detections or sources.
n – number of opportunities, total sample size, time bins, slots.
q – quantile(s) to consider. 0.5 is the median, use pvalue_from_significance to convert from sigma units.

Returns

error bars on the fraction. By default, the median, lower and upper 1 sigma estimates.