Density ratios

ratios_from_posteriors

ratios_from_posteriors(posteriors: ArrayLike, class_priors: ArrayLike, *, execution: ExecutionConfig | None = None) -> ndarray

Convert calibrated class posteriors into model density ratios.

Parameters:

• posteriors (ArrayLike) –

  Calibrated class-posterior matrix with shape [N, K]. Rows must be finite, nonnegative, and sum to one.

• class_priors (ArrayLike) –

  Strictly positive class priors under which posteriors were estimated, with shape [K] and unit sum.

Returns:

• ndarray –

  Ratio matrix r_k(x) = posteriors_k(x) / class_priors_k with shape [N, K]: the component density ratios phi_k(x) / p_train(x), where p_train is the training mixture. The common event-wise factor p_train cancels in every downstream score map.

Raises:

• ValueError –

  If shapes, finiteness, nonnegativity, or simplex normalization violate the posterior contract.

Notes

Only a calibrated posterior carries ratio information. A ranking score or an arbitrary monotone transform of a likelihood ratio is not sufficient: score construction needs a quantitatively meaningful ratio, so calibration or a ratio-estimation loss is required upstream.

The function does not calibrate, clip, or renormalize classifier output. Those operations change the implied density ratios and belong to the upstream ratio-estimation workflow.

mixture_scores_from_ratios

mixture_scores_from_ratios(ratios: ArrayLike, reference_fractions: ArrayLike, *, reference_component: int = -1, execution: ExecutionConfig | None = None) -> ndarray

Construct normalized-mixture scores from component density ratios.

Parameters:

• ratios (ArrayLike) –

  Finite nonnegative component density ratios with shape [N, K], defined up to one common event-wise factor.

• reference_fractions (ArrayLike) –

  Strictly positive mixture fractions at the score reference point, with shape [K] and unit sum.

• reference_component (int, default: -1 ) –

  Component treated as dependent under the simplex constraint. Negative indices follow ordinary Python indexing. The last component is used by default.

Returns:

• ndarray –

  Score matrix (r_k - r_ref) / sum_j reference_fractions[j] * r_j with shape [N, K - 1]. Columns follow the original component order with reference_component omitted.

Raises:

• TypeError –

  If reference_component is not an integer.

• ValueError –

  If shapes, finiteness, positivity, normalization, or the reference component violate the mixture-score contract.

Notes

This is the score of the normalized mixture p(x; theta) = sum_k theta_k phi_k(x) with sum_k theta_k = 1 and the reference component dependent on the others. The map is invariant under a common event-wise rescaling r_k(x) -> c(x) r_k(x), so any gauge works: ratios relative to one component (r_ref = 1, giving (r_k - 1) / sum_j theta_j r_j), relative to the training mixture, or relative to the reference density itself.

IntensityParameterization dataclass

IntensityParameterization(coefficients: ArrayLike)

Declare an extended linear-intensity model over component ratios.

The model is lambda(x; theta) = sum_k theta_k phi_k(x) with free, unconstrained coefficients, so every one of the K score columns is retained, including the overall-normalization direction.

Parameters:

• coefficients (ArrayLike) –

  Finite reference coefficients theta_0 with shape [K].

n_components property

n_components: int

Number of ratio columns the parameterization consumes.

scores

scores(ratios: ArrayLike, *, execution: ExecutionConfig | None = None) -> ndarray

Return the [N, K] intensity scores r_k / sum_j theta_j r_j.

Because scores_from_components is invariant under a common event-wise rescaling of its rows, evaluating it on density ratios in any gauge yields exactly the component scores phi_k / lambda.

MixtureParameterization dataclass

MixtureParameterization(reference_fractions: ArrayLike, *, reference_component: int = -1)

Declare a normalized mixture with one simplex-dependent component.

The model is p(x; theta) = sum_k theta_k phi_k(x) with sum_k theta_k = 1; the reference component is dependent, so scores have K - 1 columns.

Parameters:

• reference_fractions (ArrayLike) –

  Strictly positive mixture fractions theta_0 with shape [K] and unit sum.

• reference_component (int, default: -1 ) –

  Component treated as dependent under the simplex constraint.

n_components property

n_components: int

Number of ratio columns the parameterization consumes.

scores

scores(ratios: ArrayLike, *, execution: ExecutionConfig | None = None) -> ndarray

Return the [N, K - 1] constrained-mixture scores.

ratio_closure_report

ratio_closure_report(ratios: ArrayLike, weights: ArrayLike, *, execution: ExecutionConfig | None = None) -> RatioClosureReport

Check that density ratios integrate to one under the declared measure.

Parameters:

• ratios (ArrayLike) –

  Finite nonnegative model density ratios with shape [N, K], relative to the measure the weights carry.

• weights (ArrayLike) –

  Finite nonnegative weights with shape [N] and at least one positive entry, carrying the reference measure of the ratio denominator.

Returns:

• RatioClosureReport –

  Per-component weighted means sum_i w_i r_ik / sum_i w_i and their largest absolute deviation from one.

Raises:

• ValueError –

  If shapes, finiteness, or nonnegativity violate the contract.

Notes

For exact ratios r_k = phi_k / p_ref every column integrates to one under the reference measure, so a nonzero residual bounds estimator bias from below: it is model error, never compression loss. The test is joint in the estimator, the declared training priors, and the measure, and it is necessary but not sufficient — closure never justifies upgrading estimated provenance to exact.

RatioClosureReport dataclass

RatioClosureReport(normalizers: ndarray, max_residual: float)

Report how far model density ratios are from unit normalization.

Exact component ratios relative to a reference measure integrate to one under that measure: sum_i w_i r_ik / sum_i w_i == 1 for every component k when the weights carry the measure the ratio denominator defines. A large residual signals estimator bias, a misdeclared training prior, or a measure mismatch. The check is necessary but not sufficient: a ratio can close marginally while still being wrong pointwise, so a small residual never upgrades estimated provenance.

Attributes:

• normalizers (ndarray) –

  Weighted mean of each ratio column, shape [K].

• max_residual (float) –

  Largest absolute deviation of normalizers from one.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible closure representation.