binomial_cis package

Submodules

binomial_cis.binomial_helper module

binomial_cis.conf_intervals module

binomial_cis.conf_intervals.UMAU_lb(t_o, n, alpha, tol=1e-06)

Computes the lower bound for a 2-sided UMAU CI.

Parameters:

  • t_o (float) – Observed test statistic (number of successes + uniform random number).

  • n (int) – Number of trials (samples).

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

Returns:

p_lb – Lower bound of UMAU confidence interval for p

Return type:

float

binomial_cis.conf_intervals.UMAU_ub(t_o, n, alpha, tol=1e-06)

Computes the upper bound for a 2-sided UMAU CI.

Parameters:

  • t_o (float) – Observed test statistic (number of successes + uniform random number).

  • n (int) – Number of trials (samples).

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

Returns:

p_ub – Upper bound of UMAU confidence interval for p

Return type:

float

binomial_cis.conf_intervals.binom_bisection(k, n, alpha)

Inputs k: number of successes n: number of samples alpha: miscoverage rate, P(p_ <= p) >= 1-alpha

Returns p: smallest p such that binom_cdf(k,n,p) >= 1-alpha

binomial_cis.conf_intervals.binom_ci(k, n, alpha, side, verbose=True, randomized=True)

Compute a binomial confidence interval.

Parameters:

  • k (int) – Number of observed successes in n trials.

  • n (int) – Number of trials (samples).

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • side ({'lb', 'ub', 'lb,ub'}) – Selection of lower, upper, or 2-sided bounds.

  • verbose (bool, default True) – Whether to print intermediate updates.

  • randomized (bool, default True) – If True solves for the UMA bounds, if False then solves for (less efficient) non-randomized bounds.

Returns:

CI – Either a lower bound, upper bound, or simultaneous lower & upper bounds (returned as a tuple)

Return type:

float

binomial_cis.conf_intervals.bisection(CDF, alpha, tol=1e-06)

Inputs CDF: a function mapping from p -> F(t | p) alpha: miscoverage rate, P(p_ <= p) >= 1-alpha tol: upper bound on how far below the returned value of p is to the true solution

Returns p_: a lower bound on p such that P(p_ <= p) >= 1-alpha

binomial_cis.conf_intervals.get_UMPU_accept_region(p_o, n, alpha)

Inputs p_o: null hypothesis prob of success n: number of trials alpha: miscoverage (Type 1 error) rate, P(accept | p = p_o) >= 1-alpha

Returns t_lo, t_up: UMAU acceptance region for the test statistic

binomial_cis.conf_intervals.get_feasible_p(t_o, n, alpha)

Inputs t_o: observed test statistic n: number of trials alpha: miscoverage rate

Returns p_o: a value of p in the UMAU interval

binomial_cis.conf_intervals.get_lb(num_successes, n, alpha, randomized=True)

Inputs num_successes: number of observed successes in n trials n: number of trials alpha: miscoverage rate, P(p_ <= p) >= 1-alpha

Returns p_: a lower bound on p such that P(p_ <= p) >= 1-alpha

binomial_cis.conf_intervals.get_lb_ub(num_successes, n, alpha)

Inputs num_successes: number of observed successes in n trials n: number of trials alpha: miscoverage rate, P(p_lb <= p <= p_ub) >= 1-alpha

Returns p_lb, p_ub: A UMAU confidence interval for p

We know that the bounds of the test statistic acceptance region are monotonically increasing in p (see Lehmann textbook). Strategy: bisection search to find bounds on p

binomial_cis.conf_intervals.get_ps_cp(p, n, alpha)

Compute all possible Clopper-Pearson lower bounds given n trials.

Parameters:

  • p (float) – True success probability.

  • n (int) – Number of trials (samples).

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

Returns:

ps – Array of possible Clopper-Pearson lower bounds that are cutoff points in the expected shortage integral.

Return type:

array_like

binomial_cis.conf_intervals.in_UMPU_accept_region(t_o, p_o, n, alpha)

Inputs t_o: observed test statistic p_o: null hypothesis prob of success n: number of trials alpha: miscoverage (Type 1 error) rate, P(accept | p = p_o) >= 1-alpha

Returns boolean for whether t_o is in the UMAU acceptance region for the test statistic

binomial_cis.conf_intervals.max_accept_prob_2_sided(alpha, n, p, n_grid)

Grid search to find the parameter which has the highest probability of being in the 2-sided CI.

Parameters:

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • n (int) – Number of trials (samples).

  • p (float) – True probability of success.

  • n_grid (int) – Size of discrete grid to search over.

Returns:

  • max_ap (float) – Maximum acceptance probability.

  • max_p_0 (float) – Parameter that attains the maximum acceptance probability.

binomial_cis.conf_intervals.test_stat(num_successes, randomized=True)

Inputs num_successes: number of observed successes in n trials

Returns T: number of successes + uniform random variable

binomial_cis.mixed_monotonic module

class binomial_cis.mixed_monotonic.Interval(x_min, x_max)

Bases: object

Class for storing and performing common operations on intervals.

Parameters:

  • x_min (float) – Lower bound of interval

  • x_max (float) – Upper bound of interval

get_feasible(F)

Finds a feasible point in the interval.

Parameters:

F (function) – Mixed monotonic function (increasing in first arg, decreasing in second arg)

Returns:

  • x_feas (float) – Midpoint of interval

  • x_feas_val (float) – Value of midpoint on the function F

get_midpoint()

Computes the midpoint of the interval.

Returns:

Midpoint of interval

Return type:

float

get_ub(F)

Computes a certified upper bound of the function F over the interval.

Parameters:

F (function) – Mixed monotonic function (increasing in first arg, decreasing in second arg)

Returns:

ub – Certified upper bound of max(F) over Interval

Return type:

float

split()

Split along longest axis, else split along first axis.

Returns:

I1, I2 – Intervals resulting from splitting the orignal in half.

Return type:

Interval

volume()

Computes the width of the interval.

Returns:

Width of interval

Return type:

float

binomial_cis.mixed_monotonic.mmp_solve(F, I, tol=0.001, max_iters=1000, verbose=True)

Uses mixed-monotonic programming to solve for a certified maximum of the function F over the interval I.

Parameters:

  • F (function) – Mixed monotonic function (increasing in first arg, decreasing in second arg)

  • I (Interval) – Domain to maximize over.

Returns:

  • ub (float) – Certified upper bound of max F over I within tol of global max.

  • lb (float) – Certified lower bound of max F over I within tol of global max.

  • x_lb (float) – Input that achieves lb.

  • num_iters (int) – Number of iterations taken for the solve.

binomial_cis.plotting module

binomial_cis.plotting.plot_expected_shortage_mixed_monotonic(alpha, n, p1s, p2s, verbose=True, randomized=True)

Generate a contour plot of the mixed-monotonic form of expected shortage.

Parameters:

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • n (int) – Number of trials (samples).

  • p1 (float) – True probability of success input as limit of integration.

  • p2 (float) – True probability of success input as paremter of CDF in integrand.

  • randomized (bool, default True) – If False then use Clopper-Pearson CI.

Returns:

Contour plot showing expected shortage for each parameter combination.

Return type:

plot

binomial_cis.plotting.plot_expected_width_mixed_monotonic(alpha, n, p1s, p2s, verbose=True)

Generate a contour plot of the mixed-monotonic form of expected width.

Parameters:

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • n (int) – Number of trials (samples).

  • p1 (float) – True probability of success input as limit of integration.

  • p2 (float) – True probability of success input as paremter of CDF in integrand.

  • randomized (bool, default True) – If False then use Clopper-Pearson CI.

Returns:

Contour plot showing expected width for each parameter combination.

Return type:

plot

binomial_cis.plotting.plot_shortage_curve(alpha, n, num_p=21, verbose=True, randomized=True)

Plot expected shortage as a function of true prob of success p.

Parameters:

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • n (int) – Number of trials (samples).

  • num_p (int) – Number of values of p to compute shortage for.

  • randomized (bool, default True) – If False then use Clopper-Pearson CI.

Returns:

Plot of curve which visualizes expected shortage as a function of true prob of success p.

Return type:

plot

binomial_cis.plotting.plot_width_curve(alpha, n, num_p=21, verbose=True)

Plot expected width as a function of true prob of success p.

Parameters:

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • n (int) – Number of trials (samples).

  • num_p (int) – Number of values of p to compute width for.

Returns:

Plot of curve which visualizes expected width as a function of true prob of success p.

Return type:

plot

binomial_cis.volume module

binomial_cis.volume.expected_excess(accept_prob, alpha, n, p)

Computes the expected excess of an upper confidence bound.

Parameters:

  • accept_prob (function) – Function that takes in p_0 and outputs acceptance prob for lb.

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • n (int) – Number of trials (samples).

  • p (float) – True probability of success.

Returns:

exp_excess – The expected excess of the CI.

Return type:

float

binomial_cis.volume.expected_shortage(accept_prob, alpha, n, p)

Computes the expected shortage of a lower confidence bound.

Parameters:

  • accept_prob (function) – Function that takes in p_0 and outputs acceptance prob for lb.

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • n (int) – Number of trials (samples).

  • p (float) – True probability of success.

Returns:

exp_shortage – The expected shortage of the CI.

Return type:

float

binomial_cis.volume.expected_shortage_cp(alpha, n, p)

Computes the expected shortage of a Clopper-Pearson lower confidence bound.

Parameters:

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • n (int) – Number of trials (samples).

  • p (float) – True probability of success.

Returns:

exp_shortage – The expected shortage of the CI.

Return type:

float

binomial_cis.volume.expected_shortage_mixed_monotonic(accept_prob, alpha, n, p1, p2)

Implements the mixed-monotonic form of expected shortage for the lower bound CI.

Parameters:

  • accept_prob (function) – Function that takes in p_0 and outputs acceptance prob for lb.

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • n (int) – Number of trials (samples).

  • p1 (float) – True probability of success input as limit of integration.

  • p2 (float) – True probability of success input as paremter of CDF in integrand.

Returns:

exp_shortage_mm – The expected shortage of the CI.

Return type:

float

binomial_cis.volume.expected_shortage_mixed_monotonic_cp(alpha, n, p1, p2)

Computes the expected shortage of the lower bound CI

Inputs accept_prob: function that takes in p_0 and outputs acceptance prob for lb alpha: miscoverage rate n: number of samples p: true probability of success

Returns exp_shortage: the expected shortage of the CI

binomial_cis.volume.expected_width(accept_prob, alpha, n, p)

Computes the expected width of a 2-sided CI.

Parameters:

  • accept_prob (function) – Function that takes in p_0 and outputs acceptance prob for lb.

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • n (int) – Number of trials (samples).

  • p (float) – True probability of success.

Returns:

exp_width – The expected width of the CI.

Return type:

float

binomial_cis.volume.expected_width_mixed_monotonic(accept_prob, alpha, n, p1, p2)

Implements the mixed-monotonic form of expected width for the 2-sided CI.

Parameters:

  • accept_prob (function) – Function that takes in p_0 and outputs acceptance prob for lb.

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • n (int) – Number of trials (samples).

  • p1 (float) – True probability of success input for CDF at t_u.

  • p2 (float) – True probability of success input for CDF at t_l.

Returns:

exp_width_mm – The expected width of the CI.

Return type:

float

binomial_cis.volume.max_expected_excess(alpha, n, tol=0.001, verbose=True)

Computes maximum expected excess (MEE) for the upper bound.

Parameters:

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • n (int) – Number of trials (samples).

Returns:

  • ub (float) – An upper bound on max expected excess.

  • lb (float) – A lower bound on max expected excess.

  • p_lb (float) – The parameter that achieves lb.

  • num_iters (int) – Number of iterations taken for the solve.

binomial_cis.volume.max_expected_shortage(alpha, n, tol=0.001, verbose=True, randomized=True)

Computes maximum expected shortage (MES) for the lower bound.

Parameters:

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • n (int) – Number of trials (samples).

Returns:

  • ub (float) – An upper bound on max expected shortage.

  • lb (float) – A lower bound on max expected shortage.

  • p_lb (float) – The parameter that achieves lb.

  • num_iters (int) – Number of iterations taken for the solve.

binomial_cis.volume.max_expected_width(alpha, n, tol=0.001, verbose=True)

Computes maximum expected width (MEW) for the 2-sided bound.

Parameters:

  • alpha (float) – Miscoverage rate, P(p in CI) = 1-alpha.

  • n (int) – Number of trials (samples).

Returns:

  • ub (float) – An upper bound on max expected width.

  • lb (float) – A lower bound on max expected width.

  • p_lb (float) – The parameter that achieves lb.

  • num_iters (int) – Number of iterations taken for the solve.

Module contents