feat: add kmeans high-level api skeleton

Author: nakul-krishnakumar

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;

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.