Proportion Confidence Interval

Proportion Confidence Interval (cross-cutting/numerics/proportion-confidence-interval)

Use when you must estimate a confidence interval for a binomial proportion from attribute data (pass-fail, go-no-go, defect counts): the Wilson score interval, its continuity-corrected variant, the exact Clopper-Pearson interval computed by inverting the binomial tail through an in-leaf regularized incomplete beta, and the normal-approximation interval for the difference of two proportions. All quantiles and beta values come from the module's own inversion machinery, pure Python stdlib with no external statistics packages. It pairs with cross-cutting/numerics/confidence-interval-estimation for intervals on continuous measurements and with cross-cutting/numerics/hypothesis-testing for the verdict layer on the same attribute data.

Domain quick reference

• Conventions: k successes in n trials, confidence level cl in (0, 1) (default 0.95), z = normal_quantile((1 + cl) / 2) computed in-leaf (1.959964 for 0.95). All single-proportion bounds live in [0, 1].
• Wilson score interval: center = (phat + z^2 / (2n)) / (1 + z^2 / n), half-width = z * sqrt(phat(1 - phat) / n + z^2 / (4n^2)) / (1 + z^2 / n), bounds = center +/- half-width with k = 0 forcing lower 0 and k = n forcing upper 1. Good default for most attribute claims.
• Continuity-corrected Wilson: the Newcombe form, which moves the interval outward by the 1/(2n) correction term; it is always at least as wide as the plain Wilson interval and keeps the same endpoints at k = 0 and k = n.
• Clopper-Pearson exact interval: lower solves I_p(k, n - k + 1) = alpha / 2 and upper solves I_p(k + 1, n - k) = 1 - alpha / 2, where I_p is the regularized incomplete beta evaluated in-leaf with the symmetry transform (below the crossover (a + 1) / (a + b + 2) use betacf(a, b, x) / a, at or above it use 1 - bt * betacf(b, a, 1 - x) / b) and inverted by bisection to 1e-10. k = 0 gives lower 0 and k = n gives upper 1 by endpoint handling.
• Two-proportion difference (normal approximation): diff = p1 - p2 with standard error sqrt(p1(1 - p1) / n1 + p2(1 - p2) / n2); the interval is diff +/- z * se and the reported width is the margin z * se of the worked example.
• The Clopper-Pearson interval is exact but conservative (guaranteed coverage at or above the level); Wilson is approximate with good coverage that is closer to nominal, so Wilson is the default and Clopper-Pearson the audit-grade check.
• NACA TR-824 frames the aeronautics numerics context; the relations above are standard engineering methodology, summary-only.

Workflow

1. State the attribute data: k successes in n trials (or the defect count for a fraction-defective claim) and the confidence level cl.
2. Compute the Wilson score interval with wilson_score_interval(k, n, cl) as the default estimate for the proportion.
3. If the sample is small or the claim is audit-grade, cross-check with the exact clopper_pearson_interval(k, n, cl) and report the exact bound when it differs materially.
4. When a continuity correction is wanted for conservatism near the edges, run wilson_score_cc_interval(k, n, cl) alongside the plain Wilson interval.
5. For a difference between two groups (configuration A versus B, batch versus batch), run two_proportion_diff_interval(k1, n1, k2, n2, cl) and report diff, the bounds, and the width.
6. Form the method recommendation: Wilson for the default gate, Clopper-Pearson when the claim must hold at the stated confidence, and the two-proportion interval when the comparison is the claim.
7. Confirm every result with the deterministic checks and the contract test scripts/test_proportion_confidence_interval.py.

Worked example

Attribute data with 12 successes in 400 trials at cl = 0.95 (phat = 0.03), module output in brackets:

• Wilson: [0.017243, 0.051699], width 0.034456; a 95% claim on the pass rate of 3% runs from 1.72% to 5.17%.
• Clopper-Pearson: [0.015596, 0.051817], width 0.036222; the exact interval is wider, as expected at finite n.
• Zero-success edge: k = 0, n = 30 gives Wilson [0.0, 0.113513] and Clopper-Pearson [0.0, 0.115703]; the Clopper-Pearson upper obeys the rule of three: 1 - 0.025^(1/30) = 0.1157.
• All-success edge: k = 30, n = 30 gives Wilson [0.886487, 1.0] and Clopper-Pearson [0.884297, 1.0].
• Two-proportion: k1 = 5, n1 = 100 versus k2 = 1, n2 = 100 gives diff 0.04, width 0.046957 and interval [-0.006957, 0.086957]; the interval contains zero, so the 5% versus 1% observed rates are not separated at 95% confidence with these sample sizes.

Verification

• Confirm wilson_score_interval(12, 400) returns lower 0.017243 and upper 0.051699, within 1e-4 of the spec anchors.
• Confirm clopper_pearson_interval(12, 400) returns lower 0.015596 and upper 0.051817, and clopper_pearson_interval(0, 30) upper 0.115703.
• Confirm both intervals contain phat = k / n at several (k, n), and that the width shrinks as n grows at fixed phat.
• Confirm the two-proportion width for (5, 100) versus (1, 100) is 0.04696 within 1e-3.
• Confirm k outside [0, n], n <= 0 and cl outside (0, 1) raise ValueError in every interval function.
• Confirm the dict keys are exactly lower/upper/width (plus diff for the two-proportion function) and that every bound stays in [0, 1] for the single-proportion methods.
• Run the contract test offline: python3 scripts/test_proportion_confidence_interval.py (35 tests, deterministic, under 1 second).

Related leaves

• cross-cutting/numerics/confidence-interval-estimation: parametric intervals for a mean, a difference of means and a variance from continuous measurement data.
• cross-cutting/numerics/hypothesis-testing: significance tests that consume the same attribute data and produce the verdict layer.
• cross-cutting/numerics/descriptive-statistics: the sample statistics (counts, rates) that feed the proportion intervals.
• cross-cutting/numerics/probability-distributions: binomial and beta distribution context behind the inversion methods.

Pitfalls

• Reporting a Wald interval for a small or edge sample: the normal-approximation (Wald) interval phat +/- z * sqrt(phat(1 - phat) / n) collapses to a point at k = 0 or k = n and is badly anti-conservative at small n; the Wilson interval in this leaf does not have that failure and is the default.
• Quoting the continuity-corrected Wilson interval without saying so: the Newcombe form is visibly wider than the plain Wilson interval (0/30 upper 0.1413 versus 0.1135), so mixing the two variants in one report inflates or deflates the claim silently.
• Treating Clopper-Pearson as the tightest bound: it is exact in coverage but conservative, so its width at small n can exceed the Wilson width by a wide margin (3/7 gives lower 0.099 versus 0.158); pick it for guaranteed coverage, not for tightness.
• Reading a difference-of-proportions interval that straddles zero as a verdict: a 95% interval containing zero means the observed rates are not separated at that level, but the verdict layer belongs to cross-cutting/numerics/hypothesis-testing, not to this leaf.
• Forgetting the k = 0 and k = n endpoint handling: the incomplete beta inversion is degenerate at the edges, so the module forces lower 0 at k = 0 and upper 1 at k = n; without it the exact interval would misreport a zero-failure claim.
• Inverting the beta without the symmetry transform: a continued fraction run only in one direction loses accuracy above the crossover (a + 1) / (a + b + 2) and the Clopper-Pearson upper bounds drift; the transform branch is required for the exact bounds.

Behavior contract (gate 3)

Run the deterministic contract test (stdlib unittest, offline):

python3 scripts/test_proportion_confidence_interval.py

The test covers the spec anchors (Wilson 12/400 [0.017243, 0.051699], 0/30 [0.0, 0.113513], 30/30 [0.886487, 1.0]; Clopper-Pearson 12/400 [0.015596, 0.051817], 0/30 [0.0, 0.115703], 30/30 [0.884297, 1.0]; two-proportion diff 0.04 with width 0.04696), phat containment, width shrinkage with n, the closed-form Wilson center identity, the exact binomial-tail inversion identity for Clopper-Pearson, beta symmetry across the crossover, the rule-of-three bound, convergence of Clopper-Pearson to Wilson at large n, dict key contracts, determinism, and ValueError rejection of every non-physical input class.

Compliance

• Standards referenced, not reproduced: NACA TR-824 is the aeronautics numerics reference id per standards-map.yaml; the interval relations above are standard engineering methodology, summary-only.
• compliance: STANDARDS-REF, gated: false.