Metadata-Version: 2.4
Name: matrix-hat
Version: 0.1.0
Summary: Hat matrix and leverage diagnostics for linear regression.
Project-URL: Homepage, https://github.com/aokienz/matrix-hat
Project-URL: Repository, https://github.com/aokienz/matrix-hat
Project-URL: Issues, https://github.com/aokienz/matrix-hat/issues
Author-email: Enzo Aoki <enzoaoki02@gmail.com>
License: MIT
License-File: LICENSE
Keywords: diagnostics,hat-matrix,influence,leverage,outliers,regression,statistics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Requires-Dist: numpy>=1.21
Provides-Extra: dev
Requires-Dist: numpydoc>=1.6; extra == 'dev'
Requires-Dist: pydata-sphinx-theme>=0.15; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: sphinx>=7.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: numpydoc>=1.6; extra == 'docs'
Requires-Dist: pydata-sphinx-theme>=0.15; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# matrix-hat

[![CI](https://github.com/aokienz/matrix-hat/actions/workflows/ci.yml/badge.svg)](https://github.com/aokienz/matrix-hat/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/matrix-hat.svg)](https://pypi.org/project/matrix-hat/)
[![Python](https://img.shields.io/pypi/pyversions/matrix-hat.svg)](https://pypi.org/project/matrix-hat/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Small, dependency-light toolkit for the **hat matrix** and **leverage**
diagnostics used in linear regression.

The hat matrix of a design matrix `X` is the orthogonal projection onto its
column space:

$$H = X (X^\top X)^{-1} X^\top$$

It earns its name because it turns observed responses into fitted values
("y-hat"): $\hat{y} = Hy$. Its diagonal entries $h_{ii}$ are the **leverages**,
which measure how far each observation sits from the centre of the predictor
space — a key tool for spotting influential points and outliers.

**Full documentation** (user guide, math background, API reference) lives in
[`docs/`](docs/). Build locally with `pip install -e ".[docs]"` then
`sphinx-build -W -b html docs docs/_build/html`.

## Why this package

- **Numerically stable.** Rank-revealing SVD instead of an explicit
  `(XᵀX)⁻¹`, so it stays well-behaved on ill-conditioned or rank-deficient
  designs.
- **Memory-aware.** `leverage()` returns just the diagonal without ever forming
  the full `n × n` hat matrix.
- **Tiny footprint.** NumPy is the only runtime dependency.

## Installation

```bash
pip install matrix-hat
```

From source (tests + docs):

```bash
pip install -e ".[dev]"
```

## Quickstart

```python
import numpy as np
from matrix_hat import leverage, hat_matrix, high_leverage_points

X = np.array([[1.0], [2.0], [3.0], [4.0], [50.0]])

# Leverages (diagonal of the hat matrix), with an intercept column added.
h = leverage(X, add_intercept=True)
# array([0.267, 0.255, 0.245, 0.235, 0.998]) approx.

# Flag high-leverage observations (default rule of thumb: 2 * p / n).
high_leverage_points(X, add_intercept=True)
# array([4])

# The full projection matrix, when you actually need it.
H = hat_matrix(X, add_intercept=True)
```

## API

| Function | Description |
| --- | --- |
| `leverage(X, add_intercept=False)` | Leverages `h_ii` (diagonal of `H`) as a length-`n` vector. |
| `hat_matrix(X, add_intercept=False)` | The full `n × n` projection matrix `H`. |
| `high_leverage_points(X, threshold=None, factor=2.0)` | Indices of observations above a leverage cut-off. |
| `orthonormal_basis(X, add_intercept=False)` | Orthonormal basis `Q` for the column space (`H = Q Qᵀ`). |
| `effective_rank(X, add_intercept=False)` | Numerical rank of the design matrix. |

All functions accept a `tol` argument to control the singular-value cut-off
used for rank determination. See the Sphinx docs for full numpydoc reference
pages.

## Development

```bash
pip install -e ".[dev]"
pytest
sphinx-build -W -b html docs docs/_build/html
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## Citation

If you use this package in research, see [CITATION.cff](CITATION.cff).

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## License

MIT — see [LICENSE](LICENSE).
