matrix-hat 0.1.0__py3-none-any.whl

matrix_hat/__init__.py

@@ -0,0 +1,29 @@
+"""matrix-hat: hat matrix and leverage diagnostics for linear regression.
+
+Quick start
+-----------
+>>> import numpy as np
+>>> from matrix_hat import leverage, hat_matrix
+>>> X = np.array([[1.0], [2.0], [3.0], [10.0]])
+>>> leverage(X, add_intercept=True).round(2)
+array([0.43, 0.33, 0.27, 0.97])
+"""
+
+from .core import (
+    effective_rank,
+    hat_matrix,
+    high_leverage_points,
+    leverage,
+    orthonormal_basis,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "hat_matrix",
+    "leverage",
+    "high_leverage_points",
+    "orthonormal_basis",
+    "effective_rank",
+    "__version__",
+]

matrix_hat/_validation.py

@@ -0,0 +1,34 @@
+"""Private input validation and design-matrix helpers."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+
+def _as_2d(X: ArrayLike) -> NDArray[np.floating]:
+    """Return ``X`` as a 2-D float array, promoting 1-D input to a column."""
+    arr = np.asarray(X, dtype=float)
+    if arr.ndim == 1:
+        arr = arr.reshape(-1, 1)
+    if arr.ndim != 2:
+        raise ValueError(f"X must be 1- or 2-dimensional, got {arr.ndim} dimensions")
+    if arr.size == 0:
+        raise ValueError("X must not be empty")
+    return arr
+
+
+def _design(X: ArrayLike, add_intercept: bool) -> NDArray[np.floating]:
+    """Build the design matrix, optionally prepending an intercept column."""
+    arr = _as_2d(X)
+    if add_intercept:
+        intercept = np.ones((arr.shape[0], 1), dtype=float)
+        arr = np.hstack([intercept, arr])
+    return arr
+
+
+def _default_tol(s: NDArray[np.floating], shape: tuple[int, int]) -> float:
+    """Default singular-value tolerance, matching ``numpy.linalg.matrix_rank``."""
+    if s.size == 0:
+        return 0.0
+    return float(s.max()) * max(shape) * np.finfo(float).eps

matrix_hat/core.py

@@ -0,0 +1,354 @@
+"""Core hat matrix and leverage computations.
+
+The *hat matrix* of a design matrix ``X`` is the orthogonal projection onto
+the column space of ``X``:
+
+.. math::
+
+    H = X (X^{\\top} X)^{-1} X^{\\top}
+
+It is called the *hat* matrix because it maps the observed response ``y`` onto
+its fitted values (``y-hat``): :math:`\\hat{y} = H y`. The diagonal entries
+:math:`h_{ii}` are the *leverages*, a standard regression diagnostic measuring
+how far the ``i``-th observation lies from the centre of the predictor space.
+
+Computations here are based on a rank-revealing SVD rather than an explicit
+matrix inverse, which is numerically stable and gracefully handles
+rank-deficient design matrices.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from ._validation import _default_tol, _design
+
+__all__ = [
+    "orthonormal_basis",
+    "hat_matrix",
+    "leverage",
+    "high_leverage_points",
+    "effective_rank",
+]
+
+
+def orthonormal_basis(
+    X: ArrayLike,
+    add_intercept: bool = False,
+    tol: float | None = None,
+) -> NDArray[np.floating]:
+    """Return an orthonormal basis ``Q`` for the column space of ``X``.
+
+    The basis is obtained from the SVD and spans the same subspace as the
+    (possibly rank-deficient) columns of the design matrix. The hat matrix
+    satisfies :math:`H = Q Q^{\\top}`.
+
+    Parameters
+    ----------
+    X : array_like
+        Design matrix of shape ``(n_samples, n_features)``. A 1-D array is
+        treated as a single column.
+    add_intercept : bool, default False
+        If True, prepend a column of ones to ``X``.
+    tol : float, optional
+        Singular values below ``tol`` are treated as zero when determining the
+        rank. Defaults to a value scaled by the largest singular value and the
+        matrix size (same rule as :func:`numpy.linalg.matrix_rank`).
+
+    Returns
+    -------
+    ndarray
+        Array of shape ``(n_samples, rank)`` with orthonormal columns.
+
+    Raises
+    ------
+    ValueError
+        If ``X`` is empty or has more than two dimensions.
+
+    See Also
+    --------
+    hat_matrix : Full projection matrix ``H = Q @ Q.T``.
+    leverage : Diagonal of ``H`` without forming the full matrix.
+    effective_rank : Numerical rank equal to ``Q.shape[1]``.
+
+    Notes
+    -----
+    Using a truncated SVD avoids forming :math:`(X^{\\top} X)^{-1}` and remains
+    well-behaved for ill-conditioned or rank-deficient designs.
+
+    References
+    ----------
+    .. [1] Hoaglin, D. C. and Welsch, R. E. (1978). "The Hat Matrix in
+       Regression and ANOVA". *The American Statistician*, 32(1), 17--22.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from matrix_hat import orthonormal_basis
+    >>> X = np.array([[1.0], [2.0], [3.0]])
+    >>> Q = orthonormal_basis(X, add_intercept=True)
+    >>> Q.shape
+    (3, 2)
+    >>> np.allclose(Q.T @ Q, np.eye(Q.shape[1]))
+    True
+    """
+    design = _design(X, add_intercept)
+    U, s, _ = np.linalg.svd(design, full_matrices=False)
+    if tol is None:
+        tol = _default_tol(s, design.shape)
+    rank = int(np.sum(s > tol))
+    return U[:, :rank]
+
+
+def effective_rank(
+    X: ArrayLike,
+    add_intercept: bool = False,
+    tol: float | None = None,
+) -> int:
+    """Return the numerical rank of the (optionally augmented) design matrix.
+
+    Equivalent to the number of columns of :func:`orthonormal_basis`, i.e. the
+    number of singular values strictly larger than ``tol``.
+
+    Parameters
+    ----------
+    X : array_like
+        Design matrix of shape ``(n_samples, n_features)``. A 1-D array is
+        treated as a single column.
+    add_intercept : bool, default False
+        If True, prepend a column of ones to ``X`` before ranking.
+    tol : float, optional
+        Singular-value cut-off passed to :func:`orthonormal_basis`.
+
+    Returns
+    -------
+    int
+        Numerical rank of the design matrix.
+
+    Raises
+    ------
+    ValueError
+        If ``X`` is empty or has more than two dimensions.
+
+    See Also
+    --------
+    orthonormal_basis : Orthonormal basis whose width equals the rank.
+    leverage : Leverages sum to this rank.
+
+    Notes
+    -----
+    For a full-rank design with an intercept, the rank is
+    ``n_features + 1``.
+
+    References
+    ----------
+    .. [1] Hoaglin, D. C. and Welsch, R. E. (1978). "The Hat Matrix in
+       Regression and ANOVA". *The American Statistician*, 32(1), 17--22.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from matrix_hat import effective_rank
+    >>> X = np.array([[1.0, 2.0], [2.0, 4.0], [3.0, 6.0]])  # rank 1
+    >>> effective_rank(X)
+    1
+    >>> effective_rank(X, add_intercept=True)
+    2
+    """
+    return orthonormal_basis(X, add_intercept=add_intercept, tol=tol).shape[1]
+
+
+def hat_matrix(
+    X: ArrayLike,
+    add_intercept: bool = False,
+    tol: float | None = None,
+) -> NDArray[np.floating]:
+    """Compute the full hat (projection) matrix ``H``.
+
+    Parameters
+    ----------
+    X : array_like
+        Design matrix of shape ``(n_samples, n_features)``. A 1-D array is
+        treated as a single column.
+    add_intercept : bool, default False
+        If True, prepend a column of ones before projecting.
+    tol : float, optional
+        Rank tolerance passed to :func:`orthonormal_basis`.
+
+    Returns
+    -------
+    ndarray
+        Symmetric idempotent matrix of shape ``(n_samples, n_samples)``.
+
+    Raises
+    ------
+    ValueError
+        If ``X`` is empty or has more than two dimensions.
+
+    See Also
+    --------
+    leverage : Prefer this for large ``n``; returns only the diagonal.
+    orthonormal_basis : Factors ``H`` as ``Q @ Q.T``.
+    high_leverage_points : Indices with large diagonal entries.
+
+    Notes
+    -----
+    The full hat matrix is ``n_samples`` by ``n_samples``. For large samples
+    prefer :func:`leverage`, which returns only the diagonal without forming
+    the full matrix. Algebraically,
+    :math:`H` is the orthogonal projector onto the column space of ``X``, so
+    :math:`H = H^{\\top} = H^{2}`.
+
+    References
+    ----------
+    .. [1] Hoaglin, D. C. and Welsch, R. E. (1978). "The Hat Matrix in
+       Regression and ANOVA". *The American Statistician*, 32(1), 17--22.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from matrix_hat import hat_matrix
+    >>> X = np.array([[1.0], [2.0], [3.0]])
+    >>> H = hat_matrix(X, add_intercept=True)
+    >>> H.shape
+    (3, 3)
+    >>> np.allclose(H, H.T) and np.allclose(H @ H, H)
+    True
+    """
+    Q = orthonormal_basis(X, add_intercept=add_intercept, tol=tol)
+    return Q @ Q.T
+
+
+def leverage(
+    X: ArrayLike,
+    add_intercept: bool = False,
+    tol: float | None = None,
+) -> NDArray[np.floating]:
+    """Compute the leverages ``h_ii`` (diagonal of the hat matrix).
+
+    Computed as the row-wise sum of squares of an orthonormal basis for the
+    column space, avoiding formation of the full ``n_samples`` square hat
+    matrix.
+
+    Parameters
+    ----------
+    X : array_like
+        Design matrix of shape ``(n_samples, n_features)``. A 1-D array is
+        treated as a single column.
+    add_intercept : bool, default False
+        If True, prepend a column of ones before projecting.
+    tol : float, optional
+        Rank tolerance passed to :func:`orthonormal_basis`.
+
+    Returns
+    -------
+    ndarray
+        Vector of length ``n_samples`` with values in ``[0, 1]`` that sum to
+        the rank of the design matrix.
+
+    Raises
+    ------
+    ValueError
+        If ``X`` is empty or has more than two dimensions.
+
+    See Also
+    --------
+    hat_matrix : Full projection matrix whose diagonal is returned here.
+    high_leverage_points : Flag observations above a leverage cut-off.
+    effective_rank : Equal to ``leverage(...).sum()`` (within rounding).
+
+    Notes
+    -----
+    Leverages satisfy :math:`0 \\le h_{ii} \\le 1` and
+    :math:`\\sum_i h_{ii} = \\mathrm{rank}(X)`. Their average is therefore
+    :math:`p / n`. Memory use is ``O(n p)`` rather than ``O(n^2)``.
+
+    References
+    ----------
+    .. [1] Hoaglin, D. C. and Welsch, R. E. (1978). "The Hat Matrix in
+       Regression and ANOVA". *The American Statistician*, 32(1), 17--22.
+    .. [2] Belsley, D. A., Kuh, E. and Welsch, R. E. (1980). *Regression
+       Diagnostics*. Wiley.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from matrix_hat import leverage
+    >>> X = np.array([[1.0], [2.0], [3.0], [10.0]])
+    >>> leverage(X, add_intercept=True).round(2)
+    array([0.43, 0.33, 0.27, 0.97])
+    """
+    Q = orthonormal_basis(X, add_intercept=add_intercept, tol=tol)
+    return np.einsum("ij,ij->i", Q, Q)
+
+
+def high_leverage_points(
+    X: ArrayLike,
+    add_intercept: bool = False,
+    threshold: float | None = None,
+    factor: float = 2.0,
+    tol: float | None = None,
+) -> NDArray[np.integer]:
+    """Return indices of observations whose leverage exceeds a threshold.
+
+    Parameters
+    ----------
+    X : array_like
+        Design matrix of shape ``(n_samples, n_features)``. A 1-D array is
+        treated as a single column.
+    add_intercept : bool, default False
+        If True, prepend a column of ones before projecting.
+    threshold : float, optional
+        Absolute leverage cut-off. If omitted, a rule-of-thumb threshold of
+        ``factor * p / n`` is used, where ``p`` is the rank (mean leverage is
+        ``p / n``) and ``n`` is the number of observations.
+    factor : float, default 2.0
+        Multiplier for the automatic ``factor * p / n`` threshold. Common
+        choices are 2 or 3. Ignored when ``threshold`` is given.
+    tol : float, optional
+        Rank tolerance passed to :func:`orthonormal_basis`.
+
+    Returns
+    -------
+    ndarray
+        Integer indices of the flagged observations, in ascending order.
+
+    Raises
+    ------
+    ValueError
+        If ``X`` is empty or has more than two dimensions.
+
+    See Also
+    --------
+    leverage : Leverage values compared against the threshold.
+    hat_matrix : Full projection matrix (prefer :func:`leverage` for large ``n``).
+
+    Notes
+    -----
+    A common rule of thumb flags observations with
+    :math:`h_{ii} > 2p/n` (or :math:`3p/n`) as high leverage [2]_. High
+    leverage indicates unusual predictor values, not necessarily an outlier in
+    the response.
+
+    References
+    ----------
+    .. [1] Hoaglin, D. C. and Welsch, R. E. (1978). "The Hat Matrix in
+       Regression and ANOVA". *The American Statistician*, 32(1), 17--22.
+    .. [2] Belsley, D. A., Kuh, E. and Welsch, R. E. (1980). *Regression
+       Diagnostics*. Wiley.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from matrix_hat import high_leverage_points
+    >>> X = np.array([[1.0], [2.0], [3.0], [4.0], [50.0]])
+    >>> high_leverage_points(X, add_intercept=True)
+    array([4])
+    """
+    h = leverage(X, add_intercept=add_intercept, tol=tol)
+    if threshold is None:
+        n = h.shape[0]
+        p = float(np.sum(h))  # rank == trace of the hat matrix
+        threshold = factor * p / n
+    return np.flatnonzero(h > threshold)

matrix_hat-0.1.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+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).

matrix_hat-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+matrix_hat/__init__.py,sha256=U47RPmJ1B9fs65p_1DL6pCq1hrBVzYdnR2iRFnUZ-2Y,587
+matrix_hat/_validation.py,sha256=geA4U5oI0-9d4wLVzw64adWx0IC4Dj_TskxdPc0EERA,1145
+matrix_hat/core.py,sha256=X_6b1AUOX7CuU5AXvEMdwebawVLnWX7Eh8GKAKCg-0E,11038
+matrix_hat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+matrix_hat-0.1.0.dist-info/METADATA,sha256=we31r6XpmNNebQkmKqFuKWDG75wIEK-rPfhnyGVry8Q,4795
+matrix_hat-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+matrix_hat-0.1.0.dist-info/licenses/LICENSE,sha256=yxcYk9fBYppe_dZZt15gsLiMTKRJiUbx0kSKoL3yoQw,1061
+matrix_hat-0.1.0.dist-info/RECORD,,

matrix_hat-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

matrix_hat-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enzo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.