### 14 releases (1 stable)

1.0.0 | Aug 25, 2023 |
---|---|

0.3.3 | Aug 22, 2023 |

0.2.4 | Aug 17, 2023 |

0.1.3 | Aug 15, 2023 |

#**174** in Geospatial

**49** downloads per month

**MIT/Apache**

35KB

660 lines

# Ckmeans

Ckmeans clustering is an improvement on 1-dimensional (univariate) heuristic-based clustering approaches such as Jenks. The algorithm was developed by Haizhou Wang and Mingzhou Song (2011) as a dynamic programming approach to the problem of clustering numeric data into groups with the least within-group sum-of-squared-deviations.

Minimizing the difference within groups – what Wang & Song refer to as

, or within sum-of-squares – means that groups are optimally homogenous within and the data is split into representative groups. This is very useful for visualization, where one may wish to represent a continuous variable in discrete colour or style groups. This function can provide groups that emphasize differences between data.`withinss`

Being a dynamic approach, this algorithm is based on two matrices that store incrementally-computed values for squared deviations and backtracking indexes.

Unlike the original implementation, this implementation does not include any code to automatically determine the optimal number of clusters: this information needs to be explicitly provided. It **does** provide the

method to aid labelling, however.`roundbreaks`

# FFI

A C-compatible FFI implementation is available, along with libraries for major platforms. See the header file and a basic C example in the

folder. The FFI functions have been verified not to leak memory (see comment in example).`examples`

# WASM

A WASM module is also available, giving access to both

and `ckmeans`

. Generate the module using `roundbreaks`

and the appropriate target, or use the NPM package.`wasm-bindgen`

# Implementation

This is a port (including documentation) of David Schnurr's package https://github.com/schnerd/ckmeans, incorporating some improvements from Bill Mill's Python + Numpy implementation at https://github.com/llimllib/ckmeans.

# Performance

On an M2 Pro, to produce 7 classes:

- 110k uniformly-distributed i32 values between 0 and 250: ~12 ms
- 110k normally-distributed f64 values with a mean of 3.0 and a standard deviation of 1.0: 38 ms

## Complexity

$O(kn)$. Other approaches such as Hilferink's

or k-means have comparable complexity, but do `CalcNaturalBreaks`*not* guarantee optimality. In practice, they require many rounds to approach an optimal result, so in practice they're slower.

### Note

Wang and Song (2011) state that the algorithm runs in $O(k^2n)$ in their introduction. However, they have since updated their dynamic programming algorithm (see August 2016 note here) which reduces the complexity to linear time. This approach has been used in the extant implementations listed above, and reproduced here.

## Possible Improvements

### Perf

The "matrices" are nested vectors and thus don't have optimal memory layout. In addition, we're not trying to leverage any of the fast linear algebra libraries that might be available if we used e.g.

.`ndarray`

### Tests

Perhaps some property-based tests.

# References

#### Dependencies

~1–2.7MB

~43K SLoC