i-attp 0.1.0__tar.gz

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

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/i-attp
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

i_attp-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/

i_attp-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: i-attp
+Version: 0.1.0
+Summary: S-ATTP: cluster-stratified train/test splitting on an LDA-reduced feature space.
+Project-URL: Homepage, https://github.com/Jabualani/ATTP
+Project-URL: Repository, https://github.com/Jabualani/ATTP
+Project-URL: Issues, https://github.com/Jabualani/ATTP/issues
+Author-email: Jabulani Monchwe <MonchweJ.25@gmail.com>
+License: MIT
+Keywords: kmeans,lda,machine-learning,stratification,train-test-split
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scikit-learn>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sattp
+
+Cluster-stratified train/test splitting on an LDA-reduced feature space (S-ATTP).
+
+Instead of stratifying on the class label alone, `sattp` also stratifies on *where a row sits in
+feature space*, so the test set covers the same sub-populations as the train set.
+
+## How it works
+
+1. Reduce the features with **LDA**, using the fewest components that reach 85% of the explained
+   variance (configurable).
+2. For each candidate cluster count, run **K-Means** once on the LDA components and reuse those
+   clusters across candidate train fractions (`MiniBatchKMeans` above 50,000 rows).
+3. Build strata from `class × cluster` and do a stratified split. Strata with a single member
+   can't be split, so those rows always go to the train set.
+4. Score a classifier on every `(train fraction, n_clusters)` pair and return the split with the
+   best test score.
+
+## Install
+
+```bash
+pip install i-attp
+```
+
+Or install directly from GitHub:
+
+```bash
+pip install git+https://github.com/Jabualani/ATTP.git
+```
+
+For development:
+
+```bash
+git clone https://github.com/Jabualani/ATTP.git
+cd ATTP
+pip install -e ".[dev]"
+pytest
+```
+
+## Usage
+
+```python
+from attp import sattp_split
+
+result = sattp_split(
+    X, y,
+    splits=[0.7, 0.75, 0.8],   # candidate train fractions
+    min_clusters=2,
+    max_clusters=10,
+)
+
+X_train, y_train, X_test, y_test = result      # unpacks like a 4-tuple
+print(result.best_split, result.best_n_clusters, result.n_lda_components)
+print(result.metrics.head())                    # every candidate, best first
+```
+
+Row labels of the original `X`/`y` are preserved in the outputs.
+
+Useful options: `model=` (any scikit-learn classifier used for scoring; defaults to LDA),
+`scoring=` (custom `(fitted_model, X, y) -> float`), `variance_threshold=`, `random_state=`,
+`verbose=True`. Set `DR_Comps_Min=` and `DR_Comps_Max=` to choose the LDA component range.
+
+### Original function signature
+
+`S_ATTP` keeps the original call signature for existing code:
+
+```python
+from attp import S_ATTP
+
+X_tr, y_tr, X_te, y_te = S_ATTP(
+    X_df, y_df, "target_col", [0.7, 0.8], 2, 10, 1, 3, None, "frames", False, False
+)
+```
+
+`return_type="indices"` returns `(train_index, test_index)`, and
+`return_split_metadata=True` appends the metrics DataFrame. If no valid split exists it returns
+`None`s, like the original.
+
+## Caveats
+
+- LDA is fitted on the **whole** dataset (using all labels) before splitting, and the winning
+  split is chosen by its **test** score. Both make the reported test score optimistic. Treat it as
+  a way to build a representative split, not as an unbiased performance estimate.
+- Features must be numeric with no missing values.
+
+## License
+
+MIT

i_attp-0.1.0/README.md

@@ -0,0 +1,88 @@
+# sattp
+
+Cluster-stratified train/test splitting on an LDA-reduced feature space (S-ATTP).
+
+Instead of stratifying on the class label alone, `sattp` also stratifies on *where a row sits in
+feature space*, so the test set covers the same sub-populations as the train set.
+
+## How it works
+
+1. Reduce the features with **LDA**, using the fewest components that reach 85% of the explained
+   variance (configurable).
+2. For each candidate cluster count, run **K-Means** once on the LDA components and reuse those
+   clusters across candidate train fractions (`MiniBatchKMeans` above 50,000 rows).
+3. Build strata from `class × cluster` and do a stratified split. Strata with a single member
+   can't be split, so those rows always go to the train set.
+4. Score a classifier on every `(train fraction, n_clusters)` pair and return the split with the
+   best test score.
+
+## Install
+
+```bash
+pip install i-attp
+```
+
+Or install directly from GitHub:
+
+```bash
+pip install git+https://github.com/Jabualani/ATTP.git
+```
+
+For development:
+
+```bash
+git clone https://github.com/Jabualani/ATTP.git
+cd ATTP
+pip install -e ".[dev]"
+pytest
+```
+
+## Usage
+
+```python
+from attp import sattp_split
+
+result = sattp_split(
+    X, y,
+    splits=[0.7, 0.75, 0.8],   # candidate train fractions
+    min_clusters=2,
+    max_clusters=10,
+)
+
+X_train, y_train, X_test, y_test = result      # unpacks like a 4-tuple
+print(result.best_split, result.best_n_clusters, result.n_lda_components)
+print(result.metrics.head())                    # every candidate, best first
+```
+
+Row labels of the original `X`/`y` are preserved in the outputs.
+
+Useful options: `model=` (any scikit-learn classifier used for scoring; defaults to LDA),
+`scoring=` (custom `(fitted_model, X, y) -> float`), `variance_threshold=`, `random_state=`,
+`verbose=True`. Set `DR_Comps_Min=` and `DR_Comps_Max=` to choose the LDA component range.
+
+### Original function signature
+
+`S_ATTP` keeps the original call signature for existing code:
+
+```python
+from attp import S_ATTP
+
+X_tr, y_tr, X_te, y_te = S_ATTP(
+    X_df, y_df, "target_col", [0.7, 0.8], 2, 10, 1, 3, None, "frames", False, False
+)
+```
+
+`return_type="indices"` returns `(train_index, test_index)`, and
+`return_split_metadata=True` appends the metrics DataFrame. If no valid split exists it returns
+`None`s, like the original.
+
+## Caveats
+
+- LDA is fitted on the **whole** dataset (using all labels) before splitting, and the winning
+  split is chosen by its **test** score. Both make the reported test score optimistic. Treat it as
+  a way to build a representative split, not as an unbiased performance estimate.
+- Features must be numeric with no missing values.
+
+## License
+
+MIT

i_attp-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "i-attp"
+version = "0.1.0"
+description = "S-ATTP: cluster-stratified train/test splitting on an LDA-reduced feature space."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Jabulani Monchwe", email ="MonchweJ.25@gmail.com" }]
+keywords = ["machine-learning", "train-test-split", "stratification", "lda", "kmeans"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+dependencies = [
+    "numpy>=1.23",
+    "pandas>=1.5",
+    "scikit-learn>=1.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "ruff>=0.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/Jabualani/ATTP"
+Repository = "https://github.com/Jabualani/ATTP"
+Issues = "https://github.com/Jabualani/ATTP/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/attp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

i_attp-0.1.0/sample.py

@@ -0,0 +1,15 @@
+from sklearn.datasets import load_iris
+from attp import sattp_split
+
+data = load_iris(as_frame=True)
+result = sattp_split(
+    data.data,
+    data.target,
+    splits=[0.7],
+    min_clusters=2,
+    max_clusters=4,
+)
+
+x_train, y_train, x_test, y_test = result
+print(x_train.shape, x_test.shape, y_train.shape, y_test.shape)
+print("test score:", result.test_score)

i_attp-0.1.0/src/attp/__init__.py

@@ -0,0 +1,3 @@
+from ._split import S_ATTP, NoValidSplitError, SplitResult, sattp_split
+
+__all__ = ["NoValidSplitError", "SplitResult", "S_ATTP", "sattp_split"]

i_attp-0.1.0/src/attp/_split.py

@@ -0,0 +1,326 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Iterator, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from sklearn.base import ClassifierMixin, clone
+from sklearn.cluster import KMeans, MiniBatchKMeans
+from sklearn.discriminant_analysis import LinearDiscriminantAnalysis
+from sklearn.model_selection import train_test_split
+
+_LOGGER = logging.getLogger(__name__)
+ScoringFunction = Callable[[Any, pd.DataFrame, pd.Series], float]
+
+
+class NoValidSplitError(ValueError):
+    """Raised when no candidate split can be evaluated."""
+
+
+@dataclass(frozen=True)
+class SplitResult:
+    """The selected train/test data and scores for an S-ATTP split."""
+
+    X_train: pd.DataFrame
+    y_train: pd.Series
+    X_test: pd.DataFrame
+    y_test: pd.Series
+    best_split: float
+    best_n_clusters: int
+    n_lda_components: int
+    train_score: float
+    test_score: float
+    metrics: pd.DataFrame
+    train_indices: pd.Index
+    test_indices: pd.Index
+
+    def __iter__(self) -> Iterator[pd.DataFrame | pd.Series]:
+        yield self.X_train
+        yield self.y_train
+        yield self.X_test
+        yield self.y_test
+
+    def __len__(self) -> int:
+        return 4
+
+    def __getitem__(self, index: int | slice) -> Any:
+        return (self.X_train, self.y_train, self.X_test, self.y_test)[index]
+
+
+def _as_features(X: pd.DataFrame | np.ndarray) -> pd.DataFrame:
+    if isinstance(X, pd.DataFrame):
+        features = X.copy()
+    else:
+        array = np.asarray(X)
+        if array.ndim != 2:
+            raise ValueError("X must be a two-dimensional array or DataFrame.")
+        features = pd.DataFrame(array)
+
+    if features.empty or features.shape[1] == 0:
+        raise ValueError("X must contain at least one row and one feature.")
+    try:
+        values = features.to_numpy(dtype=float)
+    except (TypeError, ValueError) as exc:
+        raise ValueError("X must contain only numeric feature values.") from exc
+    if not np.isfinite(values).all():
+        raise ValueError("X must not contain missing or infinite values.")
+    return features
+
+
+def _as_target(
+    y: pd.Series | pd.DataFrame | Sequence[Any] | np.ndarray,
+    index: pd.Index,
+) -> pd.Series:
+    if isinstance(y, pd.DataFrame):
+        if y.shape[1] != 1:
+            raise ValueError("y must be a Series or a DataFrame with exactly one column.")
+        target = y.iloc[:, 0].copy()
+    elif isinstance(y, pd.Series):
+        target = y.copy()
+    else:
+        target = pd.Series(y)
+
+    if len(target) != len(index):
+        raise ValueError("X and y must contain the same number of rows.")
+    target.index = index
+    if target.isna().any():
+        raise ValueError("y must not contain missing values.")
+    if target.nunique() < 2:
+        raise ValueError("y must contain at least two classes.")
+    return target
+
+
+def _fit_lda(
+    X: pd.DataFrame,
+    y: pd.Series,
+    min_components: int,
+    max_components: int,
+    variance_threshold: float,
+) -> tuple[LinearDiscriminantAnalysis, int]:
+    max_possible = min(X.shape[1], y.nunique() - 1)
+    if max_possible < 1:
+        raise ValueError("LDA requires at least two target classes and one feature.")
+
+    first = max(1, min(min_components, max_possible))
+    last = min(max_components, max_possible)
+    if first > last:
+        first = last
+
+    selected: LinearDiscriminantAnalysis | None = None
+    selected_components = 0
+    for n_components in range(first, last + 1):
+        candidate = LinearDiscriminantAnalysis(n_components=n_components)
+        candidate.fit(X, y)
+        selected = candidate
+        selected_components = n_components
+        if candidate.explained_variance_ratio_.sum() >= variance_threshold:
+            break
+
+    if selected is None:
+        raise ValueError("No valid LDA component count is available.")
+    return selected, selected_components
+
+
+def sattp_split(
+    X: pd.DataFrame | np.ndarray,
+    y: pd.Series | pd.DataFrame | Sequence[Any] | np.ndarray,
+    *,
+    splits: Sequence[float] = (0.7, 0.8),
+    min_clusters: int = 2,
+    max_clusters: int = 10,
+    DR_Comps_Min: int = 1,
+    DR_Comps_Max: int = 3,
+    model: ClassifierMixin | None = None,
+    scoring: ScoringFunction | None = None,
+    variance_threshold: float = 0.85,
+    random_state: int | None = 0,
+    verbose: bool = False,
+) -> SplitResult:
+    """Find a high-scoring cluster-stratified train/test split.
+
+    LDA and clustering are fitted on the full input before splitting, so the
+    returned score is useful for selecting a representative split, not for
+    unbiased model evaluation.
+    """
+    features = _as_features(X)
+    target = _as_target(y, features.index)
+
+    if len(splits) == 0:
+        raise ValueError("splits must contain at least one train fraction.")
+    if any(not 0.0 < split < 1.0 for split in splits):
+        raise ValueError("Each split must be a train fraction strictly between 0 and 1.")
+    if min_clusters < 1 or max_clusters < min_clusters:
+        raise ValueError("Cluster bounds must satisfy 1 <= min_clusters <= max_clusters.")
+    if max_clusters > len(features):
+        raise ValueError("max_clusters cannot exceed the number of input rows.")
+    if DR_Comps_Min < 1 or DR_Comps_Max < DR_Comps_Min:
+        raise ValueError(
+            "LDA component bounds must satisfy "
+            "1 <= DR_Comps_Min <= DR_Comps_Max."
+        )
+    if not 0.0 <= variance_threshold <= 1.0:
+        raise ValueError("variance_threshold must be between 0 and 1.")
+
+    lda, n_components = _fit_lda(
+        features,
+        target,
+        DR_Comps_Min,
+        DR_Comps_Max,
+        variance_threshold,
+    )
+    reduced = lda.transform(features)
+    candidate_model = model if model is not None else LinearDiscriminantAnalysis()
+    n_samples = len(features)
+    use_minibatch = n_samples > 50_000
+    records: list[dict[str, Any]] = []
+
+    for n_clusters in range(min_clusters, max_clusters + 1):
+        if use_minibatch:
+            clusterer = MiniBatchKMeans(
+                n_clusters=n_clusters,
+                random_state=random_state,
+                batch_size=4096,
+                n_init="auto",
+            )
+        else:
+            clusterer = KMeans(
+                n_clusters=n_clusters,
+                random_state=random_state,
+                n_init="auto",
+            )
+        cluster_labels = clusterer.fit_predict(reduced)
+        strata = pd.Series(
+            target.astype(str).to_numpy() + "\x1f" + cluster_labels.astype(str)
+        )
+        counts = strata.value_counts()
+        singleton_positions = np.flatnonzero(strata.map(counts).to_numpy() == 1)
+        valid_positions = np.flatnonzero(strata.map(counts).to_numpy() > 1)
+        valid_strata = strata.iloc[valid_positions]
+        n_valid = len(valid_positions)
+        n_groups = valid_strata.nunique()
+
+        for split in splits:
+            n_train = int(np.floor(n_valid * split))
+            n_test = n_valid - n_train
+            if n_groups == 0 or n_train < n_groups or n_test < n_groups:
+                continue
+
+            train_valid, test_positions = train_test_split(
+                valid_positions,
+                train_size=split,
+                random_state=random_state,
+                stratify=valid_strata,
+            )
+            train_positions = np.concatenate((train_valid, singleton_positions))
+            X_train = features.iloc[train_positions]
+            y_train = target.iloc[train_positions]
+            X_test = features.iloc[test_positions]
+            y_test = target.iloc[test_positions]
+
+            fitted_model = clone(candidate_model)
+            fitted_model.fit(X_train, y_train)
+            if scoring is None:
+                train_score = float(fitted_model.score(X_train, y_train))
+                test_score = float(fitted_model.score(X_test, y_test))
+            else:
+                train_score = float(scoring(fitted_model, X_train, y_train))
+                test_score = float(scoring(fitted_model, X_test, y_test))
+            if not np.isfinite(train_score) or not np.isfinite(test_score):
+                raise ValueError("The scoring function must return finite numeric scores.")
+
+            records.append(
+                {
+                    "Split": split,
+                    "n_clusters": n_clusters,
+                    "train_score": round(train_score, 3),
+                    "test_score": round(test_score, 3),
+                    "train_indices": features.index.take(train_positions),
+                    "test_indices": features.index.take(test_positions),
+                    "_train_positions": train_positions,
+                    "_test_positions": test_positions,
+                }
+            )
+
+    if not records:
+        raise NoValidSplitError(
+            "No valid candidate split was found. Try different train fractions or cluster bounds."
+        )
+
+    metrics = pd.DataFrame.from_records(records).sort_values(
+        ["test_score", "n_clusters"], ascending=[False, False], ignore_index=True
+    )
+    best = metrics.iloc[0]
+    train_indices = best["train_indices"]
+    test_indices = best["test_indices"]
+    train_positions = best["_train_positions"]
+    test_positions = best["_test_positions"]
+    metrics = metrics.drop(columns=["_train_positions", "_test_positions"])
+
+    result = SplitResult(
+        X_train=features.iloc[train_positions].copy(),
+        y_train=target.iloc[train_positions].copy(),
+        X_test=features.iloc[test_positions].copy(),
+        y_test=target.iloc[test_positions].copy(),
+        best_split=float(best["Split"]),
+        best_n_clusters=int(best["n_clusters"]),
+        n_lda_components=n_components,
+        train_score=float(best["train_score"]),
+        test_score=float(best["test_score"]),
+        metrics=metrics,
+        train_indices=train_indices.copy(),
+        test_indices=test_indices.copy(),
+    )
+    if verbose:
+        _LOGGER.info(
+            "Selected split %.3f with %d clusters (test score %.3f).",
+            result.best_split,
+            result.best_n_clusters,
+            result.test_score,
+        )
+    return result
+
+
+def S_ATTP(
+    Input_X_df: pd.DataFrame,
+    Input_y_df: pd.DataFrame,
+    Target_Var_: str,
+    Splits: Sequence[float],
+    Min_clusters: int,
+    Max_Clusters: int,
+    DR_Comps_Min: int,
+    DR_Comps_Max: int,
+    accuracy_model: ClassifierMixin | None,
+    return_type: str,
+    return_split_metadata: bool,
+    verbose: bool,
+) -> tuple[Any, ...]:
+    """Compatibility wrapper for the original S_ATTP function signature."""
+    if Target_Var_ not in Input_y_df.columns:
+        raise ValueError(f"Target_Var_ {Target_Var_!r} is not a column in Input_y_df.")
+    if return_type not in {"frames", "indices"}:
+        raise ValueError("return_type must be either 'frames' or 'indices'.")
+
+    try:
+        result = sattp_split(
+            Input_X_df,
+            Input_y_df[Target_Var_],
+            splits=Splits,
+            min_clusters=Min_clusters,
+            max_clusters=Max_Clusters,
+            DR_Comps_Min=DR_Comps_Min,
+            DR_Comps_Max=DR_Comps_Max,
+            model=accuracy_model,
+            verbose=verbose,
+        )
+    except NoValidSplitError:
+        output = (None, None) if return_type == "indices" else (None, None, None, None)
+        return output + (None,) if return_split_metadata else output
+
+    if return_type == "indices":
+        output = (result.train_indices, result.test_indices)
+    else:
+        output = (result.X_train, result.y_train, result.X_test, result.y_test)
+    return output + (result.metrics,) if return_split_metadata else output

i_attp-0.1.0/tests/test_split.py

@@ -0,0 +1,103 @@
+import numpy as np
+import pandas as pd
+import pytest
+from sklearn.cluster import KMeans
+from sklearn.linear_model import LogisticRegression
+
+from attp import S_ATTP, NoValidSplitError, sattp_split
+
+
+@pytest.fixture
+def classification_data():
+    rng = np.random.default_rng(12)
+    labels = np.repeat(["a", "b", "c"], 40)
+    features = rng.normal(size=(len(labels), 5)) + np.repeat(
+        np.array([[-2, 0, 0, 0, 0], [0, 2, 0, 0, 0], [2, 0, 0, 0, 0]]),
+        40,
+        axis=0,
+    )
+    index = pd.Index([f"sample-{i}" for i in range(len(labels))])
+    return pd.DataFrame(features, columns=list("abcde"), index=index), pd.Series(
+        labels, index=index, name="label"
+    )
+
+
+def test_split_result_preserves_indices_and_unpacks(classification_data):
+    X, y = classification_data
+    result = sattp_split(
+        X,
+        y,
+        splits=[0.7],
+        min_clusters=2,
+        max_clusters=2,
+        DR_Comps_Min=1,
+        DR_Comps_Max=3,
+        model=LogisticRegression(max_iter=500),
+        random_state=4,
+    )
+    X_train, y_train, X_test, y_test = result
+
+    assert X_train.index.equals(y_train.index)
+    assert X_test.index.equals(y_test.index)
+    assert set(result.train_indices).isdisjoint(result.test_indices)
+    assert set(result.train_indices) | set(result.test_indices) == set(X.index)
+    assert result.best_split == 0.7
+    assert len(result.metrics) == 1
+
+
+def test_clusters_are_fitted_once_for_each_cluster_count(classification_data, monkeypatch):
+    X, y = classification_data
+    fitted_cluster_counts = []
+    original_fit_predict = KMeans.fit_predict
+
+    def count_fit_predict(self, *args, **kwargs):
+        fitted_cluster_counts.append(self.n_clusters)
+        return original_fit_predict(self, *args, **kwargs)
+
+    monkeypatch.setattr(KMeans, "fit_predict", count_fit_predict)
+    result = sattp_split(
+        X,
+        y,
+        splits=[0.65, 0.75],
+        min_clusters=2,
+        max_clusters=3,
+    )
+
+    assert fitted_cluster_counts == [2, 3]
+    assert len(result.metrics) == 4
+
+
+def test_legacy_wrapper_returns_frames_indices_and_metadata(classification_data):
+    X, y = classification_data
+    target = y.to_frame()
+    target.index = target.index[::-1]
+    target = target.reset_index(drop=True)
+    X = X.reset_index(drop=True)
+
+    frames = S_ATTP(X, target, "label", [0.7], 2, 2, 1, 2, None, "frames", False, False)
+    indices = S_ATTP(X, target, "label", [0.7], 2, 2, 1, 2, None, "indices", True, False)
+
+    assert len(frames) == 4
+    assert len(indices) == 3
+    assert isinstance(indices[2], pd.DataFrame)
+
+
+@pytest.mark.parametrize(
+    ("X", "y", "kwargs", "message"),
+    [
+        ([1, 2], [0, 1], {}, "two-dimensional"),
+        ([[1, np.nan], [2, 3]], [0, 1], {}, "missing or infinite"),
+        ([[1], [2]], [0], {}, "same number of rows"),
+        ([[1], [2]], [1, 1], {}, "at least two classes"),
+        ([[1], [2]], [0, 1], {"splits": [1.0]}, "strictly between"),
+    ],
+)
+def test_invalid_input_raises_clear_error(X, y, kwargs, message):
+    with pytest.raises(ValueError, match=message):
+        sattp_split(X, y, **kwargs)
+
+
+def test_no_candidate_split_raises_specific_error(classification_data):
+    X, y = classification_data
+    with pytest.raises(NoValidSplitError, match="No valid candidate"):
+        sattp_split(X, y, splits=[0.99], min_clusters=2, max_clusters=2)