robustcov documentation¶

Why robustcov?¶

Many machine-learning workflows use covariance geometry implicitly: anomaly scores, whitening, Mahalanobis distances, kernel similarities, Gaussian models, portfolio risk, and embedding retrieval. Empirical covariance is fast and useful, but it can be strongly distorted by outliers, heavy tails, leverage points, and small contaminated subsets of the data.

robustcov provides robust covariance and scatter estimators together with practical machine-learning workflows around them: anomaly detection, diagnostics, benchmark galleries, robust kernel/input metrics, and SPD geometry utilities.

The typical workflow is:

contaminated data
     -> robust scatter estimate
     -> robust precision / Mahalanobis geometry
     -> anomaly score, whitening, similarity, kernel, or diagnostic

When should I use this?¶

Use robustcov when covariance geometry matters and the data may contain outliers, heavy tails, small contaminated subsets, leverage points, or unstable directions. Typical use cases include tabular anomaly detection, sensor monitoring, financial features, embeddings, robust preprocessing, and kernel methods.

Project status¶

robustcov is under active development. The implemented estimators, examples, and diagnostics are tested and documented, but some APIs may evolve as the package matures. See API stability for the current stability policy.

robustcov is an experimental robust covariance, heavy-tail scatter, anomaly diagnostics, and benchmark-gallery package with a C++/pybind core.

The project is organized around two reader-friendly entry points:

Use-case
gallery

Start from your application

Topic-based gallery: finance/risk, fraud/security, sensors/quality, biomedical/images/embeddings, real ML datasets, and preprocessing.

Start from the evidence

Small-sample heavy-tail ranking, speed comparisons, OpenMP scaling, anomaly baselines, and hard contamination scenarios.

Math
and API

Understand the estimators

FastMCD, Tyler shape, Regularized Tyler, Student-t scatter, Cauchy scatter, diagnostics, and references.

Core ideas¶

FastMCD gives efficient classical robust covariance for separable contamination when n is comfortably larger than p.
RegularizedCauchy and StudentTScatter target small-sample, high-dimensional, heavy-tailed covariance problems.
Robust-distance diagnostics turn fitted estimators into interpretable anomaly scores, profiles, QQ plots, and reports.
Optional OpenMP acceleration improves larger workloads and benchmark/report generation.

User guide

Reference and evidence

Why not focus on MVE?¶

Minimum-volume ellipsoid estimators are historically important, but the benchmark evidence in this project points to a stronger niche: efficient MCD for separable outliers and regularized heavy-tail scatter for small samples. MVE may become an experimental add-on later, but it is not currently the core differentiator.