robustcov

robustcov is a Python/C++ toolkit for estimating reliable multivariate geometry when ordinary covariance is distorted by outliers, heavy tails, limited samples, or unstable directions.

A fitted robust location, covariance, precision matrix, support mask, or similarity geometry can be reused for anomaly detection, monitoring, robust kernels, Gaussian-process input metrics, structured models, and contamination-resistant SHAP and LIME references.

Current release: 0.2.0 · Python: 3.12–3.14 · License: Apache-2.0

GitHub · PyPI · Documentation · Method catalog · Benchmarks and validation

python -m pip install robustcov

Install the optional SHAP and LIME integrations with:

python -m pip install "robustcov[explain]"

Why robust geometry?

Many multivariate workflows quietly depend on an estimated reference geometry:

Mahalanobis anomaly scores use a center and covariance;
whitening and PCA depend on scatter directions;
covariance-drift monitoring compares SPD matrices;
kernels and nearest-neighbor methods depend on an input metric;
SHAP and LIME depend on a background or reference distribution.

A small number of leverage points can move that geometry substantially. The predictive model may remain unchanged while anomaly rankings, similarities, or local explanations change because the reference sample was contaminated.

robustcov addresses that failure mode at the geometry layer. It estimates a robust reference and then passes the resulting matrices, distances, support, or background sample into ordinary scientific-Python and machine-learning workflows.

A compact covariance workflow

import numpy as np
import robustcov as rc

rng = np.random.default_rng(0)

X = rng.standard_t(df=3, size=(400, 5))
X[:30] += 8.0

est = rc.FastMCD(
    quality="balanced",
    random_state=42,
).fit(X)

scores = est.mahalanobis(X)

print("robust location:", est.location_)
print("support size:", int(est.support_.sum()))
print("largest distances:", np.argsort(scores)[-10:])

The same fitted geometry can be used by RobustOutlierDetector, diagnostic reports, covariance-comparison utilities, robust kernels, or downstream code that accepts a covariance or precision matrix.

Robust references for SHAP and LIME

SHAP and LIME are not reimplemented. robustcov prepares a contamination-resistant reference and passes it to the established packages.

import robustcov as rc

reference = rc.RobustExplanationReference(
    estimator=rc.FastMCD(random_state=0),
    max_samples=100,
).fit(X_reference)

shap_explainer = rc.make_shap_explainer(
    model.predict_proba,
    reference,
    algorithm="permutation",
)
shap_values = shap_explainer(X_to_explain)

lime_explainer = rc.make_lime_tabular_explainer(
    reference,
    mode="classification",
    feature_names=feature_names,
    class_names=class_names,
)

The fitted reference exposes its background sample, robust location, covariance, precision, support mask, and selected row indices. Users can therefore inspect exactly which observations define the explanation geometry.

Why this can matter

The release evidence includes a binary-Iris example where the model and query are held fixed while 12 severe leverage rows are injected only into the explainer reference data.

Reference used for the explanation	SHAP attribution drift
Contaminated empirical reference	2.528
Robust reference	0.388

The robust support retained 0 of the 12 injected leverage rows.

This is the main reason for the integration: explanation methods can be correct while their reference distribution is not representative. robustcov supplies a robust reference without creating a competing explanation framework.

Read the robust SHAP and LIME workflow

Main workflow families

Problem	Typical robustcov output	Downstream use
Separated contamination	robust subset, location, covariance	anomaly screening, whitening, diagnostics
Heavy tails or small samples	regularized robust scatter	stable distances and covariance geometry
High-dimensional data	shrinkage or structured covariance	precision estimation, PCA, kernels
Multiple legitimate regimes	local robust models	cluster-aware anomaly diagnostics
Covariance change	SPD distances and geodesics	drift and regime monitoring
Contaminated explainer background	robust reference sample and covariance	SHAP and LIME
Distorted feature geometry	robust precision or similarity	kernels, GP input metrics, retrieval

The package includes FastMCD and Tyler-family estimators, Student-t and Cauchy scatter, MRCD/MMCD-style methods, cellwise and structured estimators, robust PCA and precision tools, anomaly and monitoring utilities, SPD geometry, and optional explanation adapters.

The complete estimator inventory and support status belong in the documentation rather than on this page:

Robust similarity and SPD geometry

A fitted robust scatter matrix defines a full-matrix input metric rather than an isotropic Euclidean one.

import robustcov as rc
from robustcov.kernels import robust_rbf_kernel

est = rc.RegularizedCauchy(alpha=0.10).fit(X_train)

K = robust_rbf_kernel(
    X_train,
    X_train,
    covariance=est.covariance_,
    length_scale=1.0,
)

The same idea supports covariance-drift monitoring, robust embedding retrieval, nearest-neighbor reranking, and kernel or Gaussian-process input metrics. robustcov supplies the robust geometry; it does not replace the downstream learning framework.

Read about SPD geometry · Read about robust kernels

Evidence and reproducibility

Version 0.2.0 was prepared with a release-evidence pipeline rather than manually copied benchmark numbers. The repository records:

the source revision and implementation-tree digest;
Python, NumPy, SciPy, compiler, platform, and thread settings;
deterministic statistical-validation outputs;
benchmark CSV and plot hashes;
the contaminated-Iris explanation result;
wheel and source-distribution audits;
native boundary checks and an AddressSanitizer/UndefinedBehaviorSanitizer workflow.

FastMCD uses exact SciPy chi-square calibration, reports distinct raw, C-step, and final objectives, and exposes truthful convergence and iteration diagnostics. The native extension validates shapes, sizes, finite values, and scalar parameters before entering numerical kernels.

Benchmark timing remains machine-specific. The documentation emphasizes estimator trade-offs and reproducible commands rather than universal speed claims.

Validation report · Benchmark gallery · Release history

Where it helps—and where it does not

robustcov is most useful when the downstream task depends on covariance-shaped structure and the reference data may contain outliers, heavy tails, leverage points, or unstable directions.

Good fits include:

interpretable multivariate anomaly screening;
robust covariance or correlation structure;
small-sample and high-dimensional scatter estimation;
covariance drift and regime comparison;
robust whitening, PCA, precision, and factor workflows;
robust similarity for kernels, retrieval, and embeddings;
contamination-resistant SHAP and LIME reference data.

It is not intended to replace general-purpose machine-learning libraries, probabilistic programming systems, deep anomaly-detection frameworks, or domain validation. A robust covariance score can prioritize cases for review; it does not create ground-truth labels or causal explanations.

Development status

robustcov is pre-1.0 research software. The public API is explicitly classified by stability tier, public exports are checked against a machine-readable manifest, and interface changes follow a documented deprecation policy. Experimental methods remain clearly separated.

The package provides native and native-free builds, cross-platform wheels for Python 3.12–3.14, optional OpenMP acceleration, and an Apache-2.0 license.

For implementation details, algorithms, complete examples, and references, use the maintained documentation:

Documentation · Quickstart · Examples · Citation