matrix-hat 0.1.0__tar.gz

matrix_hat-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with test extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[test]"
+
+      - name: Run tests and doctests
+        run: pytest
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install package with docs extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Build documentation
+        run: sphinx-build -W -b html docs docs/_build/html

matrix_hat-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,69 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        required: true
+        type: choice
+        options:
+          - testpypi
+          - pypi
+        default: testpypi
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish-testpypi:
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install build
+        run: python -m pip install --upgrade pip build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: >-
+      github.event_name == 'release' ||
+      (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install build
+        run: python -m pip install --upgrade pip build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

matrix_hat-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Documentation
+docs/_build/
+docs/reference/generated/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Editor / OS
+.vscode/
+.idea/
+.cursor/
+.DS_Store

matrix_hat-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-19
+
+### Added
+
+- Public API: `leverage`, `hat_matrix`, `high_leverage_points`, `orthonormal_basis`, `effective_rank`.
+- SVD-based, rank-revealing hat-matrix computations with optional intercept.
+- NumPy-style documentation (Sphinx + numpydoc) and typed public API (`py.typed`).
+- Example workflow under `examples/titanic_outliers/`.
+
+[0.1.0]: https://github.com/aokienz/matrix-hat/releases/tag/v0.1.0

matrix_hat-0.1.0/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "matrix-hat: hat matrix and leverage diagnostics for linear regression"
+version: 0.1.0
+date-released: "2026-07-19"
+license: MIT
+repository-code: "https://github.com/aokienz/matrix-hat"
+url: "https://github.com/aokienz/matrix-hat"
+authors:
+  - family-names: Aoki
+    given-names: Enzo
+    email: enzoaoki02@gmail.com
+abstract: >-
+  Small NumPy-only toolkit for the hat matrix and leverage diagnostics used
+  in linear regression, based on a rank-revealing SVD.
+keywords:
+  - statistics
+  - regression
+  - hat-matrix
+  - leverage
+  - diagnostics

matrix_hat-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+Thanks for contributing to **matrix-hat**.
+
+## Development setup
+
+```bash
+git clone https://github.com/aokienz/matrix-hat.git
+cd matrix-hat
+python -m venv .venv
+# Windows: .venv\Scripts\activate
+# Unix:    source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Tests and doctests
+
+```bash
+pytest
+pytest --doctest-modules src/matrix_hat
+```
+
+Both are run in CI. Prefer stable doctest examples (e.g. `.round(2)`).
+
+## Documentation
+
+Build the Sphinx site with warnings treated as errors:
+
+```bash
+sphinx-build -W -b html docs docs/_build/html
+```
+
+On Windows you can also run `docs\make.bat html`. Docstrings use **numpydoc**
+(`Parameters`, `Returns`, `Raises`, `See Also`, `Notes`, `References`, `Examples`).
+
+## Pull requests
+
+1. Keep the public API small and NumPy-only unless discussed first.
+2. Add or update tests for behaviour changes.
+3. Update `CHANGELOG.md` under an `[Unreleased]` section when appropriate.
+4. Keep `version` in `pyproject.toml` and `__version__` in
+   `src/matrix_hat/__init__.py` in sync when releasing.
+
+## Code style
+
+Match the existing style: type hints on public functions (`ArrayLike`,
+`NDArray`), private helpers in `_validation.py`, and English docs/comments.

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

matrix_hat-0.1.0/PKG-INFO

@@ -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/PUBLISHING.md

@@ -0,0 +1,127 @@
+# Publishing matrix-hat
+
+Checklist for releasing `matrix-hat` to TestPyPI and PyPI via **Trusted Publishing** (GitHub Actions + OIDC). No API tokens in the repository.
+
+**GitHub:** https://github.com/aokienz/matrix-hat  
+**PyPI name:** `matrix-hat`  
+**Import name:** `matrix_hat`
+
+---
+
+## One-time setup
+
+### 1. Accounts
+
+- [ ] Account on [pypi.org](https://pypi.org) with **2FA** enabled
+- [ ] Account on [test.pypi.org](https://test.pypi.org) with **2FA** enabled (separate from PyPI)
+- [ ] Public GitHub repo `aokienz/matrix-hat` with this code on `main`
+
+### 2. GitHub Environments
+
+In the repo: **Settings → Environments**
+
+- [ ] Create environment `testpypi`
+- [ ] Create environment `pypi`  
+  Optional: add protection rules (required reviewers, restrict to tags `v*`).
+
+### 3. Trusted Publishers
+
+**TestPyPI** → Account settings → Publishing → Add a new pending publisher:
+
+| Field | Value |
+|-------|--------|
+| PyPI Project Name | `matrix-hat` |
+| Owner | `aokienz` |
+| Repository name | `matrix-hat` |
+| Workflow name | `publish.yml` |
+| Environment name | `testpypi` |
+
+**PyPI** → same form with:
+
+| Field | Value |
+|-------|--------|
+| PyPI Project Name | `matrix-hat` |
+| Owner | `aokienz` |
+| Repository name | `matrix-hat` |
+| Workflow name | `publish.yml` |
+| Environment name | `pypi` |
+
+---
+
+## Local checks (before every release)
+
+```bash
+pip install -e ".[test]"
+pytest
+pip install build twine
+Remove-Item -Recurse -Force dist -ErrorAction SilentlyContinue   # PowerShell
+python -m build
+twine check dist/*
+```
+
+Bump version in **both** `pyproject.toml` (`version`) and `src/matrix_hat/__init__.py` (`__version__`). Keep them identical.
+
+Versions on PyPI are **immutable**. If `0.1.0` is wrong, ship `0.1.1`.
+
+---
+
+## Publish to TestPyPI (dry run)
+
+1. Push `main` with the workflows committed.
+2. Confirm pending publisher on TestPyPI (step 3 above).
+3. GitHub → **Actions** → **Publish** → **Run workflow** → target `testpypi`.
+4. When green, install in a clean environment:
+
+```bash
+pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ matrix-hat==0.1.0
+python -c "import matrix_hat; print(matrix_hat.__version__)"
+```
+
+(`--extra-index-url` pulls NumPy from real PyPI.)
+
+---
+
+## Publish to PyPI
+
+1. Confirm pending publisher on PyPI.
+2. Preferred: create a **GitHub Release** with tag `v0.1.0` (this triggers the `publish-pypi` job).
+3. Alternative: Actions → **Publish** → Run workflow → target `pypi`.
+4. Verify:
+
+```bash
+pip install matrix-hat
+python -c "from matrix_hat import leverage; print('ok')"
+```
+
+Project page: https://pypi.org/project/matrix-hat/
+
+---
+
+## Workflow map
+
+| Trigger | Job | Index |
+|---------|-----|--------|
+| `workflow_dispatch` → `testpypi` | `publish-testpypi` | TestPyPI |
+| `workflow_dispatch` → `pypi` | `publish-pypi` | PyPI |
+| GitHub Release published | `publish-pypi` | PyPI |
+
+CI (`ci.yml`) runs `pytest` on Python 3.9–3.13 for pushes/PRs to `main`/`master`.
+
+---
+
+## First push (if git is not set up yet)
+
+```bash
+git init
+git add .
+git commit -m "Initial release prep for matrix-hat 0.1.0"
+git branch -M main
+gh repo create matrix-hat --public --source=. --remote=origin --push
+```
+
+Or create the empty repo on GitHub first, then:
+
+```bash
+git remote add origin https://github.com/aokienz/matrix-hat.git
+git push -u origin main
+```

matrix_hat-0.1.0/README.md

@@ -0,0 +1,100 @@
+# 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/docs/Makefile

@@ -0,0 +1,14 @@
+# Minimal Makefile for Sphinx documentation
+
+SPHINXOPTS    ?= -W
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)

matrix_hat-0.1.0/docs/conf.py

@@ -0,0 +1,49 @@
+"""Sphinx configuration for matrix-hat documentation."""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+project = "matrix-hat"
+author = "Enzo Aoki"
+copyright = f"{datetime.now(timezone.utc).year}, {author}"
+release = "0.1.0"
+version = "0.1"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "numpydoc",
+]
+
+autosummary_generate = True
+autodoc_typehints = "none"
+numpydoc_show_class_members = False
+numpydoc_xref_param_type = True
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "pydata_sphinx_theme"
+html_static_path = ["_static"]
+html_title = "matrix-hat"
+html_theme_options = {
+    "github_url": "https://github.com/aokienz/matrix-hat",
+    "show_toc_level": 2,
+    "navigation_with_keys": False,
+}
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
+
+default_role = "py:obj"