kennard_stone package

kennard_stone package#

Split data evenly with the Kennard–Stone algorithm.

The package provides a scikit-learn compatible interface: KFold for cross-validation and train_test_split() for a train/test split.

Copyright © 2021 yu9824

class kennard_stone.KFold(n_splits: int = 5, *, metric: kennard_stone.utils._type_alias.MetricLike = 'euclidean', n_jobs: int | None = None, device: kennard_stone.utils._type_alias.Device = 'cpu', scale: bool = True, shuffle: None = None, random_state: None = None)#

K-fold cross-validator based on the Kennard–Stone algorithm.

The samples are split into n_splits folds so that each fold covers the feature space as evenly as possible. The folds are determined by the data alone, without randomness. Use it like sklearn.model_selection.KFold, for example as cv in sklearn.model_selection.cross_validate().

Parameters:
  • n_splits (int, default=5) – Number of folds. Must be at least 2.

  • metric (str or callable, default="euclidean") – Distance metric: a name accepted by sklearn.metrics.pairwise_distances(), or a callable that returns a distance matrix.

  • n_jobs (int, default=None) – Number of parallel jobs for the distance computation (CPU only).

  • device ({"cpu", "cuda", "mps"} or torch.device, default="cpu") – Device for the distance computation. A GPU requires PyTorch and is used only for “euclidean”, “manhattan”, “chebyshev” and “minkowski”.

  • scale (bool, default=True) – Whether to standardize the features before computing distances.

  • shuffle (None) – Ignored, because the folds do not depend on randomness. A value other than None emits a warning.

  • random_state (None) – Ignored, like shuffle.

See also

train_test_split

Split arrays into a training and a test set.

Notes

Features with zero variance are dropped and, if scale is True, the remaining features are standardized before computing distances.

Each fold starts from one of the n_splits samples farthest from the mean of the data. The folds then take samples in turn: in each round, every fold takes, among the samples not selected yet, the one whose distance to its nearest sample in that fold is the largest (max-min criterion).

Changed in version 4.0.0: With n_splits >= 3, the third and later folds could skip their best candidates in earlier versions.

Examples

>>> from sklearn.datasets import load_diabetes
>>> from kennard_stone import KFold
>>> X, y = load_diabetes(return_X_y=True)
>>> for train, test in KFold(n_splits=5).split(X):
...     pass
kennard_stone.train_test_split(*arrays: T, test_size: float | int | None = None, train_size: float | int | None = None, metric: kennard_stone.utils._type_alias.MetricLike = 'euclidean', n_jobs: int | None = None, device: kennard_stone.utils._type_alias.Device = 'cpu', scale: bool = True, init: kennard_stone.utils._type_alias.InitMethod = 'farthest_from_mean', random_state: None = None, shuffle: None = None) → list[T]#

Split arrays into a training and a test set with Kennard–Stone.

The samples selected first by the Kennard–Stone algorithm form the training set, so that it covers the feature space evenly; the rest form the test set. The order is computed from the first array and applied to all arrays. Use it like sklearn.model_selection.train_test_split().

Parameters:
  • *arrays (sequence of indexables) – Arrays of the same length (lists, ndarrays, scipy sparse matrices, pandas DataFrames, …).

  • test_size (float or int, default=None) – Proportion (between 0.0 and 1.0) or number of test samples. If None, the complement of train_size; if both are None, 0.25.

  • train_size (float or int, default=None) – Proportion or number of training samples. If None, the complement of test_size.

  • metric – See KFold.

  • n_jobs – See KFold.

  • device – See KFold.

  • scale – See KFold.

  • init ({"farthest_from_mean", "farthest_pair"}, default="farthest_from_mean") –

    How the selection starts:

    • "farthest_from_mean": from the sample farthest from the mean of the data.

    • "farthest_pair": from the two samples farthest from each other, as in the original algorithm (Kennard & Stone, 1969).

  • random_state (None) – Ignored, because the split does not depend on randomness. A value other than None emits a warning.

  • shuffle (None) – Ignored, because the split does not depend on randomness. A value other than None emits a warning.

Returns:

[X_train, X_test, y_train, y_test, ...]: the training and test parts of each array, in order.

Return type:

list

Raises:

ValueError – If no array is given.

See also

KFold

Cross-validator based on the Kennard–Stone algorithm.

Notes

Features with zero variance are dropped and, if scale is True, the remaining features are standardized before computing distances.

After the start given by init, the algorithm repeatedly selects the sample whose distance to its nearest selected sample is the largest (max-min criterion).

References

R. W. Kennard and L. A. Stone, “Computer Aided Design of Experiments”, Technometrics, 11(1), 137–148 (1969).

Examples

>>> from sklearn.datasets import load_diabetes
>>> from kennard_stone import train_test_split
>>> X, y = load_diabetes(return_X_y=True)
>>> X_train, X_test, y_train, y_test = train_test_split(
...     X, y, test_size=0.2
... )

Subpackages#