Kennard Stone
What is this?
This is an algorithm for evenly partitioning data in a scikit-learn-like interface.
(See References for details of the algorithm.)
How to install
PyPI
pip install kennard-stone
The project site is here.
Anaconda
conda install -c conda-forge kennard-stone
The project site is here.
You need numpy>=1.20 and scikit-learn to run.
How to use
You can use them like scikit-learn.
See examples for details.
In the following, X denotes an arbitrary explanatory variable and y an arbitrary objective variable.
And, estimator indicates an arbitrary prediction model that conforms to scikit-learn.
train_test_split
kennard_stone
from kennard_stone import train_test_split
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
scikit-learn
from sklearn.model_selection import train_test_split
X_train, X_test, y_train, y_test = train_test_split(
X, y, test_size=0.2, random_state=334
)
KFold
kennard_stone
from kennard_stone import KFold
# Always shuffled and uniquely determined for a data set.
kf = KFold(n_splits=5)
for i_train, i_test in kf.split(X, y):
X_train = X[i_train]
y_train = y[i_train]
X_test = X[i_test]
y_test = y[i_test]
scikit-learn
from sklearn.model_selection import KFold
kf = KFold(n_splits=5, shuffle=True, random_state=334)
for i_train, i_test in kf.split(X, y):
X_train = X[i_train]
y_train = y[i_train]
X_test = X[i_test]
y_test = y[i_test]
Other usages
If you ever specify cv in scikit-learn, you can assign KFold objects to it and apply it to various functions.
An example is cross_validate.
kennard_stone
from kennard_stone import KFold
from sklearn.model_selection import cross_validate
kf = KFold(n_splits=5)
print(cross_validate(estimator, X, y, cv=kf))
scikit-learn
from sklearn.model_selection import KFold
from sklearn.model_selection import cross_validate
kf = KFold(n_splits=5, shuffle=True, random_state=334)
print(cross_validate(estimator, X, y, cv=kf))
OR
from sklearn.model_selection import cross_validate
print(cross_validate(estimator, X, y, cv=5))
Notes
There is no notion of random_state or shuffle because the partitioning is determined uniquely for the dataset.
If these arguments are included, they do not cause an error. They simply have no effect on the result. Please be careful.
If you want to run the notebook in examples directory,
you will need to additionally install pandas, matplotlib, seaborn, tqdm, and jupyter other than the packages in requirements.txt.
Changes in v4.0.0
KFoldwithn_splits >= 3returns different folds from v3. Each fold takes the remaining sample farthest from its own selected samples, but in v3 the third and later folds could skip their best candidates.KFoldwithn_splits=2andtrain_test_splitare not affected. To reproduce the folds of v3, usekennard-stone<4.- Python 3.8 and 3.9 are no longer supported. Python 3.10 or later is required.
Since v3.1.0, KFold no longer puts a sample in two test folds (which left another sample in none).
On datasets where that happened, the folds differ from earlier versions.
Scaling and initial points (since v3.1.0)
Scaling
Before computing distances, features with zero variance are dropped and the remaining features are standardized with StandardScaler.
Set scale=False to keep the original feature scales (zero-variance features are still dropped).
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, scale=False)
kf = KFold(n_splits=5, scale=False)
Initial points
train_test_split can choose how the selection starts with init.
In both cases, the selection then repeatedly adds the sample whose distance to its nearest selected sample is the largest.
init="farthest_from_mean"(default): start from the sample farthest from the mean of the data.init="farthest_pair": start from the two samples with the largest mutual distance, as in the original paper (Kennard & Stone, 1969).
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, init="farthest_pair")
KFold always uses "farthest_from_mean": each fold starts from one of the n_splits samples farthest from the mean.
Distance metrics
See the documentation of
scipy.spatial.distance.pdisthttps://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.distance.pdist.htmlsklearn.metrics.pairwise_distanceshttps://scikit-learn.org/stable/modules/generated/sklearn.metrics.pairwise_distances.html
Valid values for metric are:
-
From scikit-learn: ['cityblock', 'cosine', 'euclidean', 'l1', 'l2', 'manhattan']. These metrics support sparse matrix inputs. ['nan_euclidean'] but it does not yet support sparse matrices.
-
From scipy.spatial.distance: ['braycurtis', 'canberra', 'chebyshev', 'correlation', 'dice', 'hamming', 'jaccard', 'mahalanobis', 'minkowski', 'rogerstanimoto', 'russellrao', 'seuclidean', 'sokalmichener', 'sokalsneath', 'sqeuclidean', 'yule'] See the documentation for scipy.spatial.distance for details on these metrics. These metrics do not support sparse matrix inputs.
Note: 'sokalmichener' is not available with SciPy >= 1.17 because it has been removed from SciPy.
, by default "euclidean"
Parallelization (since v2.1.0)
This algorithm is very computationally intensive and takes a lot of time.
To solve this problem, I have implemented parallelization and optimized the algorithm since v2.1.0.
n_jobs can be specified for parallelization as in the scikit-learn-like api.
# parallelization KFold
kf = KFold(n_splits=5, n_jobs=-1)
# parallelization train_test_split
X_train, X_test, y_train, y_test = train_test_split(
X, y, test_size=0.2, n_jobs=-1
)
The parallelization is used when calculating the distance matrix,
so it doesn't conflict with something like cross_validate in parallel when using KFold.
# OK: does not conflict each other
cross_validate(estimator, X, y, cv=KFold(5, n_jobs=-1), n_jobs=-1)
Using GPU
If you have a GPU and have installed pytorch, you can use it to calculate Minkowski distances (Manhattan, Euclidean, and Chebyshev distances).
X_train, X_test, y_train, y_test = train_test_split(
X, y, test_size=0.2, device="cuda"
)
Note: the CI has no GPU, so the GPU code path is not tested there.
The GPU tests in tests/gpu run only on a machine with PyTorch and an available GPU (CUDA or Apple MPS), and are skipped otherwise.
If you find a problem with the GPU path, please open an issue.
LICENSE
MIT Licence
Copyright (c) 2021 yu9824
References
Papers
- R. W. Kennard & L. A. Stone (1969) Computer Aided Design of Experiments, Technometrics, 11:1, 137-148, DOI: 10.1080/00401706.1969.10490666
Sites
- https://datachemeng.com/trainingtestdivision/ (Japanese site)
Histories
v2.0.0 (deprecated)
- Define Extended Kennard-Stone algorithm (multi-class) i.e. Improve KFold algorithm.
- Delete
alternateargument inKFold. - Delete requirements of
pandas.
v2.0.1
- Fix bug with Python3.7.
v2.1.0 (deprecated)
- Optimize algorithm
- Deal with Large number of data.
- parallel calculation when calculating distance (Add
n_jobsargument) - replacing recursive functions with for-loops
- parallel calculation when calculating distance (Add
- Add other than "euclidean" calculation methods (Add
metricargument)
v2.1.1 (deprecated)
- Fix bug when
metric="nan_euclidean".
v2.1.2 (deprecated)
- Fix details.
- Update docstrings and typings.
v2.1.3 (deprecated)
- Fix details.
- Update some typings. (You have access to a list of strings that can be used in the metric.)
v2.1.4
- Fix bug when metric=="seuclidean" and "mahalanobis"
- Add some tests to check all metrics.
- Add requirements numpy>=1.20
v2.1.5
- Delete "klusinski" metric to support scipy>=1.11
v2.1.6
- Improve typing in
kennard_stone.train_test_split - Add some docstrings.
v2.2.0
- Supports GPU calculations. (when metric is 'euclidean', 'manhattan', 'chebyshev' and 'minkowski')
- Supports Python 3.12
v2.2.1
- Fix setup.cfg
- Update 'typing'
Metadata
Release files for kennard-stone 4.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kennard_stone-4.1.0.tar.gz | 26.8 kB | With provenance | Details for kennard_stone-4.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kennard_stone-4.1.0-py3-none-any.whl | Python 3 | none | any | Details for kennard_stone-4.1.0-py3-none-any.whl |
Total release size: 47.7 kB
Release files / kennard_stone-4.1.0.tar.gz
| Download URL | kennard_stone-4.1.0.tar.gz |
|---|---|
| Size | 26.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5c654609dcfdb73ac7dc7263ffdc11af4df2177925506b1b68091c40b006bbb2
|
|
BLAKE2b-256 checksum How to use checksums |
49b567919c2257e6f75ec9018b5728b89d5df8cde9061472ad40e421f69932f3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logRelease files / kennard_stone-4.1.0-py3-none-any.whl
| Download URL | kennard_stone-4.1.0-py3-none-any.whl |
|---|---|
| Size | 20.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1fd5a1ab4221eaf8a17d6910e7e9fbede8a0f5a5098ac3fa4add49cb3a183428
|
|
BLAKE2b-256 checksum How to use checksums |
6a7d5b10afcd06e63a9842ce99b3c0a5c6da242e4e505353f9e75a606950e852
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logSecurity for kennard-stone 4.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for kennard_stone-4.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.