hist.intervals module#

hist.intervals.clopper_pearson_interval(num: np.typing.NDArray[Any], denom: np.typing.NDArray[Any], coverage: float | None = None) np.typing.NDArray[Any]#

Compute the Clopper-Pearson coverage interval for a binomial distribution. c.f. http://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval

Parameters
  • num – Numerator or number of successes.

  • denom – Denominator or number of trials.

  • coverage – Central coverage interval. Default is one standard deviation, which is roughly 0.68.

Returns

The Clopper-Pearson central coverage interval.

hist.intervals.poisson_interval(values: np.typing.NDArray[Any], variances: np.typing.NDArray[Any] | None = None, coverage: float | None = None) np.typing.NDArray[Any]#

The Frequentist coverage interval for Poisson-distributed observations.

What is calculated is the “Garwood” interval, c.f. V. Patil, H. Kulkarni (Revstat, 2012) or http://ms.mcmaster.ca/peter/s743/poissonalpha.html. If variances is supplied, the data is assumed to be weighted, and the unweighted count is approximated by values**2/variances, which effectively scales the unweighted Poisson interval by the average weight. This may not be the optimal solution: see 10.1016/j.nima.2014.02.021 (arXiv:1309.1287) for a proper treatment.

In cases where the value is zero, an upper limit is well-defined only in the case of unweighted data, so if variances is supplied, the upper limit for a zero value will be set to NaN.

Parameters
  • values – Sum of weights.

  • variances – Sum of weights squared.

  • coverage – Central coverage interval. Default is one standard deviation, which is roughly 0.68.

Returns

The Poisson central coverage interval.

hist.intervals.ratio_uncertainty(num: np.typing.NDArray[Any], denom: np.typing.NDArray[Any], uncertainty_type: Literal['poisson', 'poisson-ratio', 'efficiency'] = 'poisson') Any#

Calculate the uncertainties for the values of the ratio num/denom using the specified coverage interval approach.

Parameters
  • num – Numerator or number of successes.

  • denom – Denominator or number of trials.

  • uncertainty_type

    Coverage interval type to use in the calculation of the uncertainties.

    • "poisson" (default) implements the Garwood confidence interval for a Poisson-distributed numerator scaled by the denominator. See hist.intervals.poisson_interval() for further details.

    • "poisson-ratio" implements a confidence interval for the ratio num / denom assuming it is an estimator of the ratio of the expected rates from two independent Poisson distributions. It over-covers to a similar degree as the Clopper-Pearson interval does for the Binomial efficiency parameter estimate.

    • "efficiency" implements the Clopper-Pearson confidence interval for the ratio num / denom assuming it is an estimator of a Binomial efficiency parameter. This is only valid if the entries contributing to num are a strict subset of those contributing to denom.

Returns

The uncertainties for the ratio.