1 oracle.target_sampling

oracle.target_sampling

Balanced target allocation with exact marginal inclusion probabilities.

This module owns only the allocation arithmetic. Callers admit the target population, derive its causal support strata, and own the generator seed. The returned probabilities describe inclusion anywhere in the capped sample; they do not describe first-draw order or successful downstream persistence.

1.1 Classes

Name Description
StratifiedSample Capped draw with complete population-level probability accounting.
StratumAllocation Realized and expected allocation for one nonempty stratum.

1.1.1 StratifiedSample

oracle.target_sampling.StratifiedSample(
    selected_indices,
    inclusion_probabilities,
    strata,
)

Capped draw with complete population-level probability accounting.

1.1.1.1 Attributes

Name Description
selected_indices Indices into the admitted input rows, in randomized execution order.
inclusion_probabilities Marginal inclusion probability for every admitted input row.
strata Population, realized quota, and marginal probability for each stratum.

1.1.2 StratumAllocation

oracle.target_sampling.StratumAllocation(
    stratum,
    population,
    selected,
    expected_selected,
    inclusion_probability,
)

Realized and expected allocation for one nonempty stratum.

1.1.2.1 Attributes

Name Description
stratum Caller-defined stratum identifier; -1 conventionally means unavailable.
population Number of admitted targets in the stratum before capped allocation.
selected Realized number of selected targets in the stratum.
expected_selected Expected stratum quota over the randomized residual allocation.
inclusion_probability Marginal probability that any one target in the stratum is selected.

1.2 Functions

Name Description
balanced_stratified_sample Water-fill stratum quotas and randomize the incomplete quota layer.

1.2.1 balanced_stratified_sample

oracle.target_sampling.balanced_stratified_sample(strata, *, count, generator)

Water-fill stratum quotas and randomize the incomplete quota layer.

Let k = min(count, N) and let L be the largest integer no greater than max_s(n_s) satisfying sum(min(n_s, L)) <= k. Every stratum receives min(n_s, L) rows. The remaining r slots are assigned uniformly without replacement to the m unsaturated strata. A row in stratum s therefore has marginal inclusion probability (min(n_s, L) + r / m * 1[n_s > L]) / n_s. Sampling within each stratum is uniform. Randomized output order carries no per-draw probability claim.

Empty input is a valid empty population. A single stratum deliberately degenerates to one torch.randperm call so it reproduces the seeded uniform reference exactly.

Back to top