robustcov is a research-oriented Python/C++ package for robust covariance and scatter estimation, SPD geometry, anomaly diagnostics, and robust kernel/similarity workflows.
It is designed for workflows where ordinary covariance estimates become unstable: contaminated samples, heavy-tailed data, small-sample regimes, high-dimensional scatter estimation, Mahalanobis-style anomaly screening, covariance drift monitoring, and robust input-metric construction for kernel or similarity methods.
The package combines a Python API with C++/pybind11 kernels for selected compute-heavy routines. The focus is practical robust scatter estimation, diagnostic reporting, SPD geometry utilities, robust input metrics, benchmark galleries, and application-oriented examples. It is not intended to be a full probabilistic modeling framework or a replacement for general-purpose machine-learning libraries.
Links: GitHub · PyPI · Documentation · License: Apache-2.0
robustcov is independently maintained volunteer open-source research software released under the Apache-2.0 license.
python -m pip install robustcovimport numpy as np
import robustcov as rc
rng = np.random.default_rng(0)
# Heavy-tailed data with injected outliers
X = rng.standard_t(df=3, size=(400, 5))
X[:30] += 8.0
est = rc.FastMCD(quality="balanced", random_state=42).fit(X)
print(est.location_)
print(est.covariance_)
print(est.radial_kurtosis_)
det = rc.RobustOutlierDetector(
estimator=est,
contamination=0.075,
).fit(X)
print(det.labels_)Classical covariance is highly sensitive to outliers and heavy tails. A small number of extreme observations can inflate covariance estimates, rotate principal directions, distort Mahalanobis distances, and hide the very anomalies one wants to detect.
This is especially visible in settings such as:
robustcov provides robust covariance and scatter estimators that try to separate central structure from contamination or diffuse heavy tails. The resulting robust geometry can then be used for diagnostics, anomaly scores, plots, benchmark comparisons, SPD-matrix comparisons, and robust kernel or similarity methods.
The package currently focuses on six related tasks:
Main public APIs include:
FastMCD;MinCovDet;RegularizedTyler;StudentTScatter;RegularizedCauchy;KLRegularizedTyler;WieselTyler;HellingerRegularizedTyler;AutoRobustScatter;RobustOutlierDetector;AutoRobustAnomalyDetector;ClusterRobustOutlierDetector;RobustMedianImputer;robustcov.geometry;The package is not intended to be a replacement for scikit-learn, SciPy, or GPyTorch. It is narrower: robust covariance, robust scatter, robust geometry, robust distances, and input-metric tools for interpretable diagnostics and ML workflows.
Most workflows are built around robust squared Mahalanobis distances. Given observations
x_i \in \mathbb{R}^p,
a robust location estimate
\hat\mu
and a robust covariance or scatter estimate
\hat\Sigma,
the robust squared distance is
d_i^2 = (x_i - \hat\mu)^T \hat\Sigma^{-1} (x_i - \hat\mu).
Large robust distances indicate observations that are far from the estimated central elliptical structure.
This idea is simple, but the quality of the result depends heavily on the covariance estimate. If the covariance is fitted using all outliers, then the distances may be distorted. robustcov focuses on estimators that are less sensitive to this failure mode.
A fitted robust scatter estimate gives more than a covariance matrix. It defines geometry on the cone of symmetric positive-definite matrices and a robust geometry on the input space.
The typical chain is:
robust scatter
↓
robust precision
↓
robust Mahalanobis distance
↓
robust similarity / kernel geometryThe robustcov.geometry module includes utilities for SPD matrix normalization, matrix powers, matrix logarithms and exponentials, affine-invariant distance, log-Euclidean distance, geodesic interpolation, and Tyler fixed-point diagnostics.
import numpy as np
import robustcov as rc
import robustcov.geometry as rcg
rng = np.random.default_rng(8)
X_baseline = rng.normal(size=(400, 5))
X_current = rng.normal(size=(400, 5))
X_current[:, 0] *= 1.8
S_ref = rc.FastMCD(contamination=0.08, random_state=0).fit(X_baseline).covariance_
S_now = rc.FastMCD(contamination=0.08, random_state=0).fit(X_current).covariance_
drift_score = rcg.affine_invariant_distance(S_ref, S_now)
print("covariance drift:", drift_score)This is useful for covariance drift monitoring, estimator stability diagnostics, robust whitening, comparing empirical and robust scatter, and embedding or nearest-neighbor workflows where Euclidean distance may be distorted by leverage directions.
A robust scatter estimate can also define a robust input metric. Instead of using an isotropic Euclidean distance, kernel methods can use a robust Mahalanobis geometry induced by a fitted covariance or scatter estimator.
For example, a robust RBF-style similarity can be written as
k_R(x, y) = \exp\left( -\frac{1}{2\ell^2} (x-y)^T \hat\Sigma_R^{-1} (x-y) \right),
where
\hat\Sigma_R
is a robust covariance or scatter estimate.
import numpy as np
import robustcov as rc
from robustcov.kernels import robust_rbf_kernel
rng = np.random.default_rng(9)
X_train = rng.standard_t(df=3, size=(250, 8))
est = rc.RegularizedCauchy(alpha=0.10).fit(X_train)
K = robust_rbf_kernel(
X_train,
X_train,
covariance=est.covariance_,
length_scale=1.0,
)
print(K.shape)The package also includes sklearn-style and GPyTorch-style adapters for robust input metrics. These utilities target the input geometry of kernel methods and Gaussian-process workflows. They do not replace GP inference, likelihood modeling, posterior computation, or training loops.
FastMCD is the main estimator for a classical contamination setting: most observations form a central cloud, while a minority are separated outliers.
import numpy as np
import robustcov as rc
rng = np.random.default_rng(1)
X = rng.normal(size=(600, 4))
X[:40] += np.array([7.0, 0.0, 7.0, 0.0])
mcd = rc.FastMCD(
quality="balanced",
random_state=0,
).fit(X)
print("location:", np.round(mcd.location_, 3))
print("support size:", int(mcd.support_.sum()))
print("radial kurtosis:", round(mcd.radial_kurtosis_, 3))FastMCD is useful when
n \gg p
and the outliers are at least partly separable from the central data. It is less appropriate when the data are mostly heavy-tailed but not clearly split into clean and contaminated subsets.
For diffuse heavy tails, small samples, or high-dimensional regimes, hard subset selection may not be the right tool. robustcov includes several iteratively reweighted scatter estimators.
import numpy as np
import robustcov as rc
rng = np.random.default_rng(2)
X = rng.standard_t(df=2.5, size=(120, 40))
cauchy = rc.RegularizedCauchy(alpha=0.10).fit(X)
student = rc.StudentTScatter(df=3, alpha=0.05).fit(X)
tyler = rc.RegularizedTyler(
alpha=0.10,
scale_correction="radial_median",
).fit(X)
print("Cauchy condition:", np.linalg.cond(cauchy.covariance_))
print("Student-t radial kurtosis:", student.radial_kurtosis_)
print("Tyler scale:", getattr(tyler, "scale_", None))The main heavy-tail estimators are:
RegularizedCauchy;StudentTScatter;RegularizedTyler.RegularizedCauchy applies strong radial downweighting with shrinkage. It is intended for very heavy-tailed samples and small-sample regimes.
StudentTScatter uses Student-t style weights. Smaller degrees of freedom correspond to heavier tails and more aggressive downweighting.
RegularizedTyler estimates robust shape. Tyler-style estimators are scale-free unless a scale correction is applied, so they are often best interpreted through robust shape and robust distances.
AutoRobustScatter is a practical exploratory selector. It fits candidate estimators and chooses one using diagnostic or stability-based criteria.
import numpy as np
import robustcov as rc
rng = np.random.default_rng(3)
X = rng.standard_t(df=3, size=(300, 12))
X[:20] += 5.0
auto = rc.AutoRobustScatter(selection="diagnostic").fit(X)
print(auto.best_estimator_name_)
print(auto.summary())This is not an oracle. It is meant as a helpful first pass when the user does not yet know whether the data are better described as classical contamination, diffuse heavy tails, or a small-sample high-dimensional problem.
The robust covariance estimators can be wrapped into anomaly detectors.
import numpy as np
import robustcov as rc
rng = np.random.default_rng(4)
X = rng.normal(size=(500, 6))
X[:25] += 6.0
detector = rc.RobustOutlierDetector(
estimator=rc.FastMCD(quality="fast", random_state=42),
threshold="empirical",
alpha=0.95,
).fit(X)
scores = detector.decision_function(X)
labels = detector.predict(X)
print("detected outliers:", int((labels == -1).sum()))
print("largest scores:", np.sort(scores)[-5:])The anomaly score is based on robust distance. This makes the results interpretable: a point is suspicious because it is far from the robustly estimated center relative to the robust covariance or scatter shape.
robustcov includes diagnostic summaries to help interpret fitted estimators.
import numpy as np
import robustcov as rc
rng = np.random.default_rng(5)
X = rng.standard_t(df=3, size=(400, 8))
est = rc.RegularizedCauchy(alpha=0.10).fit(X)
report = rc.diagnostic_report(est)
print(report.summary())Reports are intended to summarize quantities such as:
The package also includes plotting helpers for robust distances, QQ plots, covariance heatmaps, benchmark curves, and anomaly panels. Most plotting functions support saving figures through output_path, which makes them useful for reports and documentation.
A single global robust covariance model is not always appropriate. If a data set contains several legitimate clusters or regimes, a global robust estimator may treat small valid modes as anomalies.
ClusterRobustOutlierDetector provides a cluster-then-local-robust-scatter workflow.
import numpy as np
import robustcov as rc
rng = np.random.default_rng(7)
X1 = rng.normal(loc=(-3, 0), scale=0.8, size=(250, 2))
X2 = rng.normal(loc=(3, 0), scale=0.8, size=(250, 2))
X = np.vstack([X1, X2])
X[:20] += np.array([0, 6])
det = rc.ClusterRobustOutlierDetector(
n_clusters=2,
contamination=0.05,
random_state=0,
).fit(X)
scores = det.decision_function(X)
labels = det.predict(X)
print("detected outliers:", int((labels == -1).sum()))This is not a full robust mixture model. It is a practical diagnostic workflow for multimodal data where local robust distances are more meaningful than one global covariance estimate.
The package includes a robust median imputer for simple preprocessing pipelines.
import numpy as np
import robustcov as rc
X = np.array([
[1.0, 2.0, np.nan],
[2.0, np.nan, 3.0],
[100.0, 4.0, 4.0],
])
imputer = rc.RobustMedianImputer().fit(X)
X_clean = imputer.transform(X)
print(X_clean)The goal is not to replace full-featured preprocessing libraries. The helper exists so robust covariance examples can handle simple missing-value cases without leaving the package.
If OpenMP is available at build time, the C++ backend can parallelize selected operations.
import robustcov as rc
print("OpenMP available:", rc.has_openmp())
print("threads:", rc.get_num_threads())
rc.set_num_threads(4)For reproducible timing, avoid thread oversubscription from BLAS libraries:
#| eval: false
OMP_NUM_THREADS=4 OPENBLAS_NUM_THREADS=1 MKL_NUM_THREADS=1 \
python benchmarks/openmp_scaling.py \
--n 8000 \
--p 20 \
--threads 1 2 4 \
--csv results/openmp_scaling.csvThe benchmark gallery is intended to show trade-offs rather than universal wins.
Examples include:
#| eval: false
python benchmarks/speed_estimators.py
python benchmarks/accuracy_vs_contamination.py
python benchmarks/small_sample_heavy_tail.py
python benchmarks/fastmcd_quality_speed_tradeoff.py
python benchmarks/anomaly_detection_baselines.py
python benchmarks/openmp_scaling.py
python benchmarks/make_report.py --outdir results/reportThe benchmark documentation is intentionally conservative. robustcov is strongest when the signal is covariance-shaped, heavy-tailed, high-dimensional, or benefits from interpretable robust distances. It is not expected to win every anomaly-detection benchmark.
For fair local benchmarking, report:
The examples directory includes practical scripts for different application patterns.
#| eval: false
python examples/run_use_case_gallery.py --all
python examples/use_case_finance_risk.py
python examples/use_case_multimodal_anomaly.py
python examples/use_case_sensor_anomaly.py
python examples/use_case_ml_preprocessing.py
python examples/gp_robust_input_metric.py
python examples/spd_geometry_diagnostics.py
python examples/spd_geometry_ml_use_cases.py
python examples/embedding_reranking_robust_geometry.pyUse cases include:
The examples are meant to be reproducible templates rather than leaderboard claims.
External examples live separately from the normal test suite because they may require manual data downloads or separate dataset licenses.
#| eval: false
python examples_external/kaggle_credit_card_fraud.py \
--data examples_external/data/creditcard.csv \
--outdir results/external/credit_card_fraud
python examples_external/collect_external_results.py \
--root results/external \
--outdir results/external_registryThe external-data pages should be read as evidence and diagnostics, not as universal claims. Some data sets are good fits for robust covariance methods, some are competitive but slower, and some are included mainly to show limitations.
The package connects several robust-statistics and geometry ideas:
A simplified view of the robust-distance and robust-similarity workflow is:
raw data
↓
robust location and scatter estimation
↓
robust precision / SPD geometry
↓
robust squared distances
↓
diagnostic thresholds, robust similarities, or kernel matrices
↓
outlier labels, anomaly scores, plots, reports, and ML workflow componentsFor heavy-tailed M-estimators, the core idea is iterative radial reweighting. Observations with large robust distance receive smaller weights when updating the scatter matrix.
For example, a Student-t style weight has the form
w_i(d_i^2) = \frac{\nu + p}{\nu + d_i^2},
where
\nu
is the degrees-of-freedom parameter and
p
is the dimension.
Tyler-style estimators use a shape equation of the form
\hat S = \frac{p}{n} \sum_{i=1}^n \frac{z_i z_i^T}{z_i^T \hat S^{-1} z_i}, \qquad z_i = x_i - \hat\mu.
Regularization then shrinks the update toward a stable target matrix,
S_{\text{new}} = (1-\alpha)S_{\text{robust}} + \alpha T.
This improves conditioning in small-sample or high-dimensional regimes.
robustcov is an alpha-stage scientific package. The current public release focuses on:
Out of scope for the current alpha:
The package is best understood as a focused robust scatter geometry toolkit: robust covariance and scatter estimation, robust distances, SPD geometry, anomaly diagnostics, and robust input metrics for ML workflows.
P. J. Rousseeuw. “Least Median of Squares Regression.”
P. J. Rousseeuw and K. Van Driessen. “A Fast Algorithm for the Minimum Covariance Determinant Estimator.”
D. E. Tyler. “A Distribution-Free M-Estimator of Multivariate Scatter.”
E. Ollila, D. E. Tyler, V. Koivunen, and H. V. Poor. Work on complex elliptically symmetric distributions and robust covariance.
Y. Chen, A. Wiesel, and A. O. Hero. Work on shrinkage covariance estimation under elliptical models.
R. A. Maronna, R. D. Martin, V. J. Yohai, and M. Salibián-Barrera. Robust Statistics: Theory and Methods.
P. J. Huber and E. M. Ronchetti. Robust Statistics.
X. Pennec, P. Fillard, and N. Ayache. “A Riemannian Framework for Tensor Computing.”
V. Arsigny, P. Fillard, X. Pennec, and N. Ayache. “Geometric Means in a Novel Vector Space Structure on Symmetric Positive-Definite Matrices.”
T. W. Anderson. An Introduction to Multivariate Statistical Analysis.