From 58684fad78a3bfb9c03dff6ee773b140e6c37716 Mon Sep 17 00:00:00 2001 From: Nakul Krishnakumar Date: Mon, 12 Jan 2026 12:11:55 +0530 Subject: [PATCH 1/2] feat: implement skeletion for `ml/cluster/strided/dkmeansld` --- .../ml/cluster/strided/dkmeansld/lib/index.js | 40 +++++ .../ml/cluster/strided/dkmeansld/lib/main.js | 165 ++++++++++++++++++ 2 files changed, 205 insertions(+) create mode 100644 lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/index.js create mode 100644 lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/main.js diff --git a/lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/index.js b/lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/index.js new file mode 100644 index 000000000000..fce40003959a --- /dev/null +++ b/lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/index.js @@ -0,0 +1,40 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2018 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +/** +* Compute fitted cluster results using Lloyd algorithm. +* +* @module @stdlib/ml/cluster/strided/dkmeansld +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* var ndarray = require( '@stdlib/ndarray/ctor' ); +* var kmeans = require( '@stdlib/ml/cluster/strided/dkmeansld' ); +* +*/ + +// MAIN // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/main.js b/lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/main.js new file mode 100644 index 000000000000..e229b50906a6 --- /dev/null +++ b/lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/main.js @@ -0,0 +1,165 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var dlacpy = require( '@stdlib/lapack/base/dlacpy' ).ndarray; +var Float64Array = require( '@stdlib/array/float64' ); +var Int32Array = require( '@stdlib/array/int32' ); +var dfill = require( '@stdlib/blas/ext/base/dfill' ); +var isEqualArray = require( '@stdlib/assert/is-equal-array' ); +var dcopy = require( '@stdlib/blas/base/dcopy' ).ndarray; +var deuclidean = require( '@stdlib/stats/strided/distances/deuclidean' ).ndarray; +var dcosine = require( '@stdlib/stats/strided/distances/deuclidean' ).ndarray; +var dcityblock = require( '@stdlib/stats/strided/distances/deuclidean' ).ndarray; + + +// MAIN // + +/** +* Compute fitted cluster results using Lloyd algorithm. +* @param {PositiveInteger} M - number of samples +* @param {PositiveInteger} N - number of features +* @param {PositiveInteger} k - number of clusters +* @param {NonNegativeInteger} replicates - number of times to repeat clustering with different centroids +* @param {String} metric - distance metric +* @param {NonNegativeInteger} maxIter - maximum number of iterations. +* @param {integer} tol - relative tolerance before declaring convergence. +* @param {Float64Array} X - input strided matrix +* @param {integer} strideX1 - stride of the first dimension. +* @param {integer} strideX2 - stride of the second dimension. +* @param {integer} offsetX - starting index. +* @param {Float64Array} init - strided array containing initial centroid locations. +* @param {integer} strideInit1 - stride of first dimension. +* @param {integer} strideInit2 - stride of second dimension. +* @param {integer} strideInit3 - stride of the third dimension. +* @param {integer} offsetInit - initial index. +* @ returns {Result} results object +*/ +function dkmeansld( M, N, k, replicates, metric, maxIter, tol, X, strideX1, strideX2, offsetX, init, strideInit1, strideInit2, strideInit3, offsetInit ) { // eslint-disable-line max-len + var centroidShift; + var centroidsNew; + var strictConv; + var labelsOld; + var centroids; + var bestDist; + var inertia; + var labels; + var counts; + var shift; + var same; + var dist; + var best; + var iter; + var out; + var ox; + var i; + var j; + var c; + var d; + + centroids = new Float64Array( k*N ); + centroidsNew = new Float64Array( k*N ); + labels = new Int32Array( M ); + labelsOld = new Int32Array( M ); + counts = new Int32Array( k ); // q: sklearn supports sample_weights, should we do the same? if yes, change it to Float64Array + + // centroidShift = new Float64Array( k ); + + dlacpy( 'all', k, N, init, strideInit2, strideInit3, offsetInit, centroids, strideInit2, strideInit3, 0 ); + + if ( metric === 'euclidean' ) { + dist = deuclidean; // TODO: change it to dsquared-euclidean once implemented + } else if ( metric === 'cosine' ) { + dist = dcosine; // TODO: change it to dsquared-cosine once implemented + } else if ( metric === 'cityblock' ) { + dist = dcityblock; + } + + // this is a dense implementation, sklearn also has a sparse implementation + // https://github.com/scikit-learn/scikit-learn/blob/d3898d9d57aeb1e960d266613a2e31b07bca39d7/sklearn/cluster/_kmeans.py#L696C1-L700C46 + strictConv = false; + for ( iter = 0; iter < maxIter; iter++ ) { + dfill( k*N, 0.0, centroidsNew, 1 ); + dfill( k, 0, counts, 1 ); // How do I fill it with a int32? + + ox = offsetX; + for ( i = 0; i < M; i++ ) { + best = 0; + bestDist = dist( N, X, strideX2, ox, centroids, 1, 0 ); + for ( c = 1; c < k; c++ ) { + d = dist( N, X, strideX2, ox, centroids, 1, c*N ); + if ( d < bestDist ) { + bestDist = d; + best = c; + } + } + + labels[ i ] = best; + counts[ best ] += 1; + ox += strideX1; + + for ( j = 0; j < N; j++ ) { + centroidsNew[ ( best*N )+j ] += X[ offsetX + (i*strideX1) + (j*strideX2) ]; // eslint-disable-line max-len + } + } + + for ( c = 0; c < k; c++ ) { + if ( counts[ c ] > 0 ) { + for ( j = 0; j < N; j++ ) { + centroidsNew[ ( c*N )+j ] /= counts[ c ]; + } + } else { + for ( j = 0; j < N; j++ ) { + centroidsNew[ ( c*N )+j ] = centroids[ ( c*N )+j ]; + } + } + } + + d = centroidsNew[ 0 ] - centroids[ 0 ]; + shift = d * d; + for ( i = 1; i < k * N; i++ ) { + d = centroidsNew[ i ] - centroids[ i ]; + shift += d * d; + centroids[ i ] = centroidsNew[ i ]; + } + + if ( isEqualArray( labels, labelsOld ) ) { + strictConv = true; + break; + } else { + // TODO: implement center shift + } + dcopy( M, labels, 1, 0, labelsOld, 1, 0 ); // Magic number `1` and `0` because we assume labels are stored contiguously + } + + if (!strictConv) { + // TODO: Rerun the E-step + } + + // TODO: Compute intertia + + return out; // TODO: create a results object similar to stats/base/ztest/two-sample/results/factory +} + + +// EXPORTS // + +module.exports = dkmeansld; From 237d368a9324e6d5988343915aa0c16ed7e95c77 Mon Sep 17 00:00:00 2001 From: Nakul Krishnakumar Date: Wed, 14 Jan 2026 01:30:15 +0530 Subject: [PATCH 2/2] feat: add kmeans high-level api skeleton --- .../dkmeansld/lib/high_level_kmeans.js | 152 ++++++++++++++++++ .../ml/cluster/strided/dkmeansld/lib/index.js | 2 +- 2 files changed, 153 insertions(+), 1 deletion(-) create mode 100644 lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/high_level_kmeans.js diff --git a/lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/high_level_kmeans.js b/lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/high_level_kmeans.js new file mode 100644 index 000000000000..f6959108e1f7 --- /dev/null +++ b/lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/high_level_kmeans.js @@ -0,0 +1,152 @@ +/* eslint-disable valid-jsdoc */ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var dkmeanselk = require( '@stdlib/ml/cluster/strided/dkmeanselk' ); +var dkmeansld = require( '@stdlib/ml/cluster/strided/dkmeansld' ); +var setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' ); +var isMatrixLike = require( '@stdlib/assert/is-matrix-like' ); +var isInteger = require( '@stdlib/assert/is-integer' ); +var format = require( '@stdlib/string/format' ); +var initCentroids = require( './init_centroids.js' ); + + +// MAIN // + +/** +* Kmeans clustering. +* +* @private +* @param {PositiveInteger} k - number of clusters +* @param {(string|ndarray)} init - initialization method or initial centroids +* @param {(PositiveInteger|string)} replicates - number of replicates or 'auto' +* @throws {TypeError} first argument must be a positive integer +* @throws {TypeError} second argument must be a valid initialization method or matrix +* @throws {TypeError} third argument must be a positive integer or 'auto' +* @returns {Function} fit function +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* var ndarray = require( '@stdlib/ndarray/ctor' ); +* var kmeans = require( '@stdlib/ml/cluster/strided/dkmeansld' ); +* +*/ +function dkmeans( k, init, replicates, maxIter, tol, metric, algorithm ) { // This will live in ml/cluster/kmeans/ctor, kept here just for reference + // TODO: refactor functions arguments and include a `options` argument to follow same pattern as `ml/incr/kmeans` + var model; + var reps; + + // TODO: validate function arguments + + if ( replicates === 'auto' ) { + if ( init === 'kmeans++' || isMatrixLike( init ) ) { + reps = 1; + } else if ( init === 'random' ) { + // reps = ?? + } else if ( init === 'forgy' ) { + // reps = ?? + } + } else if ( isInteger( replicates ) ) { + reps = replicates; + } else { + throw new TypeError( format( 'invalid argument. Argument specifying method for initialization must be either `kmeans++`, `random`, `forgy` or matrix specifying initial centroids. Value: `%s`.', init ) ); + } + + // TODO: update the below attachment to follow similar pattern to stats/strided/ztests + setReadOnly( model, 'fit', fit ); + + return model; + + /** + * Computes fitted cluster results using kmeans clustering. + * + * @private + * @param {MatrixLike} X - input data matrix + * @throws {TypeError} first argument must be a matrix-like object + * @returns {Object} clustering results + * + * @example + * var Float64Array = require( '@stdlib/array/float64' ); + * var ndarray = require( '@stdlib/ndarray/ctor' ); + * + */ + function fit( X ) { + var kmeansSingle; + var centroids; + var singleOut; + var out; + var sx1; + var sx2; + var ox; + var M; + var N; + var i; + + // TODO: Step 1 : validate input matrix + + // TODO: Step 2 : define arguments + M = X.shape[ 0 ]; + N = X.shape[ 1 ]; + sx1 = X.stride[ 0 ]; + sx2 = X.stride[ 1 ]; + ox = X.offset; + + /** + * NOTE : M should be greater than k (M > k) + * ref : https://github.com/scikit-learn/scikit-learn/blob/d3898d9d57aeb1e960d266613a2e31b07bca39d7/sklearn/cluster/_kmeans.py#L876 + */ + + if ( algorithm === 'elkan' ) { + kmeansSingle = dkmeanselk; + } else if ( algorithm === 'lloyd' ) { + kmeansSingle = dkmeansld; + } + + for ( i = 0; i < reps; i++ ) { + centroids = initCentroids( X, init, k ); // ref : https://github.com/scikit-learn/scikit-learn/blob/d3898d9d57aeb1e960d266613a2e31b07bca39d7/sklearn/cluster/_kmeans.py#L961 + singleOut = kmeansSingle( M, N, k, metric, maxIter, tol, X, sx1, sx2, ox, centroids, k, N, 0 ); // magic number `0` because we generate the centroid array with no offset + + /** + * According to sklearn, `singleOut` should be { labels, inertia, centers, nIter } + * ref: https://github.com/scikit-learn/scikit-learn/blob/d3898d9d57aeb1e960d266613a2e31b07bca39d7/sklearn/cluster/_kmeans.py#L1531 + * ??? How should we handle this ??? + */ + } + + /** + * TODO : Check convergence issue + * ref : https://github.com/scikit-learn/scikit-learn/blob/d3898d9d57aeb1e960d266613a2e31b07bca39d7/sklearn/cluster/_kmeans.py#L1545 + */ + + /** + * TODO : Build the `out` object + * ref : https://github.com/stdlib-js/stdlib/pull/9703#discussion_r2681280854 + */ + + return out; + } +} + + +// EXPORTS // + +module.exports = dkmeans; diff --git a/lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/index.js b/lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/index.js index fce40003959a..d8a0c5ecc49e 100644 --- a/lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/index.js +++ b/lib/node_modules/@stdlib/ml/cluster/strided/dkmeansld/lib/index.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2018 The Stdlib Authors. +* Copyright (c) 2026 The Stdlib Authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License.