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.
Files changed (31) hide show
  1. {robustmodels-0.1.0 → robustmodels-0.1.1}/.gitignore +2 -0
  2. {robustmodels-0.1.0 → robustmodels-0.1.1}/CHANGELOG.md +16 -0
  3. robustmodels-0.1.1/CITATION.cff +18 -0
  4. robustmodels-0.1.1/CONTRIBUTING.md +77 -0
  5. robustmodels-0.1.1/PKG-INFO +211 -0
  6. robustmodels-0.1.1/README.md +180 -0
  7. {robustmodels-0.1.0 → robustmodels-0.1.1}/docs/conf.py +1 -0
  8. {robustmodels-0.1.0 → robustmodels-0.1.1}/docs/covariance.md +37 -4
  9. {robustmodels-0.1.0 → robustmodels-0.1.1}/docs/index.md +2 -0
  10. {robustmodels-0.1.0 → robustmodels-0.1.1}/docs/location.md +20 -2
  11. robustmodels-0.1.1/docs/references.md +227 -0
  12. robustmodels-0.1.1/docs/scale.md +131 -0
  13. {robustmodels-0.1.0 → robustmodels-0.1.1}/pyproject.toml +11 -3
  14. {robustmodels-0.1.0 → robustmodels-0.1.1}/src/robustmodels/__init__.py +1 -1
  15. {robustmodels-0.1.0 → robustmodels-0.1.1}/src/robustmodels/covariance.py +70 -27
  16. {robustmodels-0.1.0 → robustmodels-0.1.1}/src/robustmodels/location.py +18 -2
  17. {robustmodels-0.1.0 → robustmodels-0.1.1}/src/robustmodels/scale.py +32 -12
  18. {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/test_covariance.py +172 -1
  19. {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/test_location.py +5 -0
  20. {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/test_scale.py +35 -0
  21. robustmodels-0.1.0/PKG-INFO +0 -151
  22. robustmodels-0.1.0/README.md +0 -120
  23. robustmodels-0.1.0/docs/scale.md +0 -95
  24. {robustmodels-0.1.0 → robustmodels-0.1.1}/LICENSE +0 -0
  25. {robustmodels-0.1.0 → robustmodels-0.1.1}/docs/changelog.md +0 -0
  26. {robustmodels-0.1.0 → robustmodels-0.1.1}/src/robustmodels/_validation.py +0 -0
  27. {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/conftest.py +0 -0
  28. {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/data/r_reference.json +0 -0
  29. {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/reference.py +0 -0
  30. {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/test_r_parity.py +0 -0
  31. {robustmodels-0.1.0 → robustmodels-0.1.1}/tests/test_selection.py +0 -0
@@ -11,5 +11,7 @@ dist/
11
11
  .pytest_cache/
12
12
  .ruff_cache/
13
13
  .coverage
14
+ coverage.xml
14
15
  htmlcov/
15
16
  docs/_build/
17
+ .claude
@@ -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
+ [![PyPI version](https://img.shields.io/pypi/v/robustmodels)](https://pypi.org/project/robustmodels/)
37
+ [![Python versions](https://img.shields.io/pypi/pyversions/robustmodels)](https://pypi.org/project/robustmodels/)
38
+ [![CI](https://github.com/omarbecerrasierra/robustmodels/actions/workflows/ci.yml/badge.svg)](https://github.com/omarbecerrasierra/robustmodels/actions/workflows/ci.yml)
39
+ [![Coverage](https://codecov.io/gh/omarbecerrasierra/robustmodels/graph/badge.svg)](https://codecov.io/gh/omarbecerrasierra/robustmodels)
40
+ [![Downloads](https://img.shields.io/pypi/dm/robustmodels)](https://pypistats.org/packages/robustmodels)
41
+ [![License: BSD 3-Clause](https://img.shields.io/badge/license-BSD%203--Clause-blue)](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
+ [![PyPI version](https://img.shields.io/pypi/v/robustmodels)](https://pypi.org/project/robustmodels/)
6
+ [![Python versions](https://img.shields.io/pypi/pyversions/robustmodels)](https://pypi.org/project/robustmodels/)
7
+ [![CI](https://github.com/omarbecerrasierra/robustmodels/actions/workflows/ci.yml/badge.svg)](https://github.com/omarbecerrasierra/robustmodels/actions/workflows/ci.yml)
8
+ [![Coverage](https://codecov.io/gh/omarbecerrasierra/robustmodels/graph/badge.svg)](https://codecov.io/gh/omarbecerrasierra/robustmodels)
9
+ [![Downloads](https://img.shields.io/pypi/dm/robustmodels)](https://pypistats.org/packages/robustmodels)
10
+ [![License: BSD 3-Clause](https://img.shields.io/badge/license-BSD%203--Clause-blue)](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,6 +14,7 @@ extensions = [
14
14
  "sphinx.ext.viewcode",
15
15
  ]
16
16
  exclude_patterns = ["_build"]
17
+ myst_heading_anchors = 3
17
18
 
18
19
  autodoc_member_order = "bysource"
19
20
  add_module_names = False
@@ -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
- MVE, S and MM are affine equivariant and reach a 50% breakdown point with their
19
- default settings.
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: with a 0.975 quantile, about 2.5% of the clean data are expected there.
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, unique solution |
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 median itself (`numpy.median`) has a 50% breakdown point and 64% efficiency.
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}