# 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.