Fisher information¶

fisher_information ¶

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

Estimate unbinned Fisher information.

Parameters:

scores (ArrayLike) –

Finite score matrix with shape [N, P].
weights (ArrayLike | None, default: None ) –

Optional finite, nonnegative weights with shape [N].

Returns:

ndarray –

Matrix sum_i w_i s_i s_i.T with shape [P, P].

binned_fisher_information ¶

binned_fisher_information(scores: ArrayLike, assignments: ArrayLike, weights: ArrayLike | None = None, *, n_bins: int | None = None, execution: ExecutionConfig | None = None) -> ndarray

Estimate Fisher information retained by hard bin counts.

Parameters:

scores (ArrayLike) –

Finite score matrix with shape [N, P].
assignments (ArrayLike) –

Integer bin label for every input row, with shape [N].
weights (ArrayLike | None, default: None ) –

Optional finite, nonnegative weights with shape [N].
n_bins (int | None, default: None ) –

Total number of bins. Inferred from the largest effective label when omitted; provide it explicitly to preserve trailing empty bins.

Returns:

ndarray –

Hard-binned Fisher matrix with shape [P, P].

fractional_fisher_information ¶

fractional_fisher_information(scores: ArrayLike, responsibilities: ArrayLike, weights: ArrayLike | None = None, *, execution: ExecutionConfig | None = None) -> ndarray

Estimate Fisher information retained by fractional assignments.

Parameters:

scores (ArrayLike) –

Finite score matrix with shape [N, P].
responsibilities (ArrayLike) –

Finite nonnegative responsibilities with shape [N, B] whose effective rows sum to one.
weights (ArrayLike | None, default: None ) –

Optional finite, nonnegative weights with shape [N].

Returns:

ndarray –

Fractionally binned Fisher matrix with shape [P, P].

information_report ¶

information_report(scores: ArrayLike, assignments: ArrayLike, weights: ArrayLike | None = None, *, n_bins: int | None = None, rank_rtol: float | None = None, execution: ExecutionConfig | None = None) -> InformationReport

Build retained-information and occupancy diagnostics for hard bins.

Parameters:

scores (ArrayLike) –

Finite score matrix with shape [N, P].
assignments (ArrayLike) –

Integer bin label for every input row, with shape [N].
weights (ArrayLike | None, default: None ) –

Optional finite, nonnegative weights with shape [N].
n_bins (int | None, default: None ) –

Total number of bins, including empty bins. Inferred when omitted.
rank_rtol (float | None, default: None ) –

Relative threshold used to select informative Fisher directions.

Returns:

InformationReport –

Unregularized Fisher matrices, normalized retention, spectrum, and per-bin occupancy diagnostics.

Notes

The between-cell algebra is exact for the supplied vectors. When the scores are estimates s_hat rather than the model score s, the report measures Var(E[s_hat | q]), not Var(E[s | q]), and is a surrogate for the model's own Fisher information.

profiled_information_report ¶

profiled_information_report(scores: ArrayLike, assignments: ArrayLike, *, interest: tuple[int, ...], weights: ArrayLike | None = None, n_bins: int | None = None, schema: ScoreSchema | None = None, execution: ExecutionConfig | None = None) -> ProfiledInformationReport

Build same-label profiled-\(D_s\) diagnostics without regularization.

Parameters:

scores (ArrayLike) –

Finite score matrix with shape [N, P] in the declared parameter order.
assignments (ArrayLike) –

Integer bin label for every input row.
interest (tuple[int, ...]) –

Unique nonnegative score-column indices for parameters of interest.
weights (ArrayLike | None, default: None ) –

Optional nonnegative measure weights.
n_bins (int | None, default: None ) –

Total number of bins, including empty bins.

Returns:

ProfiledInformationReport –

Full-data and same-label Schur information plus determinant retention.

efficient_scores ¶

efficient_scores(scores: ArrayLike, *, interest: tuple[int, ...], weights: ArrayLike | None = None, execution: ExecutionConfig | None = None) -> ndarray

Project scores with the full-information nuisance regression.

This constructs the explicit lower-dimensional upper problem for profiled information. Quantizing the result with ordinary D-optimality is not the same finite task as profiling nuisance from the resulting labels.

Parameters:

scores (ArrayLike) –

Finite score matrix in the declared parameter order.
interest (tuple[int, ...]) –

Unique nonnegative score-column indices for parameters of interest.
weights (ArrayLike | None, default: None ) –

Optional nonnegative reference-measure weights used for the full information regression.

Returns:

ndarray –

Full-information efficient scores with shape [N, len(interest)].

efficient_score_bound ¶

efficient_score_bound(scores: ArrayLike, *, interest: tuple[int, ...], weights: ArrayLike | None = None, n_bins: int, config: ScalarDPConfig | None = None, execution: ExecutionConfig | None = None) -> EfficientScoreBound

Certify a ceiling on profiled information by quantizing the efficient score.

The full-data efficient score \(\hat s=s_\psi-B^\ast s_\lambda\) uses the nuisance regression of the unbinned information matrix. Efficient-score domination bounds the same-label profiled information of every hard rule \(q\) with at most n_bins cells by the between-cell information of \(\hat s\) under that rule, so the best n_bins-cell rule of the efficient score certifies a ceiling for the whole score space. For one parameter of interest that best rule has ordered interval cells and is found exactly by weighted interval dynamic programming, which makes the returned ceiling both certified and cheap.

The returned labels are also the natural initializer for optimize_partition with ProfiledDOptimality: they already solve the relaxed upper problem, so profiled exchange starts inside the efficient-score geometry instead of at generic k-means seeding.

Parameters:

scores (ArrayLike) –

Finite score matrix with shape [N, P] in the declared parameter order.
interest (tuple[int, ...]) –

Unique nonnegative score-column indices for parameters of interest. Only one interest column is supported.
weights (ArrayLike | None, default: None ) –

Optional finite, nonnegative weights with shape [N].
n_bins (int) –

Cell budget the bound is certified for.
config (ScalarDPConfig | None, default: None ) –

Exact scalar solver settings. Whitening a scalar coordinate is a strictly positive rescaling, so it changes neither the labels nor the bound; rank_rtol still rejects a numerically vanishing efficient score and max_rows still bounds the exact quadratic recursion.

Returns:

EfficientScoreBound –

Certified log-scale ceiling, the interval labels attaining it, and the efficient scores it was computed from.

Raises:

NotImplementedError –

When more than one interest column is requested. A multivariate efficient score needs a genuine multivariate D solver, which would make the returned value a heuristic rather than a certificate.

Notes

The bound follows the uncentered convention of binned_fisher_information: scores are never mean-centered, so the between-cell quantity is a weighted second moment of cell means about the score-space origin. This matches PartitionResult.objective for the profiled criterion exactly, which is what makes the reported gap meaningful.