API Documentation

This page displays the functions which are exported by the binomial_cis package.

class binomial_cis.Interval(x_min, x_max)

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

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