Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.

Kennard Stone

python_badge license_badge PyPI version Downloads

CI docs release

Conda Version Conda Platforms

Ruff mypy

What is this?

This is an algorithm for evenly partitioning data in a scikit-learn-like interface. (See References for details of the algorithm.)

simulation_gif

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 the documentation for the API reference and tutorials.

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.

To run the tutorial notebooks in docs_src/tutorials, install the extra dependencies with pip install "kennard-stone[example]".

Changes in v4.0.0

  • KFold with n_splits >= 3 returns 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. KFold with n_splits=2 and train_test_split are not affected. To reproduce the folds of v3, use kennard-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

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

Sites

Changelog

See the GitHub Releases for v3.0.0 and later, and CHANGELOG.md for earlier versions.

Metadata

Release files for kennard-stone 4.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Change of provenance

The repository or configuration that created these release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Source distribution (sdist)

Source distribution for kennard-stone 4.1.1
File Size Uploaded Provenance Actions
kennard_stone-4.1.1.tar.gz 1.1 MB With provenance Details for kennard_stone-4.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kennard-stone 4.1.1
File Interpreter ABI Platform Actions
kennard_stone-4.1.1-py3-none-any.whl Python 3 none any Details for kennard_stone-4.1.1-py3-none-any.whl

Total release size: 1.1 MB

Release files / kennard_stone-4.1.1.tar.gz

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL kennard_stone-4.1.1.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
979a0dc2cb3c687fcb3d74010bc33b4bbc9625cc544c7f89c7c110abb57806bf
BLAKE2b-256 checksum
How to use checksums
3ef486b7729099f21461e497ade44b55ad3c23e10a5457888b4ee508f5f09f8a
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 log

Release files / kennard_stone-4.1.1-py3-none-any.whl

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL kennard_stone-4.1.1-py3-none-any.whl
Size 20.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6c9a60ebad8e6c75271b20632f52df84721da66b070b9718b3e449b5078e6fc4
BLAKE2b-256 checksum
How to use checksums
aa2c4d8de712822d186996fcc1a15cdab9ddf4f96b2ae516c21ab1ba8287af35
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 log

Security for kennard-stone 4.1.1

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.

Change of provenance

The configuration that created this release differs from a previous release.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Select from 2 files

Attestation for kennard_stone-4.1.1.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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page