clustering-tfjs/dist/utils/findOptimalClusters.d.ts

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

import type { DataMatrix } from '../clustering/types';
/**
 * Result for a single k value evaluation
 */
export interface ClusterEvaluation {
    /** Number of clusters */
    k: number;
    /** Silhouette score (range: [-1, 1], higher is better) */
    silhouette: number;
    /** Davies-Bouldin index (range: [0, ∞), lower is better) */
    daviesBouldin: number;
    /** Calinski-Harabasz index (range: [0, ∞), higher is better) */
    calinskiHarabasz: number;
    /** Combined score used for selection */
    combinedScore: number;
    /** Cluster labels for this k */
    labels: number[];
}
/**
 * Options for finding optimal clusters
 */
export interface FindOptimalClustersOptions {
    /** Minimum number of clusters to test (default: 2) */
    minClusters?: number;
    /** Maximum number of clusters to test (default: 10) */
    maxClusters?: number;
    /** Algorithm to use (default: 'kmeans') */
    algorithm?: 'kmeans' | 'spectral' | 'agglomerative';
    /** Algorithm-specific parameters */
    algorithmParams?: Record<string, unknown>;
    /** Metrics to use for evaluation (default: all) */
    metrics?: Array<'silhouette' | 'daviesBouldin' | 'calinskiHarabasz'>;
    /** Custom scoring function (default: silhouette + calinski - davies) */
    scoringFunction?: (evaluation: ClusterEvaluation) => number;
}
/**
 * Automatically finds the optimal number of clusters for a dataset by evaluating
 * multiple k values using validation metrics.
 *
 * @param X - Input data matrix (samples × features)
 * @param options - Configuration options
 * @returns Object containing optimal k and detailed results for all tested k values
 *
 * @example
 * ```typescript
 * import { findOptimalClusters } from 'clustering-tfjs';
 *
 * const data = [[1, 2], [1.5, 1.8], [5, 8], [8, 8], [1, 0.6], [9, 11]];
 * const result = await findOptimalClusters(data, { maxClusters: 5 });
 *
 * console.log(`Optimal number of clusters: ${result.optimal.k}`);
 * console.log(`Best silhouette score: ${result.optimal.silhouette}`);
 * ```
 */
export declare function findOptimalClusters(X: DataMatrix, options?: FindOptimalClustersOptions): Promise<{
    /** The optimal cluster evaluation */
    optimal: ClusterEvaluation;
    /** All evaluations sorted by combined score (descending) */
    evaluations: ClusterEvaluation[];
}>;
//# sourceMappingURL=findOptimalClusters.d.ts.map