generate-test-data-for-wknn 0.0.1__tar.gz

generate_test_data_for_wknn-0.0.1/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.3
+Name: generate-test-data-for-wknn
+Version: 0.0.1
+Summary: Test-data generator for validating the weighted k-NN (wkNN) method.
+Keywords: knn,weighted-knn,wknn,machine-learning,test-data
+Author: Ferubko Andrey, Kazakov Oleg
+Author-email: Ferubko Andrey <andrey.ferubko@petsplace.ru>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: numpy>=1.24
+Maintainer: Ferubko Andrey, Kazakov Oleg
+Maintainer-email: Ferubko Andrey <andrey.ferubko@petsplace.ru>
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/89605502155/generate-test-data-for-wknn
+Project-URL: Repository, https://github.com/89605502155/generate-test-data-for-wknn
+Project-URL: Issues, https://github.com/89605502155/generate-test-data-for-wknn/issues
+Description-Content-Type: text/markdown
+
+# generate-test-data-for-wknn
+
+[![PyPI](https://img.shields.io/pypi/v/generate-test-data-for-wknn.svg)](https://pypi.org/project/generate-test-data-for-wknn/)
+[![Python](https://img.shields.io/pypi/pyversions/generate-test-data-for-wknn.svg)](https://pypi.org/project/generate-test-data-for-wknn/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**EN** — Synthetic test-data generator for validating the **weighted k-NN (wkNN)** method.
+**RU** — Генератор синтетических тестовых данных для проверки метода **взвешенного k-NN (wkNN)**.
+
+*Authors / Авторы:* Ferubko Andrey, Kazakov Oleg
+*Organization / Организация:* Bryansk State Technological University of Engineering /
+Брянский государственный инженерно-технологический университет.
+
+---
+
+## Installation / Установка
+
+```bash
+pip install generate-test-data-for-wknn
+# or with uv:
+uv add generate-test-data-for-wknn
+```
+
+---
+
+## English documentation
+
+The library exposes a single public function, `generate`, which builds a
+labelled dataset `(x, y)` for testing weighted k-NN.
+
+Each class is given a random **anchor** point inside the cube
+`[min_coord, max_abs_coord]^dim`. Every other random point is assigned to the
+class whose **total weight** is largest. Weights are functions of the
+per-coordinate absolute differences `x_i = |p_i - anchor_i|` and must
+**decrease** as distance grows (otherwise a `ValueError` is raised).
+
+### Weight functions and parameter layout
+
+| `weight_type`  | Formula | `params` length | Constraint |
+|----------------|---------|-----------------|------------|
+| `"constant"`   | `w = 1` | ignored | always valid (reduces to plain kNN) |
+| `"linear"`     | `w = max(Σ aᵢ·xᵢ + f, 0)` | `dim + 1` → `[a₁,…,a_d, f]` | all `aᵢ ≤ 0` |
+| `"inverse"`    | `w = Σ aᵢ / xᵢ^bᵢ + f` | `2·dim + 1` → `[a₁,b₁,…,a_d,b_d, f]` | `aᵢ ≥ 0`, `bᵢ > 0` |
+| `"exponential"`| `w = Σ aᵢ·exp(−bᵢ·xᵢ) + f` | `2·dim + 1` → `[a₁,b₁,…,a_d,b_d, f]` | `aᵢ ≥ 0`, `bᵢ > 0` |
+
+> Example (from the spec): for `dim=2`, `linear` with `params=[-1, -8, 9]`
+> corresponds to `w = max(-1·x₁ + -8·x₂ + 9, 0)`.
+
+### Parameters
+
+| Name | Default | Meaning |
+|------|---------|---------|
+| `n_classes` | `2` | number of classes (binary by default) |
+| `dim` | `2` | dimensionality of each point |
+| `n_samples` | `30` | number of objects in the dataset |
+| `weight_type` | `"inverse"` | one of the four weighting schemes |
+| `params` | `None` | coefficient array (see table) |
+| `max_abs_coord` | `1e4` | upper coordinate bound (abs value cap) |
+| `min_coord` | `-1e4` | lower coordinate bound (use `0` for e.g. time series) |
+| `outlier_ratio` | `0.0` | fraction of **borderline** labels to flip, must be in `[0, 1]` |
+| `random_state` | `None` | RNG seed |
+
+**Returns:** `(x, y)` — `x` is `float64` of shape `(m, dim)`, `y` is `int64` of
+shape `(m,)`, where `m ≤ n_samples` (tie points are removed).
+
+### Behavioural guarantees
+
+- **Stratification:** classes are balanced (counts differ by at most 1).
+- **Ties dropped:** points where the top-2 class weights are equal are removed.
+- **Outliers:** the requested fraction of the *most borderline* points is flipped
+  to the runner-up class, spread evenly across the cube (not from a single plane).
+- **Monotonicity guard:** non-decreasing weight parameters raise `ValueError`.
+
+### Example
+
+```python
+import numpy as np
+from generate_test_data_for_wknn import generate
+
+# Binary, inverse-distance weights, 2-D, reproducible
+x, y = generate(
+    n_classes=2,
+    dim=2,
+    n_samples=50,
+    weight_type="inverse",
+    params=np.array([2.0, 1.0, 3.0, 1.5, 0.1]),  # a1,b1,a2,b2,f
+    max_abs_coord=100.0,
+    min_coord=0.0,          # non-negative coords (e.g. time series)
+    outlier_ratio=0.1,
+    random_state=42,
+)
+print(x.shape, y.shape, np.bincount(y))
+```
+
+---
+
+## Документация на русском
+
+Библиотека предоставляет одну публичную функцию `generate`, которая строит
+размеченный набор данных `(x, y)` для проверки взвешенного k-NN.
+
+Для каждого класса создаётся случайная **опорная точка** внутри куба
+`[min_coord, max_abs_coord]^dim`. Каждой другой случайной точке присваивается
+класс с наибольшим **суммарным весом**. Веса зависят от модулей разностей
+координат `x_i = |p_i − anchor_i|` и **должны убывать** с ростом расстояния
+(иначе возбуждается `ValueError`).
+
+### Весовые функции и формат параметров
+
+| `weight_type`  | Формула | Длина `params` | Ограничение |
+|----------------|---------|----------------|-------------|
+| `"constant"`   | `w = 1` | не используется | всегда допустимо (обычный kNN) |
+| `"linear"`     | `w = max(Σ aᵢ·xᵢ + f, 0)` | `dim + 1` | все `aᵢ ≤ 0` |
+| `"inverse"`    | `w = Σ aᵢ / xᵢ^bᵢ + f` | `2·dim + 1` | `aᵢ ≥ 0`, `bᵢ > 0` |
+| `"exponential"`| `w = Σ aᵢ·exp(−bᵢ·xᵢ) + f` | `2·dim + 1` | `aᵢ ≥ 0`, `bᵢ > 0` |
+
+### Параметры
+
+| Имя | По умолчанию | Смысл |
+|-----|--------------|-------|
+| `n_classes` | `2` | число классов (по умолчанию бинарная задача) |
+| `dim` | `2` | размерность точки |
+| `n_samples` | `30` | число объектов |
+| `weight_type` | `"inverse"` | схема взвешивания |
+| `params` | `None` | массив коэффициентов (см. таблицу) |
+| `max_abs_coord` | `1e4` | верхняя граница координат по модулю |
+| `min_coord` | `-1e4` | нижняя граница (для временных рядов задайте `0`) |
+| `outlier_ratio` | `0.0` | доля переставляемых **пограничных** меток, из `[0, 1]` |
+| `random_state` | `None` | зерно генератора |
+
+**Возвращает:** `(x, y)` — массивы NumPy; `m ≤ n_samples` (точки с ничьей удаляются).
+
+### Гарантии поведения
+
+- **Стратификация:** классы сбалансированы (разница ≤ 1 объект).
+- **Удаление ничьих:** точки с равными весами двух лучших классов удаляются.
+- **Выбросы:** заданная доля наиболее **пограничных** точек переставляется в
+  класс-«второе место», равномерно по всему кубу (а не из одной плоскости).
+- **Проверка монотонности:** невозрастающие/неубывающие параметры → `ValueError`.
+
+### Пример
+
+```python
+import numpy as np
+from generate_test_data_for_wknn import generate
+
+x, y = generate(
+    n_classes=3,
+    dim=2,
+    n_samples=60,
+    weight_type="exponential",
+    params=np.array([5.0, 0.01, 4.0, 0.02, 0.0]),  # a1,b1,a2,b2,f
+    outlier_ratio=0.15,
+    random_state=7,
+)
+print(x.shape, y.shape, np.bincount(y))
+```
+
+---
+
+## License / Лицензия
+
+MIT © Ferubko Andrey, Kazakov Oleg — Bryansk State Technological University of Engineering.

generate_test_data_for_wknn-0.0.1/README.md

@@ -0,0 +1,163 @@
+# generate-test-data-for-wknn
+
+[![PyPI](https://img.shields.io/pypi/v/generate-test-data-for-wknn.svg)](https://pypi.org/project/generate-test-data-for-wknn/)
+[![Python](https://img.shields.io/pypi/pyversions/generate-test-data-for-wknn.svg)](https://pypi.org/project/generate-test-data-for-wknn/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**EN** — Synthetic test-data generator for validating the **weighted k-NN (wkNN)** method.
+**RU** — Генератор синтетических тестовых данных для проверки метода **взвешенного k-NN (wkNN)**.
+
+*Authors / Авторы:* Ferubko Andrey, Kazakov Oleg
+*Organization / Организация:* Bryansk State Technological University of Engineering /
+Брянский государственный инженерно-технологический университет.
+
+---
+
+## Installation / Установка
+
+```bash
+pip install generate-test-data-for-wknn
+# or with uv:
+uv add generate-test-data-for-wknn
+```
+
+---
+
+## English documentation
+
+The library exposes a single public function, `generate`, which builds a
+labelled dataset `(x, y)` for testing weighted k-NN.
+
+Each class is given a random **anchor** point inside the cube
+`[min_coord, max_abs_coord]^dim`. Every other random point is assigned to the
+class whose **total weight** is largest. Weights are functions of the
+per-coordinate absolute differences `x_i = |p_i - anchor_i|` and must
+**decrease** as distance grows (otherwise a `ValueError` is raised).
+
+### Weight functions and parameter layout
+
+| `weight_type`  | Formula | `params` length | Constraint |
+|----------------|---------|-----------------|------------|
+| `"constant"`   | `w = 1` | ignored | always valid (reduces to plain kNN) |
+| `"linear"`     | `w = max(Σ aᵢ·xᵢ + f, 0)` | `dim + 1` → `[a₁,…,a_d, f]` | all `aᵢ ≤ 0` |
+| `"inverse"`    | `w = Σ aᵢ / xᵢ^bᵢ + f` | `2·dim + 1` → `[a₁,b₁,…,a_d,b_d, f]` | `aᵢ ≥ 0`, `bᵢ > 0` |
+| `"exponential"`| `w = Σ aᵢ·exp(−bᵢ·xᵢ) + f` | `2·dim + 1` → `[a₁,b₁,…,a_d,b_d, f]` | `aᵢ ≥ 0`, `bᵢ > 0` |
+
+> Example (from the spec): for `dim=2`, `linear` with `params=[-1, -8, 9]`
+> corresponds to `w = max(-1·x₁ + -8·x₂ + 9, 0)`.
+
+### Parameters
+
+| Name | Default | Meaning |
+|------|---------|---------|
+| `n_classes` | `2` | number of classes (binary by default) |
+| `dim` | `2` | dimensionality of each point |
+| `n_samples` | `30` | number of objects in the dataset |
+| `weight_type` | `"inverse"` | one of the four weighting schemes |
+| `params` | `None` | coefficient array (see table) |
+| `max_abs_coord` | `1e4` | upper coordinate bound (abs value cap) |
+| `min_coord` | `-1e4` | lower coordinate bound (use `0` for e.g. time series) |
+| `outlier_ratio` | `0.0` | fraction of **borderline** labels to flip, must be in `[0, 1]` |
+| `random_state` | `None` | RNG seed |
+
+**Returns:** `(x, y)` — `x` is `float64` of shape `(m, dim)`, `y` is `int64` of
+shape `(m,)`, where `m ≤ n_samples` (tie points are removed).
+
+### Behavioural guarantees
+
+- **Stratification:** classes are balanced (counts differ by at most 1).
+- **Ties dropped:** points where the top-2 class weights are equal are removed.
+- **Outliers:** the requested fraction of the *most borderline* points is flipped
+  to the runner-up class, spread evenly across the cube (not from a single plane).
+- **Monotonicity guard:** non-decreasing weight parameters raise `ValueError`.
+
+### Example
+
+```python
+import numpy as np
+from generate_test_data_for_wknn import generate
+
+# Binary, inverse-distance weights, 2-D, reproducible
+x, y = generate(
+    n_classes=2,
+    dim=2,
+    n_samples=50,
+    weight_type="inverse",
+    params=np.array([2.0, 1.0, 3.0, 1.5, 0.1]),  # a1,b1,a2,b2,f
+    max_abs_coord=100.0,
+    min_coord=0.0,          # non-negative coords (e.g. time series)
+    outlier_ratio=0.1,
+    random_state=42,
+)
+print(x.shape, y.shape, np.bincount(y))
+```
+
+---
+
+## Документация на русском
+
+Библиотека предоставляет одну публичную функцию `generate`, которая строит
+размеченный набор данных `(x, y)` для проверки взвешенного k-NN.
+
+Для каждого класса создаётся случайная **опорная точка** внутри куба
+`[min_coord, max_abs_coord]^dim`. Каждой другой случайной точке присваивается
+класс с наибольшим **суммарным весом**. Веса зависят от модулей разностей
+координат `x_i = |p_i − anchor_i|` и **должны убывать** с ростом расстояния
+(иначе возбуждается `ValueError`).
+
+### Весовые функции и формат параметров
+
+| `weight_type`  | Формула | Длина `params` | Ограничение |
+|----------------|---------|----------------|-------------|
+| `"constant"`   | `w = 1` | не используется | всегда допустимо (обычный kNN) |
+| `"linear"`     | `w = max(Σ aᵢ·xᵢ + f, 0)` | `dim + 1` | все `aᵢ ≤ 0` |
+| `"inverse"`    | `w = Σ aᵢ / xᵢ^bᵢ + f` | `2·dim + 1` | `aᵢ ≥ 0`, `bᵢ > 0` |
+| `"exponential"`| `w = Σ aᵢ·exp(−bᵢ·xᵢ) + f` | `2·dim + 1` | `aᵢ ≥ 0`, `bᵢ > 0` |
+
+### Параметры
+
+| Имя | По умолчанию | Смысл |
+|-----|--------------|-------|
+| `n_classes` | `2` | число классов (по умолчанию бинарная задача) |
+| `dim` | `2` | размерность точки |
+| `n_samples` | `30` | число объектов |
+| `weight_type` | `"inverse"` | схема взвешивания |
+| `params` | `None` | массив коэффициентов (см. таблицу) |
+| `max_abs_coord` | `1e4` | верхняя граница координат по модулю |
+| `min_coord` | `-1e4` | нижняя граница (для временных рядов задайте `0`) |
+| `outlier_ratio` | `0.0` | доля переставляемых **пограничных** меток, из `[0, 1]` |
+| `random_state` | `None` | зерно генератора |
+
+**Возвращает:** `(x, y)` — массивы NumPy; `m ≤ n_samples` (точки с ничьей удаляются).
+
+### Гарантии поведения
+
+- **Стратификация:** классы сбалансированы (разница ≤ 1 объект).
+- **Удаление ничьих:** точки с равными весами двух лучших классов удаляются.
+- **Выбросы:** заданная доля наиболее **пограничных** точек переставляется в
+  класс-«второе место», равномерно по всему кубу (а не из одной плоскости).
+- **Проверка монотонности:** невозрастающие/неубывающие параметры → `ValueError`.
+
+### Пример
+
+```python
+import numpy as np
+from generate_test_data_for_wknn import generate
+
+x, y = generate(
+    n_classes=3,
+    dim=2,
+    n_samples=60,
+    weight_type="exponential",
+    params=np.array([5.0, 0.01, 4.0, 0.02, 0.0]),  # a1,b1,a2,b2,f
+    outlier_ratio=0.15,
+    random_state=7,
+)
+print(x.shape, y.shape, np.bincount(y))
+```
+
+---
+
+## License / Лицензия
+
+MIT © Ferubko Andrey, Kazakov Oleg — Bryansk State Technological University of Engineering.

generate_test_data_for_wknn-0.0.1/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "generate-test-data-for-wknn"
+version = "0.0.1"
+description = "Test-data generator for validating the weighted k-NN (wkNN) method."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Ferubko Andrey", email = "andrey.ferubko@petsplace.ru" },
+    { name = "Kazakov Oleg" },
+]
+maintainers = [
+    { name = "Ferubko Andrey", email = "andrey.ferubko@petsplace.ru" },
+    { name = "Kazakov Oleg" },
+]
+keywords = ["knn", "weighted-knn", "wknn", "machine-learning", "test-data"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "numpy>=1.24",
+]
+
+[project.urls]
+Homepage = "https://github.com/89605502155/generate-test-data-for-wknn"
+Repository = "https://github.com/89605502155/generate-test-data-for-wknn"
+Issues = "https://github.com/89605502155/generate-test-data-for-wknn/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.9,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/generate_test_data_for_wknn"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]

generate_test_data_for_wknn-0.0.1/src/generate_test_data_for_wknn/__init__.py

@@ -0,0 +1,4 @@
+from ._core import WknnDataGenerator, WeightType, generate
+
+__all__ = ["WknnDataGenerator", "generate", "WeightType"]
+__version__ = "0.0.1"

generate_test_data_for_wknn-0.0.1/src/generate_test_data_for_wknn/_core.py

@@ -0,0 +1,230 @@
+"""Core implementation of the weighted-kNN test-data generator.
+
+Everything lives inside :class:`WknnDataGenerator` — a stateless utility class
+(no ``__init__``): call :meth:`WknnDataGenerator.generate` directly on the class.
+All heavy lifting is delegated to NumPy (vectorised).
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, Literal
+
+import numpy as np
+from numpy.typing import NDArray
+
+WeightType = Literal["constant", "linear", "inverse", "exponential"]
+
+
+class WknnDataGenerator:
+    """Stateless generator of synthetic datasets for testing weighted k-NN.
+
+    The class is never instantiated: use the classmethod directly, e.g.
+    ``x, y = WknnDataGenerator.generate(...)``. The module-level ``generate``
+    alias forwards to this method for convenience.
+    """
+
+    # ---- configuration constants ---------------------------------------
+    _LEN_DIM: ClassVar[frozenset[str]] = frozenset({"linear"})
+    _LEN_2DIM: ClassVar[frozenset[str]] = frozenset({"inverse", "exponential"})
+    _EPS: ClassVar[float] = 1e-9  # guards divisions / powers against zero
+    _MAX_ATTEMPTS: ClassVar[int] = 50
+
+    # ---- private helpers (static: no state needed) ----------------------
+    @staticmethod
+    def _default_params(weight_type: WeightType, dim: int) -> NDArray[np.float64] | None:
+        """Sensible, *decreasing* default coefficients so ``generate()`` works."""
+        if weight_type == "constant":
+            return None
+        if weight_type == "linear":
+            # w = max(sum(-1 * x_i) + 1, 0): decreasing (all slopes <= 0).
+            return np.concatenate([-np.ones(dim), [1.0]])
+        if weight_type in ("inverse", "exponential"):
+            # inverse:     w = sum(1 / x_i^1) + 0   (a=1>=0, b=1>0)
+            # exponential: w = sum(1 * exp(-1*x_i)) (a=1>=0, b=1>0)
+            return np.concatenate([np.tile([1.0, 1.0], dim), [0.0]])
+        raise ValueError(f"unknown weight_type={weight_type!r}.")
+
+    @classmethod
+    def _validate_params(
+        cls,
+        weight_type: WeightType,
+        params: NDArray[np.float64] | None,
+        dim: int,
+    ) -> tuple[NDArray[np.float64], float]:
+        """Validate params, enforce a *decreasing* weight, return (coeffs, bias)."""
+        if weight_type == "constant":
+            return np.zeros(dim, dtype=float), 1.0
+
+        if params is None:
+            params = cls._default_params(weight_type, dim)
+        params = np.asarray(params, dtype=float).ravel()
+
+        if weight_type in cls._LEN_DIM:
+            if params.size != dim + 1:
+                raise ValueError(
+                    f"linear weights need dim+1={dim + 1} params, got {params.size}."
+                )
+            a, f = params[:dim], float(params[dim])
+            if np.any(a > 0):
+                raise ValueError(
+                    "linear weight is non-decreasing: every coefficient a_i must be <= 0."
+                )
+            return a, f
+
+        if weight_type in cls._LEN_2DIM:
+            if params.size != 2 * dim + 1:
+                raise ValueError(
+                    f"{weight_type} weights need 2*dim+1={2 * dim + 1} params, "
+                    f"got {params.size}."
+                )
+            ab, f = params[: 2 * dim].reshape(dim, 2), float(params[2 * dim])
+            a, b = ab[:, 0], ab[:, 1]
+            if np.any(a < 0) or np.any(b <= 0):
+                raise ValueError(
+                    f"{weight_type} weight is non-decreasing: need a_i >= 0 and b_i > 0."
+                )
+            return ab.ravel(), f
+
+        raise ValueError(f"unknown weight_type={weight_type!r}.")
+
+    @classmethod
+    def _weights(
+        cls,
+        dx: NDArray[np.float64],
+        weight_type: WeightType,
+        coeffs: NDArray[np.float64],
+        bias: float,
+    ) -> NDArray[np.float64]:
+        """Vectorised weight for *normalised* |coordinate differences| (..., dim)."""
+        if weight_type == "constant":
+            return np.ones(dx.shape[:-1], dtype=float)
+        if weight_type == "linear":
+            return np.maximum(dx @ coeffs + bias, 0.0)
+
+        ab = coeffs.reshape(-1, 2)
+        a, b = ab[:, 0], ab[:, 1]
+        dxs = np.maximum(dx, cls._EPS)
+        if weight_type == "inverse":
+            return np.sum(a / np.power(dxs, b), axis=-1) + bias
+        return np.sum(a * np.exp(-b * dx), axis=-1) + bias  # exponential
+
+    @classmethod
+    def _assign(
+        cls,
+        x: NDArray[np.float64],
+        anchors: NDArray[np.float64],
+        scale: float,
+        weight_type: WeightType,
+        coeffs: NDArray[np.float64],
+        bias: float,
+    ) -> tuple[NDArray[np.int64], NDArray[np.float64]]:
+        """Return (labels, per-class score matrix); winner is ``argmax`` of score.
+
+        For the *constant* weight (plain kNN) all weights are equal, so the
+        class is decided by the *nearest anchor*: the score is ``-distance``,
+        which yields a proper, non-degenerate decision and meaningful margins.
+        """
+        diff = x[:, None, :] - anchors[None, :, :]  # (n, n_classes, dim)
+        if weight_type == "constant":
+            dist = np.linalg.norm(diff, axis=-1)
+            return np.argmax(-dist, axis=1).astype(np.int64), -dist
+        dx = np.abs(diff) / scale
+        w = cls._weights(dx, weight_type, coeffs, bias)
+        return np.argmax(w, axis=1).astype(np.int64), w
+
+    # ---- public API -----------------------------------------------------
+    @classmethod
+    def generate(
+        cls,
+        n_classes: int = 2,
+        dim: int = 2,
+        n_samples: int = 30,
+        weight_type: WeightType = "inverse",
+        params: NDArray[np.float64] | None = None,
+        max_abs_coord: float = 1e4,
+        min_coord: float = -1e4,
+        outlier_ratio: float = 0.0,
+        *,
+        random_state: int | None = None,
+    ) -> tuple[NDArray[np.float64], NDArray[np.int64]]:
+        """Generate a synthetic dataset for testing weighted k-NN classification.
+
+        See README for the full parameter/weight-function reference. Returns
+        ``(x, y)`` where ``x`` is float64 ``(m, dim)`` and ``y`` is int64
+        ``(m,)``, with ``m <= n_samples`` (tie points are dropped).
+        """
+        # ---- validation --------------------------------------------------
+        if n_classes < 2:
+            raise ValueError("n_classes must be >= 2.")
+        if dim < 1:
+            raise ValueError("dim must be >= 1.")
+        if n_samples < n_classes:
+            raise ValueError("n_samples must be >= n_classes.")
+        if not (min_coord < max_abs_coord):
+            raise ValueError("min_coord must be < max_abs_coord.")
+        if not (0.0 <= outlier_ratio <= 1.0):
+            raise ValueError("outlier_ratio must be within [0, 1].")
+
+        coeffs, bias = cls._validate_params(weight_type, params, dim)
+        rng = np.random.default_rng(random_state)
+        lo, hi = float(min_coord), float(max_abs_coord)
+        # Normalise distances so weights vary meaningfully regardless of cube size.
+        scale = max((hi - lo) / 4.0, cls._EPS)
+
+        per_class = n_samples // n_classes
+        remainder = n_samples - per_class * n_classes
+        takes = [per_class + (1 if c < remainder else 0) for c in range(n_classes)]
+
+        # ---- retry with fresh geometry until every class can be filled ---
+        last_counts: NDArray[np.int64] | None = None
+        for _attempt in range(cls._MAX_ATTEMPTS):
+            anchors = rng.uniform(lo, hi, size=(n_classes, dim))
+            pool = max(n_samples * 40, n_classes * 200)
+            cand = rng.uniform(lo, hi, size=(pool, dim))
+            labels, w = cls._assign(cand, anchors, scale, weight_type, coeffs, bias)
+
+            # Drop ties (top-2 class scores exactly equal).
+            top2 = np.sort(w, axis=1)[:, -2:]
+            keep = top2[:, 1] > top2[:, 0]
+            cand, labels, w = cand[keep], labels[keep], w[keep]
+
+            counts = np.bincount(labels, minlength=n_classes)
+            last_counts = counts
+            if np.all(counts >= np.asarray(takes)):
+                break
+        else:
+            raise ValueError(
+                "could not build a balanced, non-degenerate sample after "
+                f"{cls._MAX_ATTEMPTS} attempts (class counts {last_counts.tolist()}, "
+                f"needed {takes}). The chosen weight/params make one class dominate "
+                "the whole cube; try a different weight_type, params, or random_state."
+            )
+
+        # ---- stratified, balanced selection ------------------------------
+        chosen: list[int] = []
+        for c in range(n_classes):
+            idx_c = np.flatnonzero(labels == c)
+            chosen.extend(rng.choice(idx_c, size=takes[c], replace=False).tolist())
+        chosen = np.asarray(chosen, dtype=np.int64)
+        rng.shuffle(chosen)
+        x, y, w = cand[chosen], labels[chosen], w[chosen]
+
+        # ---- inject outliers on the borderline, spread across the cube ---
+        n_out = int(round(outlier_ratio * x.shape[0]))
+        if n_out > 0:
+            sw = np.sort(w, axis=1)
+            margin = sw[:, -1] - sw[:, -2]  # smaller => more borderline
+            rank = np.empty(x.shape[0], dtype=np.int64)
+            rank[np.argsort(margin)] = np.arange(x.shape[0])
+            picked: list[int] = []
+            for bucket in np.array_split(np.argsort(x[:, 0]), n_out):
+                if bucket.size:
+                    picked.append(int(bucket[np.argmin(rank[bucket])]))
+            for i in picked[:n_out]:
+                y[i] = int(np.argsort(w[i])[-2])  # flip to runner-up class
+
+        return x, y
+
+
+# Backwards-compatible functional alias: `generate(...)` == class method.
+generate = WknnDataGenerator.generate