ssbc.core_pkg.core

Core SSBC (Small-Sample Beta Correction) algorithm.

Functions

ssbc_correct(alpha_target, n, delta, *[, ...])

Small-Sample Beta Correction (SSBC), corrected acceptance rule.

Classes

SSBCResult(alpha_target, alpha_corrected, ...)

Result of SSBC correction.

class ssbc.core_pkg.core.SSBCResult(alpha_target, alpha_corrected, u_star, n, satisfied_mass, mode, details)[source]

Result of SSBC correction.

Parameters:

alpha_target (float)
alpha_corrected (float)
u_star (int)
n (int)
satisfied_mass (float)
mode (Literal['beta', 'beta-binomial'])
details (dict[str, Any])

alpha_target

Target miscoverage rate

Type:: float

alpha_corrected

Corrected miscoverage rate (u_star / (n+1))

Type:: float

u_star

Optimal u value found by the algorithm

Type:: int

n

Calibration set size

Type:: int

satisfied_mass

Probability that coverage >= target

Type:: float

mode

“beta” for infinite test window, “beta-binomial” for finite

Type:: Literal[‘beta’, ‘beta-binomial’]

details

Additional diagnostic information

Type:: dict[str, Any]

alpha_target: float

alpha_corrected: float

u_star: int

n: int

satisfied_mass: float

mode: Literal['beta', 'beta-binomial']

details: dict[str, Any]

__init__(alpha_target, alpha_corrected, u_star, n, satisfied_mass, mode, details)

Parameters:

alpha_target (float)
alpha_corrected (float)
u_star (int)
n (int)
satisfied_mass (float)
mode (Literal['beta', 'beta-binomial'])
details (dict[str, Any])

Return type:

None

ssbc.core_pkg.core.ssbc_correct(alpha_target, n, delta, *, mode='beta', m=None, bracket_width=None)[source]

Small-Sample Beta Correction (SSBC), corrected acceptance rule.

Find the largest α’ = u/(n+1) ≤ α_target such that: P(Coverage(α’) ≥ 1 - α_target) ≥ 1 - δ

where Coverage(α’) ~ Beta(n+1-u, u) for infinite test window.

Trivial regime: if α_target < 1/(n+1), return α_corrected=0.

Parameters:

alpha_target (float) – Target miscoverage rate (must be in (0,1))
n (int) – Calibration set size (must be >= 1)
delta (float) – PAC risk tolerance (must be in (0,1)). This is the probability that the coverage guarantee fails. For example, delta=0.10 means we want a 90% PAC confidence (1-delta) that coverage ≥ target.
mode ({"beta", "beta-binomial"}, default="beta") – “beta” for infinite test window “beta-binomial” for finite test window (defaults to m=n)
m (int, optional) – Test window size for beta-binomial mode (defaults to n)
bracket_width (int, optional) – Search radius around initial guess (default: adaptive based on n)

Returns:

Dataclass containing correction results and diagnostic details

Return type:

SSBCResult

Raises:

ValueError – If parameters are out of valid ranges

Examples

>>> result = ssbc_correct(alpha_target=0.10, n=50, delta=0.10)
>>> print(f"Corrected alpha: {result.alpha_corrected:.4f}")

Notes

The algorithm uses a bracketed search with an initial guess based on normal approximation to the Beta distribution. If the initial bracket fails to find a solution, it performs adaptive outward expansion (downward then upward) with O(n) worst-case complexity.