mixle.experimental.v_information module

P13 (experimental) – usable-information (V-information) receipts on a model family.

Shannon mutual information I(X;Y) measures how much information about Y is present in X; it says nothing about whether a given model family can use it. V-information does: I_V(X -> Y) is the reduction in the population-optimal predictive log-loss from letting the family condition on X,

I_V(X -> Y) = H_V(Y) - H_V(Y | X),

where H_V(Y) is the population risk of the optimal marginal Y model in the family and H_V(Y | X) the corresponding risk of an optimal conditional Y | X model. The usability gap gap = I(X;Y) - I_V is then a receipt on the library, not a model: it says how much real dependence the current grammar cannot capture, and it closes when the missing capability is added.

This module produces finite-sample held-out estimates with polynomial-Gaussian conditional families (degree 1 = linear grammar, degree 2 = adds a quadratic feature), plus the population closed-form Gaussian I(X;Y) reference when its correlation is known. A single split is only a point estimate, not a population optimum. estimate_v_information() repeats the split and reports split-assignment uncertainty; it still does not quantify dataset-sampling or model-selection uncertainty.

Exploratory mixle.experimental code (P13 card).

class VInformationEstimate(estimate, standard_error, interval, confidence, split_estimates, degree, holdout, uncertainty_scope='random_holdout_assignment_only')[source]

Bases: object

Repeated-holdout V-information estimate with explicitly scoped uncertainty.

Parameters:
marginal_nll(y, *, holdout=0.3, seed=0)[source]

One-split held-out NLL estimate for a fitted marginal Gaussian Y model.

Parameters:
Return type:

float

conditional_nll(x, y, *, degree, holdout=0.3, seed=0)[source]

One-split held-out NLL estimate for a fitted polynomial-Gaussian Y | X model.

Parameters:
Return type:

float

v_information(x, y, *, degree=1, holdout=0.3, seed=0)[source]

Return one held-out-split point estimate of I_V(X -> Y) in nats.

Marginal and conditional models use the same train/test indices. The result is the fitted family’s realized reduction in predictive log-loss on that test split. It is not the population-optimal V-information and carries no uncertainty estimate; use estimate_v_information() when split uncertainty matters.

Parameters:
Return type:

float

estimate_v_information(x, y, *, degree=1, holdout=0.3, n_splits=10, confidence=0.95, seed=0)[source]

Estimate V-information over repeated splits and report split-assignment uncertainty.

The normal interval describes variability from random train/test assignment conditional on this fixed dataset. It is not a confidence interval for population V-information and does not include model-selection uncertainty.

Parameters:
Return type:

VInformationEstimate

gaussian_mutual_information(rho)[source]

Population I(X;Y) for a valid bivariate-Gaussian correlation rho (nats).

Parameters:

rho (float)

Return type:

float

usability_gap(true_mi, i_v)[source]

Difference between a population MI reference and a finite-sample V-information estimate.

Parameters:
Return type:

float