binomial-cis 0.0.12

Confidence intervals for binomial distributions.

binomial_cis

This package computes confidence intervals for the probability of success parameter, $p$, of a binomial distribution. The confidence intervals computed by this package cover $p$ with exactly the user-specified probability and have minimal excess length.

Documentation

The documentation for the package can be found at: https://tri-ml.github.io/binomial_cis.

Installation

Install the package with pip:

pip install binomial_cis

What does this package do?

This package constructs optimal confidence intervals for the probability of success parameter, $p$, of a binomial distribution.

Lower Bounds

Given user specified miscoverage rate ($\alpha$) and maximum expected shortage ($\text{MES}$), return a lower bound on $p$ that satisfies the following requirements:

1. achieves exact desired coverage: $\mathbb{P}[\underline{p} \le p] = 1-\alpha$,
2. $[\underline{p}, 1]$ is uniformly most accurate,
3. achieves exact desired maximum expected shortage: $\max_p \ \mathbb{E}_p[\max (p - \underline{p}, 0)] = \text{MES}$,
4. uses the minimum number of samples $n$ to achieve requirements 1,2,3.

Upper Bounds

Given user specified miscoverage rate ($\alpha$) and maximum expected excess ($\text{MEE}$), return an upper bound on $p$ that satisfies the following requirements:

1. achieves exact desired coverage: $\mathbb{P}[p \le \overline{p}] = 1-\alpha$,
2. $[0, \overline{p}]$ is uniformly most accurate,
3. achieves exact desired maximum expected excess: $\max_p \ \mathbb{E}_p[\max (\overline{p} - p, 0)] = \text{MEE}$,
4. uses the minimum number of samples $n$ to achieve requirements 1,2,3.

2-Sided Bounds

Given the user specified miscoverage rate ($\alpha$) and maximum expected width ($\text{MEW}$), return simultaneous lower and upper bounds on $p$ that satisfy the following requirements:

1. achieves exact desired coverage: $\mathbb{P}[\underline{p} \le p \le \overline{p}] = 1-\alpha$,
2. $[\underline{p}, \overline{p}]$ is uniformly most accurate unbiased,
3. achieves exact desired maximum expected width: $\max_p \ \mathbb{E}_p[\overline{p} - \underline{p}] = \text{MEW}$,
4. uses the minimum number of samples $n$ to achieve requirements 1,2,3.

How do I use this package?

Lower Bounds

Find a lower bound on $p$:

from binomial_cis import binom_ci

k = 5 # number of successes
n = 10 # number of trials
alpha = 0.05 # miscoverage probability

lb = binom_ci(k, n, alpha, 'lb')

Find maximum expected shortage given miscoverage rate and number of samples:

from binomial_cis import max_expected_shortage

mes_ub, mes_lb, p_lb, num_iters = max_expected_shortage(alpha, n, tol=1e-3)

Upper Bounds

Find an upper bound on $p$:

from binomial_cis import binom_ci

k = 5 # number of successes
n = 10 # number of trials
alpha = 0.05 # miscoverage probability

ub = binom_ci(k, n, alpha, 'ub')

Find maximum expected excess given miscoverage rate and number of samples:

from binomial_cis import max_expected_excess

mee_ub, mee_lb, p_lb, num_iters = max_expected_excess(alpha, n, tol=1e-3)

2-Sided Bounds

Find simultaneous lower and upper bounds on $p$:

from binomial_cis import binom_ci

k = 5 # number of successes
n = 10 # number of trials
alpha = 0.05 # miscoverage probability

lb, ub = binom_ci(k, n, alpha, 'lb,ub')

Find maximum expected width given miscoverage rate and number of samples:

from binomial_cis import max_expected_width

mew_ub, mew_lb, p_lb, num_iters = max_expected_width(alpha, n, tol=1e-3)