generate-test-data-for-wknn 0.0.5

Test-data generator for validating the weighted k-NN (wkNN) method.

generate-test-data-for-wknn

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 / Установка

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 (also available as WknnDataGenerator.generate), which builds a labelled dataset (x, y) for testing weighted k-NN.

For each class the generator creates a small reference cloud of random points inside the cube [min_coord, max_abs_coord]^dim. A large pool of query points is then labelled by weighted k-nearest-neighbours against that reference set: each query's distance to every reference point is weighted by a distance-decreasing function, and the class with the largest summed weight wins. Weights are functions of a single scalar — the (normalised) Euclidean distance d between a query and a reference point — and must decrease as d grows (otherwise a ValueError is raised).

Weight functions and parameter layout

Weights depend on one scalar distance d, so params no longer scale with dim.

weight_type	Formula	params length	Constraint
"constant"	w = 1	ignored	always valid (reduces to plain kNN)
"linear"	w = max(a·d + f, 0)	2 [a, f]	a ≤ 0
"inverse"	w = a / d^b + f	3 [a, b, f]	a ≥ 0, b > 0
"exponential"	w = a·exp(−b·d) + f	3 [a, b, f]	a ≥ 0, b > 0

Example: linear with params=[-1, 1] gives w = max(-1·d + 1, 0) — weight 1 at d=0, decreasing to 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]
max_neighbors	None	max number of nearest reference points allowed into each query point's weighted vote; None = all, a cap larger than the reference set is clamped
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.
• Neighbour cap (weighted k-NN): with max_neighbors=k, each query point is classified using only its k nearest reference points. This lets a single close point of one class outweigh several far points of another. Example: for a query at (100, 100) with four class-0 points near the origin and one class-1 point at (99, 99), max_neighbors=1 correctly returns class 1. A cap >= size of the reference set (or None) uses every point.

Example

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, 0.1]),  # a, b, f  (single-distance layout)
    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))

Example — max_neighbors

# Cap the vote to the nearest reference points so a single close point of a
# minority class can outweigh several far points of another.
x, y = generate(
    n_classes=5,
    n_samples=60,
    weight_type="inverse",
    params=np.array([2.0, 1.0, 0.1]),
    max_neighbors=3,
    random_state=0,
)
print(x.shape, y.shape, np.bincount(y))

---

Документация на русском

Библиотека предоставляет одну публичную функцию generate (также доступна как WknnDataGenerator.generate), которая строит размеченный набор данных (x, y) для проверки взвешенного k-NN.

Для каждого класса генератор создаёт небольшое опорное облако случайных точек внутри куба [min_coord, max_abs_coord]^dim. Затем большой пул точек- запросов размечается методом взвешенных k ближайших соседей относительно этого опорного набора: расстояние каждого запроса до всех опорных точек взвешивается убывающей по расстоянию функцией, и побеждает класс с наибольшим суммарным весом. Веса зависят от одного скаляра — (нормированного) евклидова расстояния d между запросом и опорной точкой — и должны убывать с ростом d (иначе возбуждается ValueError).

Весовые функции и формат параметров

Веса зависят от одного скалярного расстояния d, поэтому длина params больше не зависит от dim.

weight_type	Формула	Длина params	Ограничение
"constant"	w = 1	не используется	всегда допустимо (обычный kNN)
"linear"	w = max(a·d + f, 0)	2 [a, f]	a ≤ 0
"inverse"	w = a / d^b + f	3 [a, b, f]	a ≥ 0, b > 0
"exponential"	w = a·exp(−b·d) + f	3 [a, b, f]	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]
max_neighbors	None	максимум ближайших опорных точек, участвующих во взвешенном голосовании точки-запроса; None = все, значение больше опорного набора обрезается
random_state	None	зерно генератора

Возвращает: (x, y) — массивы NumPy; m ≤ n_samples (точки с ничьей удаляются).

Гарантии поведения

• Стратификация: классы сбалансированы (разница ≤ 1 объект).
• Удаление ничьих: точки с равными весами двух лучших классов удаляются.
• Выбросы: заданная доля наиболее пограничных точек переставляется в класс-«второе место», равномерно по всему кубу (а не из одной плоскости).
• Проверка монотонности: невозрастающие/неубывающие параметры → ValueError.
• Ограничение соседей (взвешенный k-NN): при max_neighbors=k точка-запрос классифицируется по k ближайшим опорным точкам. Это позволяет одной близкой точке одного класса перевесить несколько далёких точек другого. Пример: для запроса (100, 100) с четырьмя точками класса 0 у начала координат и одной точкой класса 1 в (99, 99) значение max_neighbors=1 корректно вернёт класс 1. Значение >= размера опорного набора (или None) использует все точки.

Пример

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, 0.0]),  # a, b, f  (single-distance layout)
    outlier_ratio=0.15,
    max_neighbors=4,
    random_state=7,
)
print(x.shape, y.shape, np.bincount(y))

---

License / Лицензия

MIT © Ferubko Andrey, Kazakov Oleg — Bryansk State Technological University of Engineering.