kmeans1d

library0.5.0pypypi✓ verified 83d ago

kmeans1d is a Python package providing an implementation of optimal k-means clustering specifically for one-dimensional data. It utilizes an O(kn + n log n) dynamic programming algorithm, based on research by Xiaolin (1991) and Gronlund et al. (2017), to find globally optimal k clusters. The core logic is written in C++ for performance and wrapped for Python usage. The library is actively maintained, with its current version being 0.5.0.

ai-ml data

pip install kmeans1d

github ↗package ↗

INSTALL

IMPORT

SIG · KMEANS1D

kmeans1d

ai-mlpythonv0.5.0

Install

1.6s avg

Import

26ms

Disk

16MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

build_error

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.026s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

cluster

✓ from kmeans1d import cluster

✗ import kmeans1d; clusters, centroids = kmeans1d.cluster(data, k)

This example demonstrates how to perform 1D k-means clustering on a sample dataset `x` with `k=4` clusters. It returns the cluster assignments for each data point and the computed centroids for each cluster.

import kmeans1d x = [4.0, 4.1, 4.2, -50.0, 200.2, 200.4, 200.9, 80.0, 100.0, 102.0] k = 4 clusters, centroids = kmeans1d.cluster(x, k) print(f"Clusters: {clusters}") print(f"Centroids: {centroids}")

Debug

Known issues

gotchaThis library is designed exclusively for 1-dimensional data. Attempting to use it with multi-dimensional input will result in errors or incorrect behavior, as the underlying algorithm is optimized for the 1D case.

fix

Ensure your input data `x` is a flat list or array of numerical values representing a single dimension.

affects: All versions

gotchaThe number of clusters `k` must be less than or equal to the number of data points `n`. Providing `k > n` may lead to errors or undefined behavior in the clustering function.

fix

Verify that `k <= len(x)` before calling `kmeans1d.cluster(x, k)`.

affects: All versions

gotchaVersions prior to `0.4.0` might have had more specific build requirements for different Python versions or operating systems due to not using the Python Limited API. While `pip install` generally handles this, custom builds or specific environments might encounter issues.

fix

For optimal compatibility across Python versions and simplified builds, ensure you are using `kmeans1d` version `0.4.0` or newer. If building from source for older versions, refer to the release notes for specific compiler or API requirements.

affects: <0.4.0

Upgrade

Version history

0.5.0latest on PyPI · released Dec 12, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/dstein64/kmeans1d ↗

packagehttps://pypi.org/project/kmeans1d/ ↗