Uncertainty for bounded benchmark scores

bounded_mean_interval reports a weighted bounded score and a conservative interval for its expected value under a declared simulation design. Use one unit for an independently generated complete correction-family replicate. Corrected cell/measurement calls within a family share thresholds and are not independent observations for this calculation. Recording profiles are fixed simulation conditions; repeated simulations are not new biological samples.

import circadian_workbench as cw
units = [{"id": str(i), "dependency_id": str(i),
          "value": 0.8, "weight": 1.} for i in range(100)]
result = cw.bounded_mean_interval(units, confidence=0.95, bounds=[0, 1])
print(result.data["mean"], result.data["lower"], result.data["upper"])

Each unit declares an id, dependency_id, bounded value and fixed positive weight. Repeated/shared observations use the same dependency_id. Their weights are merged without adding independent evidence. Different outcomes under one dependency id are rejected: aggregate dependent outcomes into one unit first. Distinct dependency groups must be independent; the function cannot verify the experimental design.

For fixed normalized weights a_i and predeclared common bounds [L,U], the reported mean is sum(a_i * value_i). The two-sided Hoeffding radius is (U-L) * sqrt(log(2/(1-confidence)) * sum(a_i**2) / 2), capped at the full outcome range; interval endpoints are clipped to the bounds. This follows the inequality for independent bounded variables in Hoeffding (1963) and the derivation for non-identically distributed variables. It makes no normal approximation and remains wide when independent support is low. This implementation uses equal observation weighting only when equal weights were actually declared. Weights must be fixed before seeing scores.

Use [0,1] for a recovery or false-alarm fraction, or [-1,1] for paired score differences formed on the same case families. Preserve the paired source identities in the unit records; never subtract unrelated case averages and call them paired. A confidence level applies to one interval. Multiple reported intervals do not automatically have simultaneous coverage. Family-wide coverage can be requested by declaring the corresponding per-interval confidence levels before evaluation.

The result retains grouped units, normalized weights, independent/input counts, bounds, confidence, method, assumptions and the standard reproducible run record. Empty inputs produce no_observations with no mean or interval. A narrow score interval is conditional on the simulated scenarios; it is not a probability that a real cell's period is correct, and it does not establish biological replication.