Silhouette analysis threshold optimization

silhouette-analysis-threshold-optimization

License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->

Summary

Replace fixed dendrogram-flattening thresholds with silhouette-score optimization to derive data-driven cluster assignments. This skill evaluates hierarchical clustering solutions by maximizing silhouette coefficients, yielding structural cluster assignments that adapt to the intrinsic cohesion and separation of LC-MS feature groups rather than relying on arbitrary cutoff values.

When to use

When you have a pre-computed hierarchical dendrogram from structural clustering (e.g., of LC-MS features based on m/z and retention time) and want to compare or validate the cluster assignments produced by a fixed constant-threshold method. Use this skill to assess whether silhouette-optimized flattening yields meaningfully different or more robust cluster solutions, especially when the constant-threshold choice (e.g., cut_threshold=0.7) is arbitrary or domain-specific.

When NOT to use

• Input dendrogram was not pre-computed from a complete run; silhouette optimization requires a stable dendrogram to re-flatten.
• You do not have a prior constant-threshold clustering result for comparison; silhouette optimization alone without a baseline makes agreement assessment impossible.
• Feature dataset is very small (< 20 features) or highly imbalanced in cluster sizes; silhouette scores may be unstable and max_clusters may exceed meaningful granularity.

Inputs

• pre-computed correlation matrix (from hierarchical clustering run)
• hierarchical dendrogram object (from prior MamsiStructSearch run with constant threshold)
• LC-MS feature dataset with feature IDs, m/z, and retention time values
• constant-threshold cluster assignments (from prior flattening)

Outputs

• silhouette-optimized cluster assignment labels for all features
• adjusted Rand index and normalized mutual information agreement metrics
• side-by-side comparison table (feature ID, constant-threshold cluster ID, silhouette cluster ID, agreement status)
• silhouette coefficient scores for each cluster (quality metric)

How to apply

Load the pre-computed correlation matrix and dendrogram from a prior hierarchical clustering run (e.g., using linkage_method='complete'). Re-flatten the same dendrogram using silhouette-score optimization by calling the get_correlation_clusters() method with flat_method='silhouette' and specify a maximum number of clusters (e.g., max_clusters=11) to constrain the search space. Extract cluster assignment labels for all features from both the constant-threshold and silhouette-optimized solutions. Compute agreement metrics between the two clustering solutions using adjusted Rand index (ARI) and normalized mutual information (NMI) to quantify concordance. Generate a side-by-side comparison table showing feature IDs, constant-threshold cluster ID, silhouette-optimized cluster ID, and agreement status to identify features whose cluster membership differs and interpret the impact on downstream structural interpretation.

Related tools

• MAMSI (Multi-Assay Mass Spectrometry Integration) (Python framework housing the MamsiStructSearch.get_correlation_clusters() method with flat_method='silhouette' parameter for silhouette-optimized dendrogram flattening) — https://github.com/kopeckylukas/py-mamsi
• scikit-learn (Provides silhouette_score() and related clustering metrics (adjusted_rand_score, normalized_mutual_info_score) for agreement and cluster quality evaluation)
• scipy (Supplies hierarchical clustering (linkage, dendrogram) and distance computations for dendrogram structure)
• pandas (Data frame manipulation for tabulating and comparing cluster assignments across methods)
• numpy (Numerical array operations for extracting and masking cluster labels)

Examples

struct.get_correlation_clusters(flat_method='silhouette', max_clusters=11)

Evaluation signals

• Silhouette scores for each cluster in the optimized solution are all non-negative and ideally > 0.5, indicating well-separated and cohesive clusters.
• Adjusted Rand index between constant-threshold and silhouette-optimized solutions is quantified (ranges 0–1, with 1 = perfect agreement); significant disagreement (ARI < 0.7) warrants investigation of which features switched clusters.
• Normalized mutual information score confirms the degree of information overlap between the two solutions; values closer to 1 indicate higher agreement.
• The comparison table shows no singleton clusters (clusters with only 1 feature) in the silhouette solution, or if they exist, they have negative silhouette scores, indicating potential misclassification.
• Maximum silhouette score across cluster ranges (2 to max_clusters) shows a clear peak, indicating the optimized number of clusters balances granularity and stability.

Limitations

• Silhouette optimization is sensitive to the choice of max_clusters parameter; setting it too high increases computational cost and may yield spurious fine-grained clusters, while setting it too low may miss meaningful structure.
• The method assumes the dendrogram and correlation matrix remain valid and consistent; re-flattening the same dendrogram does not re-compute correlations, so changes in feature selection or preprocessing require a fresh dendrogram run.
• Silhouette scores favor well-separated, spherical clusters; elongated, chain-like structural clusters (e.g., adduct networks) may receive lower scores despite being scientifically meaningful in LC-MS structural interpretation.
• No changelog is documented for the MAMSI package, making it difficult to track whether the flat_method='silhouette' implementation has been updated or refined across versions.

Evidence

• [other] Load pre-computed correlation matrix and hierarchical dendrogram from a prior MamsiStructSearch run using constant threshold (cut_threshold=0.7, linkage_method='complete'). Re-flatten the same dendrogram using silhouette-score optimization with max_clusters=11 via the get_correlation_clusters() method with flat_method='silhouette'.: "Load pre-computed correlation matrix and hierarchical dendrogram from a prior MamsiStructSearch run using constant threshold (cut_threshold=0.7, linkage_method='complete'). Re-flatten the same"
• [other] Extract and tabulate cluster assignment labels for all features from both flattening methods. Compute agreement metrics (adjusted Rand index, normalized mutual information) between the two clustering solutions.: "Extract and tabulate cluster assignment labels for all features from both flattening methods. Compute agreement metrics (adjusted Rand index, normalized mutual information) between the two clustering"
• [other] Generate a side-by-side comparison table showing feature IDs, constant-threshold cluster ID, silhouette-optimized cluster ID, and agreement status.: "Generate a side-by-side comparison table showing feature IDs, constant-threshold cluster ID, silhouette-optimized cluster ID, and agreement status."
• [other] MAMSI integrates multi-assay mass spectrometry datasets and clusters statistically significant LC-MS features based on structural properties defined by m/z and retention time.: "MAMSI integrates multi-assay mass spectrometry datasets and clusters statistically significant LC-MS features based on structural properties defined by m/z and retention time."
• [readme] from sklearn.model_selection import train_test_split: "Further, you can use the MamsiStrustSearch.get_correlation_clusters() method to find correlation clusters. struct.get_correlation_clusters(flat_method='silhouette', max_clusters=11)"