ssbc.core_pkg

Core API facade.

Provides a stable package path for the core SSBC primitives without moving the existing core.py yet.

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

Result of SSBC correction.

Parameters:
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:
Return type:

None

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

Modules

core

Core SSBC (Small-Sample Beta Correction) algorithm.