NumpyMahalanobisHead

class probly.layers.numpy.NumpyMahalanobisHead(num_classes: int, feature_dim: int)

Bases: object

Class-conditional Gaussian head with a tied covariance (Mahalanobis OOD).

Numpy counterpart of probly.layers.torch.MahalanobisHead, implementing the Gaussian-discriminant-analysis confidence of the out-of-distribution detector of [LLLS18]. One mean is estimated per class, while a single covariance (its inverse, the precision matrix) is shared across all classes. After fitting, score() gives each sample a per-class confidence (higher = closer to a class centroid = more in-distribution), of which downstream code typically takes the max over classes.

Variables:

• means – Per-class mean vectors, shape (num_classes, feature_dim).

• precision – Shared (tied) precision matrix, shape (feature_dim, feature_dim).

Initialize with zero means and an identity precision.

Parameters:

• num_classes – Number of classes (one mean vector per class).

• feature_dim – Dimensionality of the feature vectors.

__call__(features: ArrayLike | np.ndarray) → np.ndarray

Alias for score().

fit(features: ArrayLike | np.ndarray, labels: ArrayLike | np.ndarray, covariance_estimator: CovarianceEstimator | None = None) → None

Estimate per-class means and the shared (tied) precision matrix.

Each class mean is the empirical mean of its features. The shared covariance is the empirical covariance of all per-class-centered features (pooled within-class scatter). Its inverse is obtained from covariance_estimator when given, and otherwise from the Hermitian pseudo-inverse, which stays finite even when the pooled covariance is rank-deficient, e.g. for dead post-ReLU feature dimensions.

Parameters:

• features – Feature vectors of shape (N, feature_dim).

• labels – Integer class labels of shape (N,), taking values in [0, num_classes).

• covariance_estimator – Optional fitted-on-demand covariance estimator used to derive the precision matrix, e.g. sklearn.covariance.LedoitWolf() for a shrunk estimate. When None the pseudo-inverse of the empirical covariance is used.

Raises:

ValueError – If no sample matches any class index in [0, num_classes), leaving the covariance undefined.

score(features: ArrayLike | np.ndarray) → np.ndarray

Compute per-class Mahalanobis confidence scores for each sample.

Returns -0.5 * (z - mu_c)^T P (z - mu_c) for every class c.

Parameters:

features – Feature vectors of shape (N, feature_dim).

Returns:

Per-class confidence scores of shape (N, num_classes).