Module stats 

Running statistics with confidence intervals.

• ErrorRate counts errors among trials of a Bernoulli event (bit, symbol or block errors). Its estimate is $\hat{p} = k/n$ and its interval the Wilson score interval at confidence $1 - \alpha$,

  $$ \frac{\hat{p} + \frac{z^{2}}{2n} \pm z \sqrt{\frac{\hat{p}(1 - \hat{p})}{n} + \frac{z^{2}}{4n^{2}}}}{1 + \frac{z^{2}}{n}}, \qquad z = \Phi^{-1}(1 - \alpha/2), $$

  which, unlike the normal approximation, stays inside $[0, 1]$ and is informative with few or no errors (with $k = 0$ its upper end is $z^{2}/(n + z^{2})$). The other intervals of a proportion compared by Brown, Cai & DasGupta (2001) are available through ErrorRate::interval and BinomialInterval: Wald, Agresti–Coull, Jeffreys and Clopper–Pearson, with their exact coverage and expected_length.

• Mean accumulates real values with Welford’s algorithm (numerically stable running mean and variance) and merges two accumulators exactly (Chan, Golub and LeVeque); its interval is the normal interval of the mean, $\bar{x} \pm z s/\sqrt{n}$.

• Estimate is either of the two, with the same interface.

Examples

use comnum_sim::stats::{ErrorRate, Mean, Estimate, z_score};
let mut e = ErrorRate::default();
e.add(3, 1000);
e.add(7, 1000);
assert_eq!(e.rate(), 5e-3);
let (lo, hi) = e.wilson(0.95);
assert!(lo < 5e-3 && 5e-3 < hi);
let mut m = Mean::default();
for v in [1.0, 2.0, 3.0, 4.0] { m.add(v); }
assert_eq!((m.mean(), m.variance()), (2.5, 5.0 / 3.0));
assert!((z_score(0.95) - 1.959964).abs() < 1e-5);
let est = Estimate::Rate(e);
assert_eq!(est.value(), 5e-3);

References

1. L. D. Brown, T. T. Cai, A. DasGupta, “Interval estimation for a binomial proportion,” Statistical Science 16(2), 101–133, 2001: eqs. (1), (4), (5), (6)–(8) and Sec. 4.2.1 (the intervals), Sec. 2 (the coverage), Sec. 3.3 (the expected length).

Structs

ErrorRate

Errors among trials of a Bernoulli event.

Mean

Running mean and variance of real values (Welford).

Enums

BinomialInterval

A confidence interval of a binomial proportion $p$ from $k$ successes among $n$ trials, $\hat{p} = k/n$, $z = \Phi^{-1}(1 - \alpha/2)$ (Brown, Cai & DasGupta 2001, with their equations):

Estimate

The estimate of one metric: an error rate or a mean.

Functions

coverage

The exact coverage probability $C(p, n) = P_{p}(L(X) \le p \le U(X))$ of an interval for $X \sim \mathrm{Bin}(n, p)$: the sum of the binomial probabilities of the counts whose interval contains $p$ (Brown et al. 2001, Sec. 2), no simulation.

expected_length

The expected length $\sum_{k} (U(k) - L(k)) P_{p}(X = k)$ of an interval for $X \sim \mathrm{Bin}(n, p)$ (Brown et al. 2001, Sec. 3.3), with the ends of ErrorRate::interval.

z_score

The quantile $z = \Phi^{-1}(1 - \alpha/2) = Q^{-1}(\alpha/2)$ of a two-sided confidence level $1 - \alpha$ (1.96 for 0.95); the level is clamped to $[0, 1)$ (the runner refuses a level outside $(0, 1)$, see check_confidence).