clustering-tfjs/dist/clustering/linkage.d.ts

High-performance TypeScript clustering algorithms (K-Means, Spectral, Agglomerative) with TensorFlow.js acceleration and scikit-learn compatibility

/**
 * Utility helpers implementing Lance–Williams update formulas for the most
 * common hierarchical clustering linkage criteria.
 *
 * The functions work on an explicit distance matrix represented as a
 * JavaScript number[][] (2-D array) to avoid pulling TensorFlow into the
 * critical inner loop. This keeps the implementation lightweight, easy to
 * test and free of any GC pressure from temporary tensors.
 *
 * The matrix *must* satisfy the following conditions:
 *   • Square (n × n)
 *   • Symmetric:   D[i][j] === D[j][i]
 *   • Zero diagonal: D[i][i] === 0 for all i
 *
 * When two clusters "i" and "j" are merged into a new cluster "t" the
 * distance matrix needs to be updated by computing the distance between "t"
 * and each remaining cluster "k" according to the chosen linkage criterion.
 *
 * The Lance–Williams recurrence expresses the updated distance D(t,k) as a
 * linear combination of the previous distances:
 *
 *          D(t,k) =  α_i  · D(i,k)
 *                   + α_j  · D(j,k)
 *                   +  β   · D(i,j)
 *                   + γ · | D(i,k) − D(j,k) |
 *
 * For the four linkage strategies implemented in this module the parameters
 * are:
 *
 *   • Single   : α_i = α_j = 0.5,  β = 0,        γ = -0.5
 *   • Complete : α_i = α_j = 0.5,  β = 0,        γ = +0.5
 *   • Average  : α_i = n_i / (n_i + n_j),
 *                α_j = n_j / (n_i + n_j),  β = 0, γ = 0
 *   • Ward     : α_i = (n_i + n_k) / (n_i + n_j + n_k),
 *                α_j = (n_j + n_k) / (n_i + n_j + n_k),
 *                β   = -n_k / (n_i + n_j + n_k),        γ = 0
 *
 * However, for Single/Complete/Average it is considerably cheaper and more
 * intuitive to compute the updated distance directly (min, max, weighted
 * mean) instead of evaluating the general formula above. Ward linkage on the
 * other hand is implemented using the Lance-Williams coefficients because it
 * requires them for numerical stability.
 */
export type LinkageCriterion = 'single' | 'complete' | 'average' | 'ward';
/** Distance matrix represented as a square 2-D number array. */
export type DistanceMatrix = number[][];
/**
 * Updates the distance matrix after merging clusters `i` and `j` into a new
 * cluster. The function mutates the matrix *in place* and returns it for
 * convenience.
 *
 * The row/column with the larger index is removed to keep indices stable for
 * the caller (mirroring the typical implementation in hierarchical
 * clustering libraries). After the merge, entry `i` of `clusterSizes` is
 * overwritten by the new cluster size while entry `j` is removed — keeping
 * the length of the array consistent with the contracted distance matrix.
 *
 * Parameters
 * ----------
 * D             – symmetric distance matrix (will be mutated)
 * clusterSizes  – array holding the size (number of original samples) of each
 *                 current cluster. Must have the same length as D.
 * i, j          – indices of the clusters to be merged (i < j).
 * linkage       – linkage criterion used for the update.
 */
export declare function update_distance_matrix(D: DistanceMatrix, clusterSizes: number[], i: number, j: number, linkage: LinkageCriterion): DistanceMatrix;
//# sourceMappingURL=linkage.d.ts.map