subspaceknn 0.1.0__tar.gz

subspaceknn-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

subspaceknn-0.1.0/.gitattributes

@@ -0,0 +1,7 @@
+# Normalise line endings so ruff format and CI agree across Windows, macOS and Linux.
+* text=auto eol=lf
+*.py text eol=lf
+*.md text eol=lf
+*.toml text eol=lf
+*.yml text eol=lf
+*.png binary

subspaceknn-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.python-version.local
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Editors and operating systems
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db
+
+# Example outputs
+examples/output/

subspaceknn-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+# Optional local hooks; CI runs the same tools. Install with `uvx pre-commit install`.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.8
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-toml
+      - id: check-yaml

subspaceknn-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

subspaceknn-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project are 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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-18
+
+### Added
+
+- `SubspaceKNNClassifier`: a scikit-learn compatible classifier that fits k-nearest-neighbour models on every small feature subspace, ranks them by cross-validated score, and combines the best by weighted soft or hard voting. Subspaces can have any size or a mix of sizes; wide data is handled by screening features to keep the candidate count within `max_candidates`.
+- `explain`, returning an `Explanation` per sample with one `SubspaceVote` per subspace, and `feature_scores_` as a coarse relevance measure.
+- `subspaceknn.plotting.plot_subspaces`, drawing one-, two- and three-dimensional subspaces with decision regions where possible (optional `plot` extra).
+- Test suite covering scikit-learn's estimator contract for two configurations, behaviour, explanations, plotting, and an accuracy comparison against plain kNN on the iris, wine and breast-cancer datasets.
+- Project infrastructure: uv-based workflow, ruff and mypy in strict mode, CI across Python 3.10 to 3.13 and three operating systems, tag-driven PyPI release with trusted publishing, Dependabot, issue and pull request templates, contributing guide, security policy and code of conduct.
+
+[Unreleased]: https://github.com/DiogoRibeiro7/subspaceknn/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/DiogoRibeiro7/subspaceknn/releases/tag/v0.1.0

subspaceknn-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer, Diogo Ribeiro, through the contact details
+on the GitHub profile [@DiogoRibeiro7](https://github.com/DiogoRibeiro7).
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

subspaceknn-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to subspaceknn
+
+Thank you for considering a contribution. The project has one goal: an interpretable nearest-neighbour classifier that behaves exactly like a scikit-learn estimator and explains every prediction it makes. The guidelines below keep that intact as the code grows.
+
+## Ground rules
+
+- Be respectful. The project follows the [Code of Conduct](CODE_OF_CONDUCT.md).
+- Open an issue before large work so the design can be agreed first. Small fixes can go straight to a pull request.
+- Every behavioural claim in the code or the documentation must be backed by a test.
+
+## Development setup
+
+You need Python 3.10 or newer and [uv](https://docs.astral.sh/uv/). There are no other build dependencies.
+
+```sh
+git clone https://github.com/DiogoRibeiro7/subspaceknn.git
+cd subspaceknn
+uv sync --all-extras
+```
+
+Optional local hooks that run the same checks as CI: `uvx pre-commit install`.
+
+## Before you open a pull request
+
+Run the same checks CI runs. All of them must pass:
+
+```sh
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+uv run python examples/iris_explanations.py
+uv build && uvx twine check dist/*
+```
+
+Ruff runs with every rule enabled except the few listed in `pyproject.toml`, and mypy runs in strict mode on the package. Prefer fixing a finding over silencing it; when silencing is the right call, scope the `noqa` or `type: ignore` to the line and say why.
+
+## Coding standards
+
+- **scikit-learn contract first.** `__init__` only stores parameters, validation happens in `fit`, fitted state lives in attributes with a trailing underscore, `predict` has no side effects, `predict_proba` and `predict` agree, and invalid input raises an informative `ValueError`. `tests/test_sklearn_compat.py` runs `check_estimator`; a change that breaks it is a bug.
+- **Deterministic by construction.** Subspace enumeration, ranking and tie-breaking are documented in `docs/method.md`; keep them that way and update the note if they change.
+- **Explanations are data.** Anything a user needs to understand a prediction belongs in `Explanation` and `SubspaceVote`, not in printed output or plot side effects.
+- **Optional dependencies stay optional.** matplotlib is imported lazily; the core package depends only on numpy and scikit-learn.
+- **Typed and documented.** Public functions have numpy-style docstrings and complete type annotations.
+
+## Testing standards
+
+- Unit tests for behaviour and validation live in `tests/`; the scikit-learn contract runs against every configuration that changes a code path.
+- Numbers that appear in the documentation come from `tests/test_benchmark.py`. If you change the method, rerun it and update `docs/benchmark.md` and the README table together.
+- Keep tests deterministic: fixed seeds, fixed splitters, no network.
+
+## Documentation
+
+- Public API changes need a docstring update and, when user-visible, an entry under *Unreleased* in `CHANGELOG.md`.
+- Design changes need a corresponding change in `docs/method.md`.
+
+## Branches, commits and pull requests
+
+- Branch from `main` using a short prefix: `feat/`, `fix/`, `test/`, `docs/`, `chore/`.
+- Write commit subjects in the imperative mood, at most 72 characters.
+- Keep pull requests focused and fill in the template, including how the change was validated.
+
+## Licensing of contributions
+
+By submitting a contribution you agree that it is licensed under the project's MIT license, without any additional terms or conditions.

subspaceknn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diogo Ribeiro
+
+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.

subspaceknn-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: subspaceknn
+Version: 0.1.0
+Summary: Interpretable k-nearest-neighbour classification by ensembling kNN models fitted on low-dimensional feature subspaces.
+Project-URL: Homepage, https://github.com/DiogoRibeiro7/subspaceknn
+Project-URL: Repository, https://github.com/DiogoRibeiro7/subspaceknn
+Project-URL: Issues, https://github.com/DiogoRibeiro7/subspaceknn/issues
+Project-URL: Changelog, https://github.com/DiogoRibeiro7/subspaceknn/blob/main/CHANGELOG.md
+Author: Diogo Ribeiro
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ensemble,explainability,interpretable-machine-learning,knn,nearest-neighbours,scikit-learn
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Requires-Dist: scikit-learn>=1.6
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# subspaceknn
+
+[![CI](https://github.com/DiogoRibeiro7/subspaceknn/actions/workflows/ci.yml/badge.svg)](https://github.com/DiogoRibeiro7/subspaceknn/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/subspaceknn)](https://pypi.org/project/subspaceknn/)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://github.com/DiogoRibeiro7/subspaceknn)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Interpretable k-nearest-neighbour classification by ensembling kNN models fitted on low-dimensional feature subspaces.
+
+`SubspaceKNNClassifier` fits one k-nearest-neighbour model per small subset of features, ranks those subspaces by cross-validated performance, and lets the best of them vote, each weighted by its score. Because every member of the ensemble lives in a space of one, two or three features, a prediction can be explained by showing the neighbourhoods that produced it, and each subspace can be drawn with its decision regions.
+
+The method generalises the *interpretable kNN* (ikNN) idea of [Brett Kennedy](https://github.com/Brett-Kennedy/ikNN), described in his article [Interpretable kNN (ikNN)](https://towardsdatascience.com/interpretable-knn-iknn-33d38402b8fc), from pairs of features to subspaces of any small size. This package is an independent implementation written from the description of the method. It shares no code, text or results with the original.
+
+## Installation
+
+```sh
+pip install subspaceknn            # core: numpy and scikit-learn
+pip install "subspaceknn[plot]"    # adds matplotlib for plot_subspaces
+```
+
+The package supports Python 3.10 to 3.13 and scikit-learn 1.6 or newer.
+
+## Quick start
+
+```python
+from sklearn.datasets import load_iris
+from sklearn.model_selection import train_test_split
+
+from subspaceknn import SubspaceKNNClassifier
+
+iris = load_iris(as_frame=True)
+X, y = iris.data, iris.target_names[iris.target]
+X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=0, stratify=y)
+
+clf = SubspaceKNNClassifier(subspace_size=(1, 2), n_subspaces=4).fit(X_train, y_train)
+print(clf.score(X_test, y_test))
+
+for subspace, score, weight in zip(clf.subspaces_, clf.subspace_scores_, clf.subspace_weights_):
+    print(list(X.columns[list(subspace)]), f"score={score:.3f}", f"weight={weight:.3f}")
+```
+
+The estimator follows the scikit-learn contract, so it works inside `Pipeline`, `GridSearchCV` and `cross_val_score`, accepts data frames, and exposes `predict`, `predict_proba` and `score`. Feature scales matter for nearest neighbours, so put a `StandardScaler` in front of it unless the features are already comparable.
+
+### Explaining a prediction
+
+```python
+explanation = clf.explain(X_test.iloc[:1])[0]
+print(explanation.prediction, explanation.agreement())
+for vote in explanation.votes:
+    print(vote.feature_names, vote.prediction, f"weight={vote.weight:.3f}")
+```
+
+`explain` returns one `Explanation` per sample. It holds the ensemble prediction and probabilities and one `SubspaceVote` per subspace with the features involved, that subspace's own prediction and probabilities, its cross-validated score and its voting weight. `agreement()` is the total weight of the subspaces that voted for the final prediction, and `to_records()` produces rows ready for `pandas.DataFrame.from_records`.
+
+### Drawing the subspaces
+
+```python
+from subspaceknn.plotting import plot_subspaces
+
+fig = plot_subspaces(clf, X_train, y_train, sample=X_test.iloc[0].to_numpy())
+fig.savefig("subspaces.png")
+```
+
+One panel per subspace: a strip plot with decision intervals for one feature, a scatter plot with decision regions for two, a 3-D scatter for three. The highlighted sample is the point being explained.
+
+## How it works
+
+For subspace sizes `d` in `subspace_size`, the estimator enumerates every `d`-subset of the features, fits a `KNeighborsClassifier` on each subset and scores it with stratified cross-validation on the training data (macro-F1 by default). The `n_subspaces` best subsets form the ensemble. For a new sample the class probabilities are the weighted average of the subspace models' probabilities,
+
+```text
+p(c | x) = sum_s w_s * p_s(c | x),        w_s = score_s / sum_t score_t,
+```
+
+and the prediction is the class with the largest probability. `voting="hard"` replaces `p_s` by the one-hot prediction of each subspace and `weighting="uniform"` replaces `w_s` by equal weights.
+
+The number of subsets grows combinatorially with the number of features, so `max_candidates` caps how many are cross-validated. Above the cap, features are screened by the cross-validated score of their one-dimensional model, and only the best-scoring features are combined, as many as keep the candidate count within the cap. Everything is deterministic: subsets are enumerated in lexicographic order and ties keep that order.
+
+The full description, including how tiny training sets are handled, is in [docs/method.md](docs/method.md).
+
+## Parameters
+
+| Parameter | Default | Meaning |
+| --- | --- | --- |
+| `n_neighbors` | `5` | Neighbours used by every subspace model. |
+| `subspace_size` | `2` | Size of each subspace, or a sequence of sizes to enumerate together. |
+| `n_subspaces` | `5` | Number of best subspaces that vote; `None` uses all candidates. |
+| `max_candidates` | `100` | Cap on cross-validated subspaces; triggers feature screening above it. |
+| `voting` | `"soft"` | `"soft"` averages probabilities, `"hard"` averages one-hot votes. |
+| `weighting` | `"score"` | Weight by cross-validated score, or `"uniform"`. |
+| `cv` | `5` | Folds, or any scikit-learn splitter, used to score subspaces. |
+| `scoring` | `"f1_macro"` | Any scikit-learn scorer; higher must be better. |
+| `knn_weights`, `metric` | `"uniform"`, `"minkowski"` | Passed to the subspace models. |
+
+Fitted attributes include `subspaces_`, `subspace_scores_`, `subspace_weights_`, `estimators_`, the full `candidate_subspaces_` with `candidate_scores_`, the `screened_features_`, and `feature_scores_`, a coarse feature-relevance measure. See the class docstring for the complete list.
+
+## Does interpretability cost accuracy?
+
+Five-fold stratified cross-validated macro-F1 on scikit-learn's toy datasets, features standardised, everything else at its defaults:
+
+| Dataset | kNN | Subspaces of size 2 | Sizes 1, 2 and 3 (8 subspaces) |
+| --- | ---: | ---: | ---: |
+| iris (4 features) | 0.953 | 0.953 | 0.953 |
+| wine (13 features) | 0.960 | 0.945 | 0.967 |
+| breast cancer (30 features) | 0.962 | 0.946 | 0.943 |
+
+The ensemble stays within a couple of points of plain kNN while every one of its votes is a picture. The test suite asserts this stays true. Details in [docs/benchmark.md](docs/benchmark.md).
+
+## Limitations
+
+- Features must be numeric and are used as given; encode categorical features and scale everything first.
+- Candidate subspaces grow as the binomial coefficient of the feature count; rely on `max_candidates` or a sequence of small sizes for wide data.
+- The voting weights are cross-validated scores, not calibrated probabilities. Treat `predict_proba` as a ranking rather than a probability estimate.
+- Classification only.
+
+## Development
+
+```sh
+git clone https://github.com/DiogoRibeiro7/subspaceknn.git
+cd subspaceknn
+uv sync --all-extras
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+uv run pytest
+```
+
+The test suite runs scikit-learn's estimator contract (`check_estimator`) against two configurations, plus behavioural, explanation, plotting and benchmark tests. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License and attribution
+
+MIT, see [LICENSE](LICENSE). The method is due to Brett Kennedy's ikNN; this implementation, its generalisation to arbitrary subspace sizes, and everything in this repository were written independently.

subspaceknn-0.1.0/README.md

@@ -0,0 +1,130 @@
+# subspaceknn
+
+[![CI](https://github.com/DiogoRibeiro7/subspaceknn/actions/workflows/ci.yml/badge.svg)](https://github.com/DiogoRibeiro7/subspaceknn/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/subspaceknn)](https://pypi.org/project/subspaceknn/)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://github.com/DiogoRibeiro7/subspaceknn)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Interpretable k-nearest-neighbour classification by ensembling kNN models fitted on low-dimensional feature subspaces.
+
+`SubspaceKNNClassifier` fits one k-nearest-neighbour model per small subset of features, ranks those subspaces by cross-validated performance, and lets the best of them vote, each weighted by its score. Because every member of the ensemble lives in a space of one, two or three features, a prediction can be explained by showing the neighbourhoods that produced it, and each subspace can be drawn with its decision regions.
+
+The method generalises the *interpretable kNN* (ikNN) idea of [Brett Kennedy](https://github.com/Brett-Kennedy/ikNN), described in his article [Interpretable kNN (ikNN)](https://towardsdatascience.com/interpretable-knn-iknn-33d38402b8fc), from pairs of features to subspaces of any small size. This package is an independent implementation written from the description of the method. It shares no code, text or results with the original.
+
+## Installation
+
+```sh
+pip install subspaceknn            # core: numpy and scikit-learn
+pip install "subspaceknn[plot]"    # adds matplotlib for plot_subspaces
+```
+
+The package supports Python 3.10 to 3.13 and scikit-learn 1.6 or newer.
+
+## Quick start
+
+```python
+from sklearn.datasets import load_iris
+from sklearn.model_selection import train_test_split
+
+from subspaceknn import SubspaceKNNClassifier
+
+iris = load_iris(as_frame=True)
+X, y = iris.data, iris.target_names[iris.target]
+X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=0, stratify=y)
+
+clf = SubspaceKNNClassifier(subspace_size=(1, 2), n_subspaces=4).fit(X_train, y_train)
+print(clf.score(X_test, y_test))
+
+for subspace, score, weight in zip(clf.subspaces_, clf.subspace_scores_, clf.subspace_weights_):
+    print(list(X.columns[list(subspace)]), f"score={score:.3f}", f"weight={weight:.3f}")
+```
+
+The estimator follows the scikit-learn contract, so it works inside `Pipeline`, `GridSearchCV` and `cross_val_score`, accepts data frames, and exposes `predict`, `predict_proba` and `score`. Feature scales matter for nearest neighbours, so put a `StandardScaler` in front of it unless the features are already comparable.
+
+### Explaining a prediction
+
+```python
+explanation = clf.explain(X_test.iloc[:1])[0]
+print(explanation.prediction, explanation.agreement())
+for vote in explanation.votes:
+    print(vote.feature_names, vote.prediction, f"weight={vote.weight:.3f}")
+```
+
+`explain` returns one `Explanation` per sample. It holds the ensemble prediction and probabilities and one `SubspaceVote` per subspace with the features involved, that subspace's own prediction and probabilities, its cross-validated score and its voting weight. `agreement()` is the total weight of the subspaces that voted for the final prediction, and `to_records()` produces rows ready for `pandas.DataFrame.from_records`.
+
+### Drawing the subspaces
+
+```python
+from subspaceknn.plotting import plot_subspaces
+
+fig = plot_subspaces(clf, X_train, y_train, sample=X_test.iloc[0].to_numpy())
+fig.savefig("subspaces.png")
+```
+
+One panel per subspace: a strip plot with decision intervals for one feature, a scatter plot with decision regions for two, a 3-D scatter for three. The highlighted sample is the point being explained.
+
+## How it works
+
+For subspace sizes `d` in `subspace_size`, the estimator enumerates every `d`-subset of the features, fits a `KNeighborsClassifier` on each subset and scores it with stratified cross-validation on the training data (macro-F1 by default). The `n_subspaces` best subsets form the ensemble. For a new sample the class probabilities are the weighted average of the subspace models' probabilities,
+
+```text
+p(c | x) = sum_s w_s * p_s(c | x),        w_s = score_s / sum_t score_t,
+```
+
+and the prediction is the class with the largest probability. `voting="hard"` replaces `p_s` by the one-hot prediction of each subspace and `weighting="uniform"` replaces `w_s` by equal weights.
+
+The number of subsets grows combinatorially with the number of features, so `max_candidates` caps how many are cross-validated. Above the cap, features are screened by the cross-validated score of their one-dimensional model, and only the best-scoring features are combined, as many as keep the candidate count within the cap. Everything is deterministic: subsets are enumerated in lexicographic order and ties keep that order.
+
+The full description, including how tiny training sets are handled, is in [docs/method.md](docs/method.md).
+
+## Parameters
+
+| Parameter | Default | Meaning |
+| --- | --- | --- |
+| `n_neighbors` | `5` | Neighbours used by every subspace model. |
+| `subspace_size` | `2` | Size of each subspace, or a sequence of sizes to enumerate together. |
+| `n_subspaces` | `5` | Number of best subspaces that vote; `None` uses all candidates. |
+| `max_candidates` | `100` | Cap on cross-validated subspaces; triggers feature screening above it. |
+| `voting` | `"soft"` | `"soft"` averages probabilities, `"hard"` averages one-hot votes. |
+| `weighting` | `"score"` | Weight by cross-validated score, or `"uniform"`. |
+| `cv` | `5` | Folds, or any scikit-learn splitter, used to score subspaces. |
+| `scoring` | `"f1_macro"` | Any scikit-learn scorer; higher must be better. |
+| `knn_weights`, `metric` | `"uniform"`, `"minkowski"` | Passed to the subspace models. |
+
+Fitted attributes include `subspaces_`, `subspace_scores_`, `subspace_weights_`, `estimators_`, the full `candidate_subspaces_` with `candidate_scores_`, the `screened_features_`, and `feature_scores_`, a coarse feature-relevance measure. See the class docstring for the complete list.
+
+## Does interpretability cost accuracy?
+
+Five-fold stratified cross-validated macro-F1 on scikit-learn's toy datasets, features standardised, everything else at its defaults:
+
+| Dataset | kNN | Subspaces of size 2 | Sizes 1, 2 and 3 (8 subspaces) |
+| --- | ---: | ---: | ---: |
+| iris (4 features) | 0.953 | 0.953 | 0.953 |
+| wine (13 features) | 0.960 | 0.945 | 0.967 |
+| breast cancer (30 features) | 0.962 | 0.946 | 0.943 |
+
+The ensemble stays within a couple of points of plain kNN while every one of its votes is a picture. The test suite asserts this stays true. Details in [docs/benchmark.md](docs/benchmark.md).
+
+## Limitations
+
+- Features must be numeric and are used as given; encode categorical features and scale everything first.
+- Candidate subspaces grow as the binomial coefficient of the feature count; rely on `max_candidates` or a sequence of small sizes for wide data.
+- The voting weights are cross-validated scores, not calibrated probabilities. Treat `predict_proba` as a ranking rather than a probability estimate.
+- Classification only.
+
+## Development
+
+```sh
+git clone https://github.com/DiogoRibeiro7/subspaceknn.git
+cd subspaceknn
+uv sync --all-extras
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+uv run pytest
+```
+
+The test suite runs scikit-learn's estimator contract (`check_estimator`) against two configurations, plus behavioural, explanation, plotting and benchmark tests. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License and attribution
+
+MIT, see [LICENSE](LICENSE). The method is due to Brett Kennedy's ikNN; this implementation, its generalisation to arbitrary subspace sizes, and everything in this repository were written independently.

subspaceknn-0.1.0/SECURITY.md

@@ -0,0 +1,25 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are applied to the `main` branch and to the latest release on PyPI. Older releases do not receive backports.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for security problems.
+
+Use GitHub private vulnerability reporting instead:
+<https://github.com/DiogoRibeiro7/subspaceknn/security/advisories/new>
+
+You can expect an acknowledgement within seven days. Once the report is confirmed, a fix and a coordinated disclosure date are agreed with the reporter before any advisory is published.
+
+## Scope
+
+`subspaceknn` is a pure-Python library depending on numpy and scikit-learn. Its public API validates every input and raises typed errors rather than failing unpredictably.
+
+The following are treated as security-relevant and welcome through the private channel:
+
+- unbounded resource use reachable through the public API with attacker-controlled input beyond what `max_candidates` documents;
+- vulnerabilities in the dependency tree that affect this package.
+
+Accuracy problems, surprising predictions or explanation semantics are correctness bugs, not vulnerabilities. Please report them as ordinary issues with a minimal reproduction.