Binomial Proportion Intervals¶

See the fixed-sample guide for assumptions, precision planning and optional indicator summary metadata.

`trade_study.ProportionInterval(k, n, estimate, low, high, confidence, method)` `dataclass` ¶

Two-sided, marginal interval for a fixed-sample Bernoulli probability.

Wilson coverage is approximate; Clopper-Pearson is conservative under independent identically distributed Bernoulli sampling at a fixed n. Neither method supplies a sequential or post-selection guarantee.

Attributes:

Name	Type	Description
`k`	`int`	Number of successes.
`n`	`int`	Number of trials.
`estimate`	`float`	Observed proportion k / n, not the Wilson interval center.
`low`	`float`	Lower probability bound.
`high`	`float`	Upper probability bound.
`confidence`	`float`	Nominal two-sided confidence level.
`method`	`str`	Wilson without continuity correction, or Clopper-Pearson.

`trade_study.proportion_interval(k, n, *, confidence=0.95, method='wilson')` ¶

Estimate a binomial proportion and its two-sided fixed-sample interval.

Trials must be independent Bernoulli outcomes with a common probability and a prespecified sample size. Callers establish these assumptions; counts alone cannot verify them. Intervals are marginal, without a multiplicity adjustment, and are not valid for arbitrary optional stopping.

Parameters:

Name	Type	Description	Default
`k`	`int`	Integer successes, including NumPy integer scalars; 0 <= k <= n.	required
`n`	`int`	Positive integer trial count, at most 2**53 for float64 arithmetic.	required
`confidence`	`float`	Nominal level in (0, 1), default 0.95.	`0.95`
`method`	`str`	"wilson" without continuity correction (core), or "clopper-pearson" using the optional stats extra.	`'wilson'`

Returns:

Type	Description
`ProportionInterval`	Observed estimate and interval with counts and method recorded.

Raises:

Type	Description
`ValueError`	If counts, confidence or method are invalid or unsupported.
`ImportError`	If Clopper-Pearson is requested without the stats extra.

Examples:

>>> interval = proportion_interval(8, 10)
>>> interval.estimate, interval.n, interval.method
(0.8, 10, 'wilson')
>>> interval.low < interval.estimate < interval.high
True

Source code in src/trade_study/proportions.py

def proportion_interval(
    k: int,
    n: int,
    *,
    confidence: float = 0.95,
    method: str = "wilson",
) -> ProportionInterval:
    """Estimate a binomial proportion and its two-sided fixed-sample interval.

    Trials must be independent Bernoulli outcomes with a common probability
    and a prespecified sample size. Callers establish these assumptions;
    counts alone cannot verify them. Intervals are marginal, without a
    multiplicity adjustment, and are not valid for arbitrary optional stopping.

    Args:
        k: Integer successes, including NumPy integer scalars; 0 <= k <= n.
        n: Positive integer trial count, at most 2**53 for float64 arithmetic.
        confidence: Nominal level in (0, 1), default 0.95.
        method: "wilson" without continuity correction (core), or
            "clopper-pearson" using the optional stats extra.

    Returns:
        Observed estimate and interval with counts and method recorded.

    Raises:
        ValueError: If counts, confidence or method are invalid or unsupported.
        ImportError: If Clopper-Pearson is requested without the stats extra.

    Examples:
        >>> interval = proportion_interval(8, 10)
        >>> interval.estimate, interval.n, interval.method
        (0.8, 10, 'wilson')
        >>> interval.low < interval.estimate < interval.high
        True
    """
    successes, trials = _count(k, "k"), _count(n, "n")
    if not 0 < trials <= _MAX_TRIALS or successes > trials:
        msg = "counts must satisfy 0 <= k <= n and 1 <= n <= 2**53"
        raise ValueError(msg)
    tail = _tail(confidence, method)
    estimate = successes / trials
    if method == "clopper-pearson":
        try:
            from scipy.special import (  # type: ignore[import-untyped]
                betainccinv,
                betaincinv,
            )
        except ImportError as error:
            msg = "Clopper-Pearson intervals require trade-study[stats] (SciPy >=1.11)"
            raise ImportError(msg) from error
        low = (
            0.0
            if successes == 0
            else float(betaincinv(successes, trials - successes + 1, tail))
        )
        high = (
            1.0
            if successes == trials
            else float(betainccinv(successes + 1, trials - successes, tail))
        )
        if not 0 <= low <= high <= 1:
            msg = "Clopper-Pearson beta inversion produced invalid bounds"
            raise ValueError(msg)
    else:
        z = -NormalDist().inv_cdf(tail)
        correction = z * z / trials
        center = (estimate + correction / 2) / (1 + correction)
        radius = (
            z
            * sqrt((estimate * (1 - estimate) + correction / 4) / trials)
            / (1 + correction)
        )
        low = 0.0 if successes == 0 else max(0.0, center - radius)
        high = 1.0 if successes == trials else min(1.0, center + radius)
    return ProportionInterval(
        successes, trials, estimate, low, high, float(confidence), method
    )

`trade_study.replicates_for_half_width(half_width, *, confidence=0.95)` ¶

Plan a fixed trial count from the worst-case Wilson interval half-width.

The largest continuous Wilson half-width occurs at observed proportion 1/2 and equals z / (2 * sqrt(n + z**2)). Inverting this expression gives the smallest positive integer satisfying that conservative bound, even when n is odd. This is interval-precision planning, not power analysis, a guarantee of Wilson coverage, or a rule for stopping after each trial.