subspaceknn 0.1.0__py3-none-any.whl

subspaceknn/__init__.py

@@ -0,0 +1,15 @@
+"""Interpretable k-nearest-neighbour classification on low-dimensional feature subspaces.
+
+The package provides :class:`SubspaceKNNClassifier`, a scikit-learn compatible
+classifier that fits one k-nearest-neighbour model per small subset of features,
+ranks those subspaces by cross-validated performance, and combines the best of
+them by weighted voting. Because every member of the ensemble lives in a space of
+one, two or three features, each prediction can be explained by looking at the
+neighbourhoods that produced it.
+"""
+
+from subspaceknn._classifier import SubspaceKNNClassifier
+from subspaceknn._explanation import Explanation, SubspaceVote
+
+__all__ = ["Explanation", "SubspaceKNNClassifier", "SubspaceVote"]
+__version__ = "0.1.0"

subspaceknn/_classifier.py

@@ -0,0 +1,468 @@
+"""Ensemble of k-nearest-neighbour classifiers on low-dimensional feature subspaces."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from itertools import combinations
+from math import ceil, comb
+from numbers import Integral
+from typing import TYPE_CHECKING, Any, Literal, TypeGuard
+
+import numpy as np
+from sklearn.base import BaseEstimator, ClassifierMixin
+from sklearn.metrics import get_scorer
+from sklearn.model_selection import StratifiedKFold, cross_val_score
+from sklearn.neighbors import KNeighborsClassifier
+from sklearn.utils.multiclass import check_classification_targets, unique_labels
+from sklearn.utils.validation import check_is_fitted, validate_data
+
+from subspaceknn._explanation import Explanation, SubspaceVote
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+    from numpy.typing import ArrayLike, NDArray
+    from sklearn.model_selection import BaseCrossValidator
+
+Voting = Literal["soft", "hard"]
+Weighting = Literal["score", "uniform"]
+
+
+class SubspaceKNNClassifier(ClassifierMixin, BaseEstimator):  # type: ignore[misc]
+    """Weighted vote of k-nearest-neighbour classifiers fitted on small feature subspaces.
+
+    The estimator enumerates every subset of ``subspace_size`` features (or every
+    subset of each size when a sequence of sizes is given), fits a
+    :class:`~sklearn.neighbors.KNeighborsClassifier` on each subset, and scores
+    it by cross-validation on the training data. The ``n_subspaces`` best
+    subspaces then vote on new samples, each weighted by its cross-validated
+    score. Because the members of the ensemble live in spaces of one, two or
+    three features, every prediction can be explained by looking at the
+    neighbourhoods that produced it; see :meth:`explain`.
+
+    The method generalises the interpretable kNN (ikNN) idea of Brett Kennedy,
+    which uses pairs of features only, to subspaces of any small size. This is
+    an independent implementation that shares no code with the original.
+
+    Parameters
+    ----------
+    n_neighbors : int, default=5
+        Number of neighbours used by every subspace model.
+    subspace_size : int or sequence of int, default=2
+        Number of features in each subspace. A sequence enumerates subspaces of
+        every listed size. Sizes larger than the number of features are ignored.
+    n_subspaces : int or None, default=5
+        Number of best-scoring subspaces used for prediction. ``None`` uses every
+        candidate subspace.
+    max_candidates : int or None, default=100
+        Soft cap on the number of candidate subspaces that are cross-validated.
+        When the number of subsets exceeds it, features are first 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. ``None`` evaluates every subset, which grows
+        combinatorially with the number of features.
+    voting : {"soft", "hard"}, default="soft"
+        ``"soft"`` averages the class probabilities of the subspace models,
+        ``"hard"`` averages their one-hot predictions.
+    weighting : {"score", "uniform"}, default="score"
+        ``"score"`` weights each subspace by its cross-validated score (negative
+        scores are clipped to zero), ``"uniform"`` gives every subspace the same
+        weight.
+    cv : int or cross-validation generator, default=5
+        Cross-validation used to score subspaces. An integer selects stratified
+        k-fold with that many splits, reduced automatically when a class has fewer
+        samples than splits. When the training set is too small to
+        cross-validate at all, the resubstitution score on the training data is
+        used instead.
+    scoring : str or callable, default="f1_macro"
+        Any scikit-learn scorer. Score-based weighting assumes higher is better
+        and scores are non-negative.
+    knn_weights : {"uniform", "distance"}, default="uniform"
+        Neighbour weighting passed to the subspace models.
+    metric : str, default="minkowski"
+        Distance metric passed to the subspace models.
+    n_jobs : int or None, default=None
+        Parallelism for cross-validation, passed to
+        :func:`~sklearn.model_selection.cross_val_score`.
+
+    Attributes
+    ----------
+    classes_ : ndarray of shape (n_classes,)
+        Class labels.
+    n_features_in_ : int
+        Number of features seen during :meth:`fit`.
+    feature_names_in_ : ndarray of shape (n_features_in_,)
+        Feature names, only when ``X`` had string column names.
+    screened_features_ : ndarray of shape (n_screened,)
+        Indices of the features retained after screening, all features when no
+        screening was necessary.
+    feature_screening_scores_ : ndarray of shape (n_features_in_,) or None
+        Cross-validated score of each feature's one-dimensional model, only when
+        screening took place.
+    candidate_subspaces_ : list of tuple of int
+        Every subspace that was cross-validated, in enumeration order.
+    candidate_scores_ : ndarray of shape (n_candidates,)
+        Cross-validated score of each candidate subspace.
+    subspaces_ : list of tuple of int
+        Subspaces used for prediction, from the best to the worst score.
+    subspace_scores_ : ndarray of shape (n_selected,)
+        Scores of the selected subspaces.
+    subspace_weights_ : ndarray of shape (n_selected,)
+        Normalised voting weights of the selected subspaces; they sum to one.
+    estimators_ : list of KNeighborsClassifier
+        Fitted subspace models, aligned with ``subspaces_``.
+    feature_scores_ : ndarray of shape (n_features_in_,)
+        Mean score of the selected subspaces containing each feature, zero for
+        features that appear in none. A coarse measure of feature relevance.
+
+    Examples
+    --------
+    >>> from sklearn.datasets import load_iris
+    >>> from subspaceknn import SubspaceKNNClassifier
+    >>> X, y = load_iris(return_X_y=True)
+    >>> clf = SubspaceKNNClassifier(subspace_size=(1, 2)).fit(X, y)
+    >>> clf.subspaces_[0]
+    (2, 3)
+    >>> clf.explain(X[:1])[0].votes[0].feature_names
+    ('x2', 'x3')
+    """
+
+    def __init__(
+        self,
+        *,
+        n_neighbors: int = 5,
+        subspace_size: int | Sequence[int] = 2,
+        n_subspaces: int | None = 5,
+        max_candidates: int | None = 100,
+        voting: Voting = "soft",
+        weighting: Weighting = "score",
+        cv: int | BaseCrossValidator = 5,
+        scoring: str | Callable[..., float] = "f1_macro",
+        knn_weights: Literal["uniform", "distance"] = "uniform",
+        metric: str = "minkowski",
+        n_jobs: int | None = None,
+    ) -> None:
+        self.n_neighbors = n_neighbors
+        self.subspace_size = subspace_size
+        self.n_subspaces = n_subspaces
+        self.max_candidates = max_candidates
+        self.voting = voting
+        self.weighting = weighting
+        self.cv = cv
+        self.scoring = scoring
+        self.knn_weights = knn_weights
+        self.metric = metric
+        self.n_jobs = n_jobs
+
+    # ------------------------------------------------------------------ fitting
+
+    def fit(self, X: ArrayLike, y: ArrayLike) -> SubspaceKNNClassifier:
+        """Fit one subspace model per candidate subspace and select the best.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Training data.
+        y : array-like of shape (n_samples,)
+            Class labels.
+
+        Returns
+        -------
+        self
+            The fitted estimator.
+        """
+        X_arr, y_arr = validate_data(self, X, y, dtype="numeric")
+        check_classification_targets(y_arr)
+        self._check_hyperparameters()
+        n_samples, n_features = X_arr.shape
+        if self.n_neighbors > n_samples:
+            raise ValueError(
+                "Expected n_neighbors <= n_samples, got "
+                f"n_neighbors={self.n_neighbors} and n_samples={n_samples}.",
+            )
+
+        self.classes_ = unique_labels(y_arr)
+        y_encoded = np.searchsorted(self.classes_, y_arr)
+        sizes = self._subspace_sizes(n_features)
+        cv = self._cross_validator(y_encoded)
+
+        features = np.arange(n_features)
+        self.feature_screening_scores_: NDArray[np.float64] | None = None
+        total = sum(comb(n_features, size) for size in sizes)
+        if self.max_candidates is not None and total > self.max_candidates:
+            singletons = [(index,) for index in range(n_features)]
+            screening = self._score_subspaces(singletons, X_arr, y_encoded, cv)
+            self.feature_screening_scores_ = screening
+            keep = self._n_features_to_keep(sizes, n_features, self.max_candidates)
+            features = np.sort(np.argsort(-screening, kind="stable")[:keep])
+        self.screened_features_ = features
+
+        feature_list = [int(index) for index in features]
+        candidates = [combo for size in sizes for combo in combinations(feature_list, size)]
+        scores = self._score_subspaces(candidates, X_arr, y_encoded, cv)
+        self.candidate_subspaces_ = candidates
+        self.candidate_scores_ = scores
+
+        order = np.argsort(-scores, kind="stable")
+        if self.n_subspaces is not None:
+            order = order[: self.n_subspaces]
+        self.subspaces_ = [candidates[index] for index in order]
+        self.subspace_scores_ = scores[order]
+        self.subspace_weights_ = self._weights(self.subspace_scores_)
+        self.estimators_ = [
+            self._make_knn().fit(X_arr[:, list(subspace)], y_encoded)
+            for subspace in self.subspaces_
+        ]
+        self.feature_scores_ = self._feature_scores(n_features)
+        return self
+
+    def _check_hyperparameters(self) -> None:
+        if not _is_positive_integer(self.n_neighbors):
+            raise ValueError(f"n_neighbors must be a positive integer, got {self.n_neighbors!r}.")
+        sizes = self._requested_sizes()
+        if not sizes or any(size < 1 for size in sizes):
+            raise ValueError(
+                "subspace_size must be a positive integer or a non-empty sequence of "
+                f"positive integers, got {self.subspace_size!r}.",
+            )
+        if self.n_subspaces is not None and not _is_positive_integer(self.n_subspaces):
+            raise ValueError(
+                f"n_subspaces must be None or a positive integer, got {self.n_subspaces!r}.",
+            )
+        if self.max_candidates is not None and not _is_positive_integer(self.max_candidates):
+            raise ValueError(
+                f"max_candidates must be None or a positive integer, got {self.max_candidates!r}.",
+            )
+        if self.voting not in ("soft", "hard"):
+            raise ValueError(f"voting must be 'soft' or 'hard', got {self.voting!r}.")
+        if self.weighting not in ("score", "uniform"):
+            raise ValueError(f"weighting must be 'score' or 'uniform', got {self.weighting!r}.")
+        if _is_integer(self.cv) and self.cv < 2:  # noqa: PLR2004
+            raise ValueError(f"cv must be at least 2 when given as an integer, got {self.cv!r}.")
+
+    def _requested_sizes(self) -> list[int]:
+        value: object = self.subspace_size
+        if _is_integer(value):
+            return [value]
+        if isinstance(value, str) or not isinstance(value, Iterable):
+            return []
+        sizes = list(value)
+        if not all(_is_integer(size) for size in sizes):
+            return []
+        return [int(size) for size in sizes]
+
+    def _subspace_sizes(self, n_features: int) -> list[int]:
+        requested = sorted(set(self._requested_sizes()))
+        sizes = [size for size in requested if size <= n_features]
+        if not sizes:
+            raise ValueError(
+                f"No feature subspace of size {requested} fits in n_features={n_features}; "
+                "reduce subspace_size or add features.",
+            )
+        return sizes
+
+    def _cross_validator(self, y_encoded: NDArray[np.intp]) -> BaseCrossValidator | None:
+        """Return the splitter used to score subspaces, or None for resubstitution scoring."""
+        if not _is_integer(self.cv):
+            return self.cv
+        n_samples = len(y_encoded)
+        smallest_class = int(np.bincount(y_encoded).min())
+        n_splits = min(self.cv, smallest_class)
+        if n_splits < 2:  # noqa: PLR2004
+            return None
+        smallest_training_fold = n_samples - ceil(n_samples / n_splits)
+        if smallest_training_fold < self.n_neighbors:
+            return None
+        return StratifiedKFold(n_splits=n_splits)
+
+    def _make_knn(self) -> KNeighborsClassifier:
+        return KNeighborsClassifier(
+            n_neighbors=self.n_neighbors,
+            weights=self.knn_weights,
+            metric=self.metric,
+        )
+
+    def _score_subspaces(
+        self,
+        subspaces: Sequence[tuple[int, ...]],
+        X: NDArray[np.float64],
+        y_encoded: NDArray[np.intp],
+        cv: BaseCrossValidator | None,
+    ) -> NDArray[np.float64]:
+        if cv is None:
+            return self._resubstitution_scores(subspaces, X, y_encoded)
+        scores = np.empty(len(subspaces), dtype=np.float64)
+        for position, subspace in enumerate(subspaces):
+            fold_scores = cross_val_score(
+                self._make_knn(),
+                X[:, list(subspace)],
+                y_encoded,
+                cv=cv,
+                scoring=self.scoring,
+                n_jobs=self.n_jobs,
+                error_score="raise",
+            )
+            scores[position] = float(np.mean(fold_scores))
+        return scores
+
+    def _resubstitution_scores(
+        self,
+        subspaces: Sequence[tuple[int, ...]],
+        X: NDArray[np.float64],
+        y_encoded: NDArray[np.intp],
+    ) -> NDArray[np.float64]:
+        """Score each subspace on its own training data.
+
+        Used only when the training set is too small to cross-validate.
+        """
+        scorer = get_scorer(self.scoring)
+        scores = np.empty(len(subspaces), dtype=np.float64)
+        for position, subspace in enumerate(subspaces):
+            X_sub = X[:, list(subspace)]
+            model = self._make_knn().fit(X_sub, y_encoded)
+            scores[position] = float(scorer(model, X_sub, y_encoded))
+        return scores
+
+    @staticmethod
+    def _n_features_to_keep(sizes: Sequence[int], n_features: int, max_candidates: int) -> int:
+        """Largest feature count whose subspace count stays within ``max_candidates``."""
+        floor = max(sizes)
+        keep = floor
+        for count in range(floor, n_features + 1):
+            if sum(comb(count, size) for size in sizes) <= max_candidates:
+                keep = count
+            else:
+                break
+        return keep
+
+    def _weights(self, scores: NDArray[np.float64]) -> NDArray[np.float64]:
+        if self.weighting == "score":
+            clipped = np.clip(scores, 0.0, None)
+            if clipped.sum() > 0.0:
+                return np.asarray(clipped / clipped.sum(), dtype=np.float64)
+        return np.full(len(scores), 1.0 / len(scores), dtype=np.float64)
+
+    def _feature_scores(self, n_features: int) -> NDArray[np.float64]:
+        totals = np.zeros(n_features, dtype=np.float64)
+        counts = np.zeros(n_features, dtype=np.float64)
+        for subspace, score in zip(self.subspaces_, self.subspace_scores_, strict=True):
+            for feature in subspace:
+                totals[feature] += score
+                counts[feature] += 1.0
+        return np.asarray(np.divide(totals, counts, out=np.zeros_like(totals), where=counts > 0))
+
+    # --------------------------------------------------------------- predicting
+
+    def predict_proba(self, X: ArrayLike) -> NDArray[np.float64]:
+        """Return the weighted average of the subspace models' class probabilities.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Samples to classify.
+
+        Returns
+        -------
+        ndarray of shape (n_samples, n_classes)
+            Class probabilities aligned with ``classes_``; each row sums to one.
+        """
+        check_is_fitted(self)
+        X_arr = validate_data(self, X, reset=False, dtype="numeric")
+        votes = self._subspace_votes(X_arr)
+        proba = np.tensordot(self.subspace_weights_, votes, axes=1)
+        return self._normalise(proba)
+
+    def predict(self, X: ArrayLike) -> NDArray[Any]:
+        """Return the class with the highest ensemble probability for each sample.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Samples to classify.
+
+        Returns
+        -------
+        ndarray of shape (n_samples,)
+            Predicted class labels.
+        """
+        proba = self.predict_proba(X)
+        return np.asarray(self.classes_[np.argmax(proba, axis=1)])
+
+    def explain(self, X: ArrayLike) -> list[Explanation]:
+        """Explain the prediction for every sample in ``X``.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Samples to explain.
+
+        Returns
+        -------
+        list of Explanation
+            One explanation per sample, each listing the vote of every subspace
+            used by the ensemble, ordered from the highest to the lowest weight.
+        """
+        check_is_fitted(self)
+        X_arr = validate_data(self, X, reset=False, dtype="numeric")
+        votes = self._subspace_votes(X_arr)
+        proba = self._normalise(np.tensordot(self.subspace_weights_, votes, axes=1))
+        names = self._feature_names()
+        explanations: list[Explanation] = []
+        for row in range(X_arr.shape[0]):
+            row_votes = tuple(
+                SubspaceVote(
+                    features=subspace,
+                    feature_names=tuple(names[index] for index in subspace),
+                    score=float(score),
+                    weight=float(weight),
+                    probabilities=votes[position, row],
+                    prediction=self.classes_[int(np.argmax(votes[position, row]))],
+                )
+                for position, (subspace, score, weight) in enumerate(
+                    zip(
+                        self.subspaces_, self.subspace_scores_, self.subspace_weights_, strict=True
+                    ),
+                )
+            )
+            explanations.append(
+                Explanation(
+                    prediction=self.classes_[int(np.argmax(proba[row]))],
+                    probabilities=proba[row],
+                    classes=self.classes_,
+                    votes=row_votes,
+                ),
+            )
+        return explanations
+
+    def _subspace_votes(self, X: NDArray[np.float64]) -> NDArray[np.float64]:
+        """Return an array of shape (n_selected, n_samples, n_classes) with each subspace's vote."""
+        n_classes = len(self.classes_)
+        votes = np.empty((len(self.estimators_), X.shape[0], n_classes), dtype=np.float64)
+        for position, (estimator, subspace) in enumerate(
+            zip(self.estimators_, self.subspaces_, strict=True),
+        ):
+            X_sub = X[:, list(subspace)]
+            if self.voting == "hard":
+                votes[position] = np.eye(n_classes)[estimator.predict(X_sub)]
+            else:
+                votes[position] = estimator.predict_proba(X_sub)
+        return votes
+
+    def _normalise(self, proba: NDArray[np.float64]) -> NDArray[np.float64]:
+        row_sums = proba.sum(axis=1, keepdims=True)
+        uniform = np.full_like(proba, 1.0 / proba.shape[1])
+        return np.asarray(np.divide(proba, row_sums, out=uniform, where=row_sums > 0))
+
+    def _feature_names(self) -> list[str]:
+        names = getattr(self, "feature_names_in_", None)
+        if names is None:
+            return [f"x{index}" for index in range(self.n_features_in_)]
+        return [str(name) for name in names]
+
+
+def _is_integer(value: object) -> TypeGuard[int]:
+    return isinstance(value, Integral) and not isinstance(value, bool)
+
+
+def _is_positive_integer(value: object) -> TypeGuard[int]:
+    return _is_integer(value) and value > 0

subspaceknn/_explanation.py

@@ -0,0 +1,92 @@
+"""Structured explanations of individual predictions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import numpy as np
+    from numpy.typing import NDArray
+
+
+@dataclass(frozen=True)
+class SubspaceVote:
+    """The contribution of one feature subspace to a single prediction.
+
+    Attributes
+    ----------
+    features : tuple of int
+        Column indices of the features that span the subspace.
+    feature_names : tuple of str
+        Names of those features, taken from ``feature_names_in_`` when the
+        estimator was fitted on a data frame and ``x<i>`` otherwise.
+    score : float
+        Cross-validated score of the subspace on the training data.
+    weight : float
+        Normalised weight of the subspace in the ensemble vote. Weights sum to one
+        across the subspaces used for prediction.
+    probabilities : ndarray of shape (n_classes,)
+        Class probabilities produced by this subspace alone, aligned with
+        ``Explanation.classes``. Under hard voting this is a one-hot vector.
+    prediction : Any
+        Class label predicted by this subspace alone.
+    """
+
+    features: tuple[int, ...]
+    feature_names: tuple[str, ...]
+    score: float
+    weight: float
+    probabilities: NDArray[np.float64]
+    prediction: Any
+
+
+@dataclass(frozen=True)
+class Explanation:
+    """How the ensemble arrived at the prediction for one sample.
+
+    Attributes
+    ----------
+    prediction : Any
+        Class label predicted by the ensemble.
+    probabilities : ndarray of shape (n_classes,)
+        Ensemble class probabilities, the weighted average of the votes.
+    classes : ndarray of shape (n_classes,)
+        Class labels, in the order used by ``probabilities``.
+    votes : tuple of SubspaceVote
+        One entry per subspace used for prediction, ordered from the highest to
+        the lowest weight.
+    """
+
+    prediction: Any
+    probabilities: NDArray[np.float64]
+    classes: NDArray[Any]
+    votes: tuple[SubspaceVote, ...]
+
+    def agreement(self) -> float:
+        """Return the weighted fraction of subspaces that voted for the ensemble prediction."""
+        return float(
+            sum(vote.weight for vote in self.votes if vote.prediction == self.prediction),
+        )
+
+    def to_records(self) -> list[dict[str, Any]]:
+        """Return the votes as plain dictionaries, one per subspace.
+
+        The result is suitable for ``pandas.DataFrame.from_records`` and contains,
+        for every vote, the feature names, the subspace score and weight, the
+        subspace prediction, whether it agrees with the ensemble, and one
+        ``p(<class>)`` column per class.
+        """
+        records: list[dict[str, Any]] = []
+        for vote in self.votes:
+            record: dict[str, Any] = {
+                "features": ", ".join(vote.feature_names),
+                "score": vote.score,
+                "weight": vote.weight,
+                "prediction": vote.prediction,
+                "agrees": bool(vote.prediction == self.prediction),
+            }
+            for label, probability in zip(self.classes, vote.probabilities, strict=True):
+                record[f"p({label})"] = float(probability)
+            records.append(record)
+        return records

subspaceknn/plotting.py

@@ -0,0 +1,275 @@
+"""Visualise the subspaces of a fitted :class:`~subspaceknn.SubspaceKNNClassifier`.
+
+This module needs matplotlib, which is an optional dependency::
+
+    pip install "subspaceknn[plot]"
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+import numpy as np
+from sklearn.utils.validation import check_is_fitted, validate_data
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from matplotlib.axes import Axes
+    from matplotlib.figure import Figure
+    from mpl_toolkits.mplot3d import Axes3D
+    from numpy.typing import ArrayLike, NDArray
+    from sklearn.neighbors import KNeighborsClassifier
+
+    from subspaceknn._classifier import SubspaceKNNClassifier
+
+_PALETTE = (
+    "tab:blue",
+    "tab:orange",
+    "tab:green",
+    "tab:red",
+    "tab:purple",
+    "tab:brown",
+    "tab:pink",
+    "tab:gray",
+    "tab:olive",
+    "tab:cyan",
+)
+
+
+def plot_subspaces(
+    estimator: SubspaceKNNClassifier,
+    X: ArrayLike,
+    y: ArrayLike,
+    *,
+    sample: ArrayLike | None = None,
+    n_subspaces: int | None = None,
+    grid_resolution: int = 100,
+    panel_size: float = 4.0,
+) -> Figure:
+    """Draw the training data in the best subspaces, with decision regions where possible.
+
+    Parameters
+    ----------
+    estimator : SubspaceKNNClassifier
+        A fitted estimator.
+    X : array-like of shape (n_samples, n_features)
+        Data to draw, usually the training data.
+    y : array-like of shape (n_samples,)
+        Class labels of ``X``.
+    sample : array-like of shape (n_features,), optional
+        A single sample to highlight with a star in every panel, for example a
+        test point whose prediction is being explained.
+    n_subspaces : int, optional
+        Number of panels, from the best subspace onwards. Defaults to all
+        subspaces used for prediction.
+    grid_resolution : int, default=100
+        Number of grid points per axis for the decision regions of one- and
+        two-dimensional subspaces.
+    panel_size : float, default=4.0
+        Width and height of each panel in inches.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The figure; it is not shown or saved.
+
+    Raises
+    ------
+    ImportError
+        If matplotlib is not installed.
+    """
+    try:
+        import matplotlib.pyplot as plt  # noqa: PLC0415
+    except ImportError as error:  # pragma: no cover - exercised only without matplotlib
+        raise ImportError(
+            "plot_subspaces needs matplotlib; install it with 'pip install subspaceknn[plot]'.",
+        ) from error
+
+    check_is_fitted(estimator)
+    X_arr = validate_data(estimator, X, reset=False, dtype="numeric")
+    y_arr = np.asarray(y)
+    sample_arr = None if sample is None else np.asarray(sample, dtype=np.float64).reshape(-1)
+    names = estimator._feature_names()  # noqa: SLF001
+    subspaces = estimator.subspaces_ if n_subspaces is None else estimator.subspaces_[:n_subspaces]
+    n_panels = max(len(subspaces), 1)
+
+    fig = plt.figure(figsize=(panel_size * n_panels, panel_size))
+    for panel, subspace in enumerate(subspaces, start=1):
+        estimator_index = estimator.subspaces_.index(subspace)
+        model = estimator.estimators_[estimator_index]
+        score = float(estimator.subspace_scores_[estimator_index])
+        title = f"{', '.join(names[index] for index in subspace)}\nscore {score:.3f}"
+        if len(subspace) == 1:
+            ax = fig.add_subplot(1, n_panels, panel)
+            _draw_1d(
+                ax,
+                model=model,
+                classes=estimator.classes_,
+                X=X_arr,
+                y=y_arr,
+                subspace=subspace,
+                sample=sample_arr,
+                grid_resolution=grid_resolution,
+            )
+        elif len(subspace) == 2:  # noqa: PLR2004
+            ax = fig.add_subplot(1, n_panels, panel)
+            _draw_2d(
+                ax,
+                model=model,
+                classes=estimator.classes_,
+                X=X_arr,
+                y=y_arr,
+                subspace=subspace,
+                sample=sample_arr,
+                grid_resolution=grid_resolution,
+            )
+        elif len(subspace) == 3:  # noqa: PLR2004
+            axes3d = cast("Axes3D", fig.add_subplot(1, n_panels, panel, projection="3d"))
+            _draw_3d(
+                axes3d,
+                classes=estimator.classes_,
+                X=X_arr,
+                y=y_arr,
+                subspace=subspace,
+                sample=sample_arr,
+            )
+            ax = axes3d
+        else:
+            ax = fig.add_subplot(1, n_panels, panel)
+            _draw_2d(
+                ax,
+                model=None,
+                classes=estimator.classes_,
+                X=X_arr,
+                y=y_arr,
+                subspace=subspace[:2],
+                sample=sample_arr,
+                grid_resolution=grid_resolution,
+            )
+            title += f" (first two of {len(subspace)} features)"
+        ax.set_title(title)
+        ax.legend(loc="best", fontsize="small")
+    fig.tight_layout()
+    return fig
+
+
+def _colour(index: int) -> str:
+    return _PALETTE[index % len(_PALETTE)]
+
+
+def _draw_1d(
+    ax: Axes,
+    *,
+    model: KNeighborsClassifier,
+    classes: NDArray[Any],
+    X: NDArray[np.float64],
+    y: NDArray[Any],
+    subspace: Sequence[int],
+    sample: NDArray[np.float64] | None,
+    grid_resolution: int,
+) -> None:
+    column = X[:, subspace[0]]
+    low, high = _padded_range(column)
+    grid = np.linspace(low, high, grid_resolution)
+    regions = model.predict(grid.reshape(-1, 1))
+    for index in range(len(grid) - 1):
+        ax.axvspan(
+            grid[index], grid[index + 1], color=_colour(int(regions[index])), alpha=0.12, lw=0
+        )
+    for class_index, label in enumerate(classes):
+        mask = y == label
+        ax.scatter(
+            column[mask],
+            np.full(mask.sum(), class_index),
+            s=18,
+            alpha=0.6,
+            c=_colour(class_index),
+            label=str(label),
+        )
+    if sample is not None:
+        ax.axvline(sample[subspace[0]], color="black", lw=1.2, ls="--", label="sample")
+    ax.set_yticks(range(len(classes)))
+    ax.set_yticklabels([str(label) for label in classes])
+    ax.set_xlim(low, high)
+
+
+def _draw_2d(
+    ax: Axes,
+    *,
+    model: KNeighborsClassifier | None,
+    classes: NDArray[Any],
+    X: NDArray[np.float64],
+    y: NDArray[Any],
+    subspace: Sequence[int],
+    sample: NDArray[np.float64] | None,
+    grid_resolution: int,
+) -> None:
+    first, second = subspace[0], subspace[1]
+    x_low, x_high = _padded_range(X[:, first])
+    y_low, y_high = _padded_range(X[:, second])
+    if model is not None:
+        mesh_x, mesh_y = np.meshgrid(
+            np.linspace(x_low, x_high, grid_resolution),
+            np.linspace(y_low, y_high, grid_resolution),
+        )
+        grid = np.column_stack([mesh_x.ravel(), mesh_y.ravel()])
+        regions = model.predict(grid).reshape(mesh_x.shape)
+        levels = np.arange(len(classes) + 1) - 0.5
+        colours = [_colour(index) for index in range(len(classes))]
+        ax.contourf(mesh_x, mesh_y, regions, levels=levels, colors=colours, alpha=0.12)
+    for class_index, label in enumerate(classes):
+        mask = y == label
+        ax.scatter(
+            X[mask, first],
+            X[mask, second],
+            s=18,
+            alpha=0.6,
+            c=_colour(class_index),
+            label=str(label),
+        )
+    if sample is not None:
+        ax.plot(
+            sample[first], sample[second], marker="*", markersize=16, color="black", label="sample"
+        )
+    ax.set_xlim(x_low, x_high)
+    ax.set_ylim(y_low, y_high)
+
+
+def _draw_3d(
+    ax: Axes3D,
+    *,
+    classes: NDArray[Any],
+    X: NDArray[np.float64],
+    y: NDArray[Any],
+    subspace: Sequence[int],
+    sample: NDArray[np.float64] | None,
+) -> None:
+    first, second, third = subspace[0], subspace[1], subspace[2]
+    for class_index, label in enumerate(classes):
+        mask = y == label
+        ax.scatter(
+            X[mask, first],
+            X[mask, second],
+            X[mask, third],
+            s=14,
+            alpha=0.6,
+            c=_colour(class_index),
+            label=str(label),
+        )
+    if sample is not None:
+        ax.scatter(
+            [sample[first]],
+            [sample[second]],
+            [sample[third]],
+            marker="*",
+            s=200,
+            c="black",
+            label="sample",
+        )
+
+
+def _padded_range(values: NDArray[np.float64]) -> tuple[float, float]:
+    low, high = float(np.min(values)), float(np.max(values))
+    pad = 0.05 * (high - low) if high > low else 0.5
+    return low - pad, high + pad

subspaceknn-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+subspaceknn/__init__.py,sha256=1x2Dw8xwtSuk6pw51UO3pg7WqfrJkau_Wcld1VRakds,740
+subspaceknn/_classifier.py,sha256=GLHQ9O9EqdpM8yVJOp8RByW1lswKMvQsBpQv-tTizwA,20208
+subspaceknn/_explanation.py,sha256=lvo-Lgn5Nvbj3jxw6JIPfknnwav6sTp3Sx1m6zuCCDg,3302
+subspaceknn/plotting.py,sha256=WQbuVp6WE3BWQ8bt0iCh3wwVZBNC_roQ0I9NU4-Wa5w,8698
+subspaceknn/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+subspaceknn-0.1.0.dist-info/METADATA,sha256=8yhcCUQV8q3InOUHdn83q1-PDGw_n0NGbJ2Jodp3QDI,9250
+subspaceknn-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+subspaceknn-0.1.0.dist-info/licenses/LICENSE,sha256=jPYDkXzOXETff4tGRBkRvUJtBxPtpZKJ_ukTRSWkaVg,1070
+subspaceknn-0.1.0.dist-info/RECORD,,

subspaceknn-0.1.0.dist-info/WHEEL

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

subspaceknn-0.1.0.dist-info/licenses/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.