matrix-hat 0.1.0

Hat matrix and leverage diagnostics for linear regression.

matrix-hat

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/. 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

pip install matrix-hat

From source (tests + docs):

pip install -e ".[dev]"

Quickstart

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

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

See CONTRIBUTING.md for details.

Citation

If you use this package in research, see CITATION.cff.

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.