robustmodels 0.1.0__tar.gz → 0.1.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {robustmodels-0.1.0 → robustmodels-0.1.1}/.gitignore +2 -0
- {robustmodels-0.1.0 → robustmodels-0.1.1}/CHANGELOG.md +16 -0
- robustmodels-0.1.1/CITATION.cff +18 -0
- robustmodels-0.1.1/CONTRIBUTING.md +77 -0
- robustmodels-0.1.1/PKG-INFO +211 -0
- robustmodels-0.1.1/README.md +180 -0
- {robustmodels-0.1.0 → robustmodels-0.1.1}/docs/conf.py +1 -0
- {robustmodels-0.1.0 → robustmodels-0.1.1}/docs/covariance.md +37 -4
- {robustmodels-0.1.0 → robustmodels-0.1.1}/docs/index.md +2 -0
- {robustmodels-0.1.0 → robustmodels-0.1.1}/docs/location.md +20 -2
- robustmodels-0.1.1/docs/references.md +227 -0
- robustmodels-0.1.1/docs/scale.md +131 -0
- {robustmodels-0.1.0 → robustmodels-0.1.1}/pyproject.toml +11 -3
- {robustmodels-0.1.0 → robustmodels-0.1.1}/src/robustmodels/__init__.py +1 -1
- {robustmodels-0.1.0 → robustmodels-0.1.1}/src/robustmodels/covariance.py +70 -27
- {robustmodels-0.1.0 → robustmodels-0.1.1}/src/robustmodels/location.py +18 -2
- {robustmodels-0.1.0 → robustmodels-0.1.1}/src/robustmodels/scale.py +32 -12
- {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/test_covariance.py +172 -1
- {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/test_location.py +5 -0
- {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/test_scale.py +35 -0
- robustmodels-0.1.0/PKG-INFO +0 -151
- robustmodels-0.1.0/README.md +0 -120
- robustmodels-0.1.0/docs/scale.md +0 -95
- {robustmodels-0.1.0 → robustmodels-0.1.1}/LICENSE +0 -0
- {robustmodels-0.1.0 → robustmodels-0.1.1}/docs/changelog.md +0 -0
- {robustmodels-0.1.0 → robustmodels-0.1.1}/src/robustmodels/_validation.py +0 -0
- {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/conftest.py +0 -0
- {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/data/r_reference.json +0 -0
- {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/reference.py +0 -0
- {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/test_r_parity.py +0 -0
- {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/test_selection.py +0 -0
|
@@ -1,5 +1,21 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.1 (2026-11-11)
|
|
4
|
+
|
|
5
|
+
- Stabilize univariate MCD window variances in the presence of extreme outliers.
|
|
6
|
+
- Finish slow M-scale iterations with a bracketed root solver.
|
|
7
|
+
- Select MRCD's common regularization weight according to the published rule.
|
|
8
|
+
- Reject MM tuning combinations that violate the loss-ordering condition.
|
|
9
|
+
- Warn when M-location reaches its iteration limit without convergence.
|
|
10
|
+
- Add method citations and clarify finite-sample, complexity and optimization limits.
|
|
11
|
+
|
|
12
|
+
- Redesign the PyPI overview with worked examples and an estimator selection guide.
|
|
13
|
+
- Move development and release instructions to `CONTRIBUTING.md`.
|
|
14
|
+
- Test every line and branch, require 100% coverage in CI, and report it to Codecov.
|
|
15
|
+
- Add coverage and download badges.
|
|
16
|
+
- Link Tarr's thesis through its permanent University of Sydney handle.
|
|
17
|
+
- Add `CITATION.cff`.
|
|
18
|
+
|
|
3
19
|
## 0.1.0 (2026-11-09)
|
|
4
20
|
|
|
5
21
|
First release.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
cff-version: 1.2.0
|
|
2
|
+
message: "If you use this software, please cite it using these metadata."
|
|
3
|
+
title: "robustmodels: robust statistics for Python"
|
|
4
|
+
type: software
|
|
5
|
+
authors:
|
|
6
|
+
- name: omarbecerrasierra
|
|
7
|
+
version: 0.1.1
|
|
8
|
+
date-released: "2026-11-11"
|
|
9
|
+
license: BSD-3-Clause
|
|
10
|
+
repository-code: "https://github.com/omarbecerrasierra/robustmodels"
|
|
11
|
+
url: "https://omarbecerrasierra.github.io/robustmodels/"
|
|
12
|
+
abstract: >-
|
|
13
|
+
Robust estimators of univariate location and scale and of multivariate
|
|
14
|
+
location and scatter, with the scikit-learn estimator interface.
|
|
15
|
+
keywords:
|
|
16
|
+
- robust statistics
|
|
17
|
+
- outliers
|
|
18
|
+
- covariance
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Contributing to robustmodels
|
|
2
|
+
|
|
3
|
+
For bugs, include a small reproducible example, the expected result, the actual
|
|
4
|
+
result, and your Python and dependency versions. For changes to an estimator,
|
|
5
|
+
include a scientific reference and explain the numerical convention being used.
|
|
6
|
+
|
|
7
|
+
## Development setup
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
uv sync --locked --group docs
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Run the tests and style checks:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
uv run pytest
|
|
17
|
+
uv run ruff check .
|
|
18
|
+
uv run ruff format --check .
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Measure line and branch coverage, which CI requires to stay at 100%:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
uv run pytest --cov
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Build and check the distributions:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
uv build
|
|
31
|
+
uvx twine check --strict dist/*
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Run the docstring examples and build the documentation:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
uv run pytest --doctest-modules --pyargs robustmodels
|
|
38
|
+
uv run --group docs sphinx-build -W --keep-going -b html docs docs/_build/html
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
CI tests the installed wheel on Python 3.10–3.14 on Linux, Windows and macOS.
|
|
42
|
+
Python 3.10 jobs use the minimum supported NumPy, SciPy and scikit-learn versions.
|
|
43
|
+
The examples in `docs/` and the docstrings run as tests. The test suite covers
|
|
44
|
+
estimator definitions, statistical properties, edge cases, comparisons with R's
|
|
45
|
+
robustbase and rrcov, and scikit-learn compatibility. A separate CI job checks
|
|
46
|
+
coverage and reports it to Codecov. Mark a line with `# pragma: no cover` only when
|
|
47
|
+
it cannot be reached, and say why in the comment.
|
|
48
|
+
|
|
49
|
+
## Code organization
|
|
50
|
+
|
|
51
|
+
| File in `src/robustmodels` | Contents | Internal dependencies |
|
|
52
|
+
| --- | --- | --- |
|
|
53
|
+
| `location.py` | Location estimators | `scale.py`, `_validation.py` |
|
|
54
|
+
| `scale.py` | Scale, skewness, correction factors and pairwise selection | `_validation.py` |
|
|
55
|
+
| `covariance.py` | Covariance estimators and their fitting steps | `scale.py`, `_validation.py` |
|
|
56
|
+
| `_validation.py` | Input and parameter checks | None |
|
|
57
|
+
|
|
58
|
+
Each method and its steps stay together. `__init__.py` exposes the three public
|
|
59
|
+
modules. Update the relevant docstrings and user guide when changing public
|
|
60
|
+
behavior, including numerical limits and differences from reference software.
|
|
61
|
+
|
|
62
|
+
## Release checklist
|
|
63
|
+
|
|
64
|
+
1. Set the version in `pyproject.toml` and run `uv lock`. Date the changelog entry
|
|
65
|
+
and update the version and release date in `CITATION.cff`.
|
|
66
|
+
2. Validate the README examples and rendered package description, run the checks
|
|
67
|
+
above, and commit the release changes to `main`.
|
|
68
|
+
3. Tag that commit with the matching version, for example `v0.1.1`, and push the
|
|
69
|
+
tag. CI tests and builds the release before publishing.
|
|
70
|
+
4. Review and approve deployment to the `pypi` environment. Trusted publishing
|
|
71
|
+
uploads the distributions without a stored PyPI token.
|
|
72
|
+
5. Verify the version and description on PyPI, then create the matching GitHub
|
|
73
|
+
release using the changelog entry.
|
|
74
|
+
|
|
75
|
+
PyPI descriptions come from `README.md` in the uploaded distribution. Updating
|
|
76
|
+
the README on GitHub alone does not update an existing PyPI release. Use absolute
|
|
77
|
+
URLs for links and check both the wheel and source distribution with Twine.
|
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: robustmodels
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Robust statistics for Python: univariate location and scale, multivariate location and scatter.
|
|
5
|
+
Project-URL: Homepage, https://github.com/omarbecerrasierra/robustmodels
|
|
6
|
+
Project-URL: Documentation, https://omarbecerrasierra.github.io/robustmodels/
|
|
7
|
+
Project-URL: Repository, https://github.com/omarbecerrasierra/robustmodels
|
|
8
|
+
Project-URL: Issues, https://github.com/omarbecerrasierra/robustmodels/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/omarbecerrasierra/robustmodels/blob/main/CHANGELOG.md
|
|
10
|
+
Author: omarbecerrasierra
|
|
11
|
+
License-Expression: BSD-3-Clause
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: MCD,Qn,Sn,covariance,medcouple,outliers,robust statistics
|
|
14
|
+
Classifier: Development Status :: 3 - Alpha
|
|
15
|
+
Classifier: Intended Audience :: Science/Research
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
24
|
+
Classifier: Topic :: Scientific/Engineering
|
|
25
|
+
Classifier: Topic :: Scientific/Engineering :: Mathematics
|
|
26
|
+
Requires-Python: >=3.10
|
|
27
|
+
Requires-Dist: numpy>=1.24
|
|
28
|
+
Requires-Dist: scikit-learn>=1.6
|
|
29
|
+
Requires-Dist: scipy>=1.10
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
# robustmodels
|
|
33
|
+
|
|
34
|
+
**Robust statistics for Python, from individual measurements to multivariate data.**
|
|
35
|
+
|
|
36
|
+
[](https://pypi.org/project/robustmodels/)
|
|
37
|
+
[](https://pypi.org/project/robustmodels/)
|
|
38
|
+
[](https://github.com/omarbecerrasierra/robustmodels/actions/workflows/ci.yml)
|
|
39
|
+
[](https://codecov.io/gh/omarbecerrasierra/robustmodels)
|
|
40
|
+
[](https://pypistats.org/packages/robustmodels)
|
|
41
|
+
[](https://github.com/omarbecerrasierra/robustmodels/blob/main/LICENSE)
|
|
42
|
+
|
|
43
|
+
[User guide](https://omarbecerrasierra.github.io/robustmodels/)
|
|
44
|
+
· [Method references](https://omarbecerrasierra.github.io/robustmodels/references.html)
|
|
45
|
+
· [Source code](https://github.com/omarbecerrasierra/robustmodels)
|
|
46
|
+
· [Report an issue](https://github.com/omarbecerrasierra/robustmodels/issues)
|
|
47
|
+
|
|
48
|
+
A few extreme observations can pull a mean away from the bulk of your data,
|
|
49
|
+
inflate a standard deviation, or distort a covariance matrix. **robustmodels**
|
|
50
|
+
brings established robust estimators into a consistent Python API so you can
|
|
51
|
+
compare summaries, estimate multivariate structure, and investigate unusual
|
|
52
|
+
observations.
|
|
53
|
+
|
|
54
|
+
- **Summarize a sample:** robust location, scale, skewness and tail-weight measures.
|
|
55
|
+
- **Model multivariate data:** six location and covariance estimators, including
|
|
56
|
+
regularized covariance for data with more variables than observations.
|
|
57
|
+
- **Work with familiar tools:** NumPy-compatible inputs and the scikit-learn
|
|
58
|
+
estimator interface for covariance models.
|
|
59
|
+
- **Inspect the methods:** documented formulas, scientific references, numerical
|
|
60
|
+
conventions and executable examples.
|
|
61
|
+
|
|
62
|
+
## Installation
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
python -m pip install robustmodels
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Requires **Python 3.10+**. NumPy, SciPy and scikit-learn are installed as dependencies.
|
|
69
|
+
CI tests Python 3.10–3.14 on Linux, Windows and macOS.
|
|
70
|
+
|
|
71
|
+
## Start with one sample
|
|
72
|
+
|
|
73
|
+
Compare ordinary and robust summaries of a sample containing one extreme value:
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
import numpy as np
|
|
77
|
+
from robustmodels import location, scale
|
|
78
|
+
|
|
79
|
+
x = [1, 2, 2, 3, 4, 100]
|
|
80
|
+
|
|
81
|
+
print(f"Mean: {np.mean(x):.2f}")
|
|
82
|
+
print(f"Hodges–Lehmann: {location.hodges_lehmann(x):.2f}")
|
|
83
|
+
print(f"Standard dev.: {np.std(x, ddof=1):.2f}")
|
|
84
|
+
print(f"Qn scale: {scale.qn(x):.2f}")
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
```text
|
|
88
|
+
Mean: 18.67
|
|
89
|
+
Hodges–Lehmann: 3.00
|
|
90
|
+
Standard dev.: 39.86
|
|
91
|
+
Qn scale: 1.36
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
The robust summaries remain close to the location and spread of the five values
|
|
95
|
+
between 1 and 4. Qn is calibrated to estimate the normal standard deviation and
|
|
96
|
+
includes a finite-sample correction by default.
|
|
97
|
+
|
|
98
|
+
You can also use `location.m_location(x)`, `scale.mad(x)` or
|
|
99
|
+
`scale.medcouple(x)` to estimate a robust center, scale or skewness. The
|
|
100
|
+
[location guide](https://omarbecerrasierra.github.io/robustmodels/location.html)
|
|
101
|
+
and [scale guide](https://omarbecerrasierra.github.io/robustmodels/scale.html)
|
|
102
|
+
explain their tuning and tradeoffs.
|
|
103
|
+
|
|
104
|
+
## Explore multivariate outliers
|
|
105
|
+
|
|
106
|
+
Fit a Minimum Covariance Determinant model and compute squared robust
|
|
107
|
+
Mahalanobis distances. This example adds a shift to ten observations:
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
import numpy as np
|
|
111
|
+
from scipy.stats import chi2
|
|
112
|
+
from robustmodels.covariance import MCD
|
|
113
|
+
|
|
114
|
+
X = np.random.default_rng(0).normal(size=(100, 2))
|
|
115
|
+
X[:10] += 10
|
|
116
|
+
|
|
117
|
+
model = MCD(random_state=0).fit(X)
|
|
118
|
+
distances = model.mahalanobis(X)
|
|
119
|
+
cutoff = chi2.ppf(0.975, df=X.shape[1])
|
|
120
|
+
|
|
121
|
+
print("Robust center:", model.location_.round(2).tolist())
|
|
122
|
+
print("Rows to inspect:", np.flatnonzero(distances > cutoff).tolist())
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
```text
|
|
126
|
+
Robust center: [0.01, 0.1]
|
|
127
|
+
Rows to inspect: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 69]
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
The ten shifted observations are flagged, along with one unshifted observation
|
|
131
|
+
in the tail. Treat these as candidates for investigation. The chi-square cutoff
|
|
132
|
+
is a reference under a multivariate normal model, not an exact finite-sample
|
|
133
|
+
test or a guaranteed false-positive rate.
|
|
134
|
+
|
|
135
|
+
The fitted model exposes `location_`, `covariance_`, `precision_` and `support_`.
|
|
136
|
+
Use `mahalanobis(new_X)` to score new observations; it returns **squared**
|
|
137
|
+
distances. Covariance estimators support `get_params`, `set_params` and
|
|
138
|
+
`sklearn.base.clone`.
|
|
139
|
+
|
|
140
|
+
## Choose an estimator
|
|
141
|
+
|
|
142
|
+
| Your task | A starting point | What to consider |
|
|
143
|
+
| --- | --- | --- |
|
|
144
|
+
| Estimate the center of one sample | `location.hodges_lehmann` | No tuning parameter; based on pairwise averages. |
|
|
145
|
+
| Estimate spread with resistance to outliers | `scale.qn` or `scale.mad` | Qn uses pairwise differences; MAD uses deviations from a center. |
|
|
146
|
+
| Describe asymmetry | `scale.medcouple` | Robust skewness; `lmc` and `rmc` describe the tails. |
|
|
147
|
+
| Estimate covariance when observations outnumber variables | `MCD` | Supports random or deterministic starts. |
|
|
148
|
+
| Estimate covariance when variables outnumber observations | `MRCD` | Regularizes toward an identity target in standardized coordinates. |
|
|
149
|
+
| Explore other multivariate approaches | `OGK`, `MVE`, `SEstimator`, `MMEstimator` | Different robustness, efficiency and computational tradeoffs. |
|
|
150
|
+
|
|
151
|
+
For example, regularized covariance can be fitted to a wide matrix:
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
import numpy as np
|
|
155
|
+
from robustmodels.covariance import MRCD
|
|
156
|
+
|
|
157
|
+
wide = np.random.default_rng(0).normal(size=(20, 50))
|
|
158
|
+
regularized = MRCD().fit(wide)
|
|
159
|
+
print(regularized.covariance_.shape)
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
```text
|
|
163
|
+
(50, 50)
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
See the [covariance guide](https://omarbecerrasierra.github.io/robustmodels/covariance.html)
|
|
167
|
+
for sample-size requirements, parameters and worked examples.
|
|
168
|
+
|
|
169
|
+
## Available methods
|
|
170
|
+
|
|
171
|
+
| Module | Public estimators |
|
|
172
|
+
| --- | --- |
|
|
173
|
+
| `robustmodels.location` | `hodges_lehmann`, `m_location`, `tau_location`, `trimmed_mean`, `winsorized_mean` |
|
|
174
|
+
| `robustmodels.scale` | `mad`, `qn`, `sn`, `pn`, `tau_scale`, `m_scale`, `medcouple`, `lmc`, `rmc` |
|
|
175
|
+
| `robustmodels.covariance` | `MCD`, `MRCD`, `MVE`, `OGK`, `SEstimator`, `MMEstimator` |
|
|
176
|
+
|
|
177
|
+
The covariance module also exposes `h_alpha_n`, `mcd_consistency` and
|
|
178
|
+
`mcd_small_sample`. Each public method has a docstring with parameters,
|
|
179
|
+
return values, examples and references.
|
|
180
|
+
|
|
181
|
+
## Conventions and scope
|
|
182
|
+
|
|
183
|
+
- Univariate estimators take finite, one-dimensional samples. Empty samples
|
|
184
|
+
return `NaN`; a single observation has zero scale. Handle missing and infinite
|
|
185
|
+
values before fitting.
|
|
186
|
+
- Covariance models take matrices with **observations in rows** and variables
|
|
187
|
+
in columns. Set `random_state` for methods that use random starts.
|
|
188
|
+
- Qn, Sn and Pn apply finite-sample corrections by default. Use
|
|
189
|
+
`finite_correction=False` when you need the asymptotic calibration.
|
|
190
|
+
- Robustness depends on the estimator, sample size, dimension and data. No method
|
|
191
|
+
in this package is immune to arbitrary contamination. Multivariate subset
|
|
192
|
+
searches are approximations and do not certify global optima.
|
|
193
|
+
- The package is in **early development**. Its API may change before version 1.0.
|
|
194
|
+
|
|
195
|
+
The [method references](https://omarbecerrasierra.github.io/robustmodels/references.html)
|
|
196
|
+
connect the implementations to their scientific sources and explain differences
|
|
197
|
+
from R conventions. Tests cover statistical properties, edge cases, reference
|
|
198
|
+
comparisons with R's robustbase and rrcov, and scikit-learn compatibility.
|
|
199
|
+
|
|
200
|
+
## Documentation, contributions and citation
|
|
201
|
+
|
|
202
|
+
- **Learn:** the [user guide](https://omarbecerrasierra.github.io/robustmodels/)
|
|
203
|
+
includes the API reference and examples tested alongside the package.
|
|
204
|
+
- **Contribute:** see the [development guide](https://github.com/omarbecerrasierra/robustmodels/blob/main/CONTRIBUTING.md)
|
|
205
|
+
for setup, checks and release instructions. Bug reports and reproducible
|
|
206
|
+
examples are welcome in [Issues](https://github.com/omarbecerrasierra/robustmodels/issues).
|
|
207
|
+
- **Follow changes:** read the [changelog](https://github.com/omarbecerrasierra/robustmodels/blob/main/CHANGELOG.md).
|
|
208
|
+
- **Cite:** use the metadata in [CITATION.cff](https://github.com/omarbecerrasierra/robustmodels/blob/main/CITATION.cff)
|
|
209
|
+
or GitHub's “Cite this repository” option.
|
|
210
|
+
|
|
211
|
+
Released under the [BSD 3-Clause license](https://github.com/omarbecerrasierra/robustmodels/blob/main/LICENSE).
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# robustmodels
|
|
2
|
+
|
|
3
|
+
**Robust statistics for Python, from individual measurements to multivariate data.**
|
|
4
|
+
|
|
5
|
+
[](https://pypi.org/project/robustmodels/)
|
|
6
|
+
[](https://pypi.org/project/robustmodels/)
|
|
7
|
+
[](https://github.com/omarbecerrasierra/robustmodels/actions/workflows/ci.yml)
|
|
8
|
+
[](https://codecov.io/gh/omarbecerrasierra/robustmodels)
|
|
9
|
+
[](https://pypistats.org/packages/robustmodels)
|
|
10
|
+
[](https://github.com/omarbecerrasierra/robustmodels/blob/main/LICENSE)
|
|
11
|
+
|
|
12
|
+
[User guide](https://omarbecerrasierra.github.io/robustmodels/)
|
|
13
|
+
· [Method references](https://omarbecerrasierra.github.io/robustmodels/references.html)
|
|
14
|
+
· [Source code](https://github.com/omarbecerrasierra/robustmodels)
|
|
15
|
+
· [Report an issue](https://github.com/omarbecerrasierra/robustmodels/issues)
|
|
16
|
+
|
|
17
|
+
A few extreme observations can pull a mean away from the bulk of your data,
|
|
18
|
+
inflate a standard deviation, or distort a covariance matrix. **robustmodels**
|
|
19
|
+
brings established robust estimators into a consistent Python API so you can
|
|
20
|
+
compare summaries, estimate multivariate structure, and investigate unusual
|
|
21
|
+
observations.
|
|
22
|
+
|
|
23
|
+
- **Summarize a sample:** robust location, scale, skewness and tail-weight measures.
|
|
24
|
+
- **Model multivariate data:** six location and covariance estimators, including
|
|
25
|
+
regularized covariance for data with more variables than observations.
|
|
26
|
+
- **Work with familiar tools:** NumPy-compatible inputs and the scikit-learn
|
|
27
|
+
estimator interface for covariance models.
|
|
28
|
+
- **Inspect the methods:** documented formulas, scientific references, numerical
|
|
29
|
+
conventions and executable examples.
|
|
30
|
+
|
|
31
|
+
## Installation
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
python -m pip install robustmodels
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Requires **Python 3.10+**. NumPy, SciPy and scikit-learn are installed as dependencies.
|
|
38
|
+
CI tests Python 3.10–3.14 on Linux, Windows and macOS.
|
|
39
|
+
|
|
40
|
+
## Start with one sample
|
|
41
|
+
|
|
42
|
+
Compare ordinary and robust summaries of a sample containing one extreme value:
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
import numpy as np
|
|
46
|
+
from robustmodels import location, scale
|
|
47
|
+
|
|
48
|
+
x = [1, 2, 2, 3, 4, 100]
|
|
49
|
+
|
|
50
|
+
print(f"Mean: {np.mean(x):.2f}")
|
|
51
|
+
print(f"Hodges–Lehmann: {location.hodges_lehmann(x):.2f}")
|
|
52
|
+
print(f"Standard dev.: {np.std(x, ddof=1):.2f}")
|
|
53
|
+
print(f"Qn scale: {scale.qn(x):.2f}")
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
```text
|
|
57
|
+
Mean: 18.67
|
|
58
|
+
Hodges–Lehmann: 3.00
|
|
59
|
+
Standard dev.: 39.86
|
|
60
|
+
Qn scale: 1.36
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The robust summaries remain close to the location and spread of the five values
|
|
64
|
+
between 1 and 4. Qn is calibrated to estimate the normal standard deviation and
|
|
65
|
+
includes a finite-sample correction by default.
|
|
66
|
+
|
|
67
|
+
You can also use `location.m_location(x)`, `scale.mad(x)` or
|
|
68
|
+
`scale.medcouple(x)` to estimate a robust center, scale or skewness. The
|
|
69
|
+
[location guide](https://omarbecerrasierra.github.io/robustmodels/location.html)
|
|
70
|
+
and [scale guide](https://omarbecerrasierra.github.io/robustmodels/scale.html)
|
|
71
|
+
explain their tuning and tradeoffs.
|
|
72
|
+
|
|
73
|
+
## Explore multivariate outliers
|
|
74
|
+
|
|
75
|
+
Fit a Minimum Covariance Determinant model and compute squared robust
|
|
76
|
+
Mahalanobis distances. This example adds a shift to ten observations:
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
import numpy as np
|
|
80
|
+
from scipy.stats import chi2
|
|
81
|
+
from robustmodels.covariance import MCD
|
|
82
|
+
|
|
83
|
+
X = np.random.default_rng(0).normal(size=(100, 2))
|
|
84
|
+
X[:10] += 10
|
|
85
|
+
|
|
86
|
+
model = MCD(random_state=0).fit(X)
|
|
87
|
+
distances = model.mahalanobis(X)
|
|
88
|
+
cutoff = chi2.ppf(0.975, df=X.shape[1])
|
|
89
|
+
|
|
90
|
+
print("Robust center:", model.location_.round(2).tolist())
|
|
91
|
+
print("Rows to inspect:", np.flatnonzero(distances > cutoff).tolist())
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
```text
|
|
95
|
+
Robust center: [0.01, 0.1]
|
|
96
|
+
Rows to inspect: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 69]
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
The ten shifted observations are flagged, along with one unshifted observation
|
|
100
|
+
in the tail. Treat these as candidates for investigation. The chi-square cutoff
|
|
101
|
+
is a reference under a multivariate normal model, not an exact finite-sample
|
|
102
|
+
test or a guaranteed false-positive rate.
|
|
103
|
+
|
|
104
|
+
The fitted model exposes `location_`, `covariance_`, `precision_` and `support_`.
|
|
105
|
+
Use `mahalanobis(new_X)` to score new observations; it returns **squared**
|
|
106
|
+
distances. Covariance estimators support `get_params`, `set_params` and
|
|
107
|
+
`sklearn.base.clone`.
|
|
108
|
+
|
|
109
|
+
## Choose an estimator
|
|
110
|
+
|
|
111
|
+
| Your task | A starting point | What to consider |
|
|
112
|
+
| --- | --- | --- |
|
|
113
|
+
| Estimate the center of one sample | `location.hodges_lehmann` | No tuning parameter; based on pairwise averages. |
|
|
114
|
+
| Estimate spread with resistance to outliers | `scale.qn` or `scale.mad` | Qn uses pairwise differences; MAD uses deviations from a center. |
|
|
115
|
+
| Describe asymmetry | `scale.medcouple` | Robust skewness; `lmc` and `rmc` describe the tails. |
|
|
116
|
+
| Estimate covariance when observations outnumber variables | `MCD` | Supports random or deterministic starts. |
|
|
117
|
+
| Estimate covariance when variables outnumber observations | `MRCD` | Regularizes toward an identity target in standardized coordinates. |
|
|
118
|
+
| Explore other multivariate approaches | `OGK`, `MVE`, `SEstimator`, `MMEstimator` | Different robustness, efficiency and computational tradeoffs. |
|
|
119
|
+
|
|
120
|
+
For example, regularized covariance can be fitted to a wide matrix:
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
import numpy as np
|
|
124
|
+
from robustmodels.covariance import MRCD
|
|
125
|
+
|
|
126
|
+
wide = np.random.default_rng(0).normal(size=(20, 50))
|
|
127
|
+
regularized = MRCD().fit(wide)
|
|
128
|
+
print(regularized.covariance_.shape)
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
```text
|
|
132
|
+
(50, 50)
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
See the [covariance guide](https://omarbecerrasierra.github.io/robustmodels/covariance.html)
|
|
136
|
+
for sample-size requirements, parameters and worked examples.
|
|
137
|
+
|
|
138
|
+
## Available methods
|
|
139
|
+
|
|
140
|
+
| Module | Public estimators |
|
|
141
|
+
| --- | --- |
|
|
142
|
+
| `robustmodels.location` | `hodges_lehmann`, `m_location`, `tau_location`, `trimmed_mean`, `winsorized_mean` |
|
|
143
|
+
| `robustmodels.scale` | `mad`, `qn`, `sn`, `pn`, `tau_scale`, `m_scale`, `medcouple`, `lmc`, `rmc` |
|
|
144
|
+
| `robustmodels.covariance` | `MCD`, `MRCD`, `MVE`, `OGK`, `SEstimator`, `MMEstimator` |
|
|
145
|
+
|
|
146
|
+
The covariance module also exposes `h_alpha_n`, `mcd_consistency` and
|
|
147
|
+
`mcd_small_sample`. Each public method has a docstring with parameters,
|
|
148
|
+
return values, examples and references.
|
|
149
|
+
|
|
150
|
+
## Conventions and scope
|
|
151
|
+
|
|
152
|
+
- Univariate estimators take finite, one-dimensional samples. Empty samples
|
|
153
|
+
return `NaN`; a single observation has zero scale. Handle missing and infinite
|
|
154
|
+
values before fitting.
|
|
155
|
+
- Covariance models take matrices with **observations in rows** and variables
|
|
156
|
+
in columns. Set `random_state` for methods that use random starts.
|
|
157
|
+
- Qn, Sn and Pn apply finite-sample corrections by default. Use
|
|
158
|
+
`finite_correction=False` when you need the asymptotic calibration.
|
|
159
|
+
- Robustness depends on the estimator, sample size, dimension and data. No method
|
|
160
|
+
in this package is immune to arbitrary contamination. Multivariate subset
|
|
161
|
+
searches are approximations and do not certify global optima.
|
|
162
|
+
- The package is in **early development**. Its API may change before version 1.0.
|
|
163
|
+
|
|
164
|
+
The [method references](https://omarbecerrasierra.github.io/robustmodels/references.html)
|
|
165
|
+
connect the implementations to their scientific sources and explain differences
|
|
166
|
+
from R conventions. Tests cover statistical properties, edge cases, reference
|
|
167
|
+
comparisons with R's robustbase and rrcov, and scikit-learn compatibility.
|
|
168
|
+
|
|
169
|
+
## Documentation, contributions and citation
|
|
170
|
+
|
|
171
|
+
- **Learn:** the [user guide](https://omarbecerrasierra.github.io/robustmodels/)
|
|
172
|
+
includes the API reference and examples tested alongside the package.
|
|
173
|
+
- **Contribute:** see the [development guide](https://github.com/omarbecerrasierra/robustmodels/blob/main/CONTRIBUTING.md)
|
|
174
|
+
for setup, checks and release instructions. Bug reports and reproducible
|
|
175
|
+
examples are welcome in [Issues](https://github.com/omarbecerrasierra/robustmodels/issues).
|
|
176
|
+
- **Follow changes:** read the [changelog](https://github.com/omarbecerrasierra/robustmodels/blob/main/CHANGELOG.md).
|
|
177
|
+
- **Cite:** use the metadata in [CITATION.cff](https://github.com/omarbecerrasierra/robustmodels/blob/main/CITATION.cff)
|
|
178
|
+
or GitHub's “Cite this repository” option.
|
|
179
|
+
|
|
180
|
+
Released under the [BSD 3-Clause license](https://github.com/omarbecerrasierra/robustmodels/blob/main/LICENSE).
|
|
@@ -14,9 +14,11 @@ Robust estimators of multivariate location and scatter, in
|
|
|
14
14
|
| `SEstimator` | `n > p` | Yes | Smooth weights instead of a hard subset |
|
|
15
15
|
| `MMEstimator` | `n > p` | Yes | S-estimator refined to 95% shape efficiency |
|
|
16
16
|
|
|
17
|
-
Here `n` is the number of observations and `p` the number of variables. MCD,
|
|
18
|
-
|
|
19
|
-
|
|
17
|
+
Here `n` is the number of observations and `p` the number of variables. The exact MCD, MVE, S and MM definitions are affine equivariant under their
|
|
18
|
+
respective assumptions. Numerical searches may behave differently; in
|
|
19
|
+
particular deterministic starts do not guarantee full affine equivariance.
|
|
20
|
+
Maximal breakdown approaches 50% for fixed dimension as sample size grows,
|
|
21
|
+
and can be substantially lower in small samples or high dimensions.
|
|
20
22
|
|
|
21
23
|
## Use
|
|
22
24
|
|
|
@@ -65,7 +67,9 @@ above a high quantile:
|
|
|
65
67
|
```
|
|
66
68
|
|
|
67
69
|
The ten planted outliers are found. Observation 69 is a clean point in the
|
|
68
|
-
tail
|
|
70
|
+
tail. The 2.5% tail probability is a population/asymptotic reference; fitted
|
|
71
|
+
in-sample distances do not provide an exact finite-sample test or an exact
|
|
72
|
+
2.5% false-positive rate.
|
|
69
73
|
|
|
70
74
|
### Reproducibility
|
|
71
75
|
|
|
@@ -107,6 +111,35 @@ The estimators work with `clone`, `get_params`, `set_params` and pipelines:
|
|
|
107
111
|
|
|
108
112
|
```
|
|
109
113
|
|
|
114
|
+
## Numerical limits and sources
|
|
115
|
+
|
|
116
|
+
MCD is solved by an exhaustive sorted-window search in one dimension.
|
|
117
|
+
Multivariate MCD, MRCD, MVE, S and MM use finite searches or iterative
|
|
118
|
+
refinements: they do not certify a global optimum. The MVE implementation
|
|
119
|
+
searches elemental ellipsoids and local refits; it also does not solve a
|
|
120
|
+
minimum-volume enclosing-ellipsoid problem for each selected subset.
|
|
121
|
+
|
|
122
|
+
For exact raw MCD on data in general position, the finite-sample breakdown
|
|
123
|
+
fraction is `min(n-h+1, h-p)/n`; it is not simply 50% for every `n,p`.
|
|
124
|
+
Finite-sample correction factors are empirical approximations.
|
|
125
|
+
|
|
126
|
+
MRCD applies the common-rho rule in Boudt et al., algorithm step 3.4. The
|
|
127
|
+
`max_condition` parameter calibrates **initial** subsets in standardized
|
|
128
|
+
coordinates. Keeping rho fixed during C-steps does not impose a hard bound
|
|
129
|
+
on the final subset's condition number. In original units, unequal column
|
|
130
|
+
scales can further increase the condition number.
|
|
131
|
+
|
|
132
|
+
MM's `efficiency` targets asymptotic **shape** efficiency. Its scale comes from
|
|
133
|
+
the S-estimator; 95% shape efficiency does not imply 95% efficiency for location
|
|
134
|
+
or all covariance entries. The final normalized bisquare loss must not exceed
|
|
135
|
+
the initial loss pointwise (final tuning at least initial tuning). Parameter
|
|
136
|
+
combinations violating this condition raise `ValueError`.
|
|
137
|
+
|
|
138
|
+
Sources: [FAST-MCD](references.md#rvd99), [DetMCD](references.md#hrv12),
|
|
139
|
+
[MCD corrections](references.md#pvaw02), [MRCD](references.md#brvv20),
|
|
140
|
+
[MVE](references.md#var09), [OGK](references.md#mz02),
|
|
141
|
+
[S-estimation](references.md#d87), and [multivariate MM](references.md#sbvaw06).
|
|
142
|
+
|
|
110
143
|
## Reference
|
|
111
144
|
|
|
112
145
|
```{eval-rst}
|
|
@@ -45,6 +45,7 @@ The covariance estimators are scikit-learn estimators:
|
|
|
45
45
|
| --- | --- |
|
|
46
46
|
| [Location](location.md) | Hodges-Lehmann, M-estimators, tau location, trimmed and winsorized means |
|
|
47
47
|
| [Scale and skewness](scale.md) | MAD, Qn, Sn, Pn, tau scale, M-scale, medcouple and tail weights |
|
|
48
|
+
| [Method references](references.md) | Scientific sources, formulas and R conventions |
|
|
48
49
|
| [Covariance](covariance.md) | MCD, MRCD, MVE, OGK, S- and MM-estimators; outlier detection |
|
|
49
50
|
|
|
50
51
|
Each page explains how to choose and use the estimators, then documents every
|
|
@@ -69,5 +70,6 @@ example.
|
|
|
69
70
|
location
|
|
70
71
|
scale
|
|
71
72
|
covariance
|
|
73
|
+
references
|
|
72
74
|
changelog
|
|
73
75
|
```
|
|
@@ -7,13 +7,15 @@ Robust alternatives to the sample mean, in `robustmodels.location`.
|
|
|
7
7
|
| Function | Breakdown point | Gaussian efficiency | Notes |
|
|
8
8
|
| --- | --- | --- | --- |
|
|
9
9
|
| `hodges_lehmann` | 29.3% | 95.5% | No tuning; a good default |
|
|
10
|
-
| `m_location` (Huber) | 50% | 95% | Monotone psi
|
|
10
|
+
| `m_location` (Huber) | 50% | 95% | Monotone psi; flat sets of solutions are possible |
|
|
11
11
|
| `m_location` (bisquare) | 50% | 95% | Rejects gross outliers completely |
|
|
12
12
|
| `tau_location` | 50% | | One weighted mean; no iteration |
|
|
13
13
|
| `trimmed_mean` | `proportion` | | Removes the tails |
|
|
14
14
|
| `winsorized_mean` | `proportion` | | Clips the tails |
|
|
15
15
|
|
|
16
|
-
The
|
|
16
|
+
The percentages are asymptotic under the relevant assumptions. The M-location
|
|
17
|
+
values assume the default robust scale and tuning. The median itself
|
|
18
|
+
(`numpy.median`) has a 50% asymptotic breakdown point and 64% Gaussian efficiency.
|
|
17
19
|
|
|
18
20
|
## Use
|
|
19
21
|
|
|
@@ -54,6 +56,22 @@ estimate with `scale`:
|
|
|
54
56
|
|
|
55
57
|
```
|
|
56
58
|
|
|
59
|
+
## Numerical conventions and sources
|
|
60
|
+
|
|
61
|
+
`m_location` uses a fixed scale and starts from the median. A zero scale returns
|
|
62
|
+
the median. Bisquare can have multiple stationary solutions; a local iteration
|
|
63
|
+
does not certify a global minimum. If the requested iteration limit is reached,
|
|
64
|
+
the last location is returned with a `RuntimeWarning`. Huber's monotone score
|
|
65
|
+
can also have an interval of roots rather than a unique root.
|
|
66
|
+
|
|
67
|
+
The Hodges–Lehmann estimator includes diagonal pairs. Its current sorted-row
|
|
68
|
+
selector uses `O(n log² n)` time and `O(n)` auxiliary storage. It computes the
|
|
69
|
+
specified median in floating-point arithmetic.
|
|
70
|
+
|
|
71
|
+
Sources: [Hodges–Lehmann](references.md#hl63), [Huber](references.md#h64),
|
|
72
|
+
[Beaton–Tukey](references.md#bt74), [Tukey–McLaughlin](references.md#tm63),
|
|
73
|
+
and [Maronna–Zamar](references.md#mz02).
|
|
74
|
+
|
|
57
75
|
## Reference
|
|
58
76
|
|
|
59
77
|
```{eval-rst}
|