Clustering groups the peptides in a dataset by overall structural similarity, so you can see which families of analogs a series contains and how their properties differ. This page explains how the grouping is computed, what the Summary table's quality figures mean, and — most importantly — why the scatter plot is not a picture of the clusters.
For the step-by-step settings, see How to Cluster Peptides.
What "similar" means here
Clustering needs a single number for how far apart any two peptides are. Ideation builds that number from four components, each measured in the way that suits it:
| Component | How the distance is measured |
|---|---|
| Backbone monomers | Position by position across the alignment frame, using graded substitution scoring (below). Columns where both peptides have a gap are skipped; a residue facing a gap costs the full mismatch. |
| Branches | Per attachment point, each branch compared like a small backbone. A branch facing no branch at all costs the full mismatch. |
| Bridges | Set overlap (Jaccard distance) over the bridges each peptide carries, keyed by their endpoints and type. |
| Chemical objects | Position-aware: the same object at the same position costs nothing, a different object at the same position costs half, and present-versus-absent costs the full mismatch. |
The backbone and branch comparisons use the same graded substitution model as the automatic alignment: identical monomers cost nothing, monomers sharing a natural analog cost a little, monomers in the same physicochemical family cost more, and unrelated monomers cost the most. That is what makes a modified residue cluster with the amino acid it derives from. See Understanding Peptide Alignment for the model itself.
Component weights are relative, and renormalised per pair
The four weights you set are not absolute contributions. For every pair of peptides, Ideation counts only the components that carry data in at least one of the two, and renormalises their weights across just those.
The purpose is sound: a feature absent from the whole dataset — no branches, say — must not silently dilute every distance toward zero. But it has a consequence worth knowing:
Two peptides that both lack bridges are compared on backbone, branches and chemical objects only, with those weights scaled up to fill the gap. Two other peptides in the same run may be compared on all four. The distance scale is therefore not uniform across the dataset, and the "total: 100" the panel displays is cosmetic rather than a guarantee.
Setting a component's weight to zero does not disable it — it contributes zero while still counting as present, which changes how the remaining weights renormalise. And if every present component is set to zero, all distances collapse to zero and the grouping becomes arbitrary.
How the groups are formed
Ideation uses k-medoids (also called PAM, Partitioning Around Medoids), not k-means. The distinction matters: a medoid is an actual peptide from your dataset chosen as the group's centre, not an averaged phantom point. Every cluster therefore has a real, inspectable representative.
The procedure is:
- Compute the distance between every pair of peptides.
- Pick starting medoids by a farthest-point rule — begin with the most central peptide, then repeatedly take the peptide furthest from any medoid chosen so far, so the initial centres are spread out.
- Repeatedly swap a medoid for a non-medoid whenever doing so lowers the total distance from every peptide to its nearest medoid, stopping when no swap improves things (or after 100 rounds).
This is deterministic — no random seed — so the same dataset and settings always reproduce the same clusters. It is a greedy search though, accepting the first improving swap it finds rather than the best one, so the result is a good grouping and not a provably optimal one.
Auto-detecting the number of clusters
With Auto-detect optimal k enabled, Ideation simply tries every k it can and keeps the best. For each candidate it runs the full clustering and computes the average silhouette coefficient, then picks the k that scores highest.
The range tried is 2 up to 20, further limited to at most half the number of peptides (you cannot meaningfully ask for more clusters than the data can support). Very small datasets short-circuit to 2.
Auto-k is therefore roughly twenty times the work of a single run, all of it after the one-off distance computation. It is a genuine search for the most defensible grouping, not a heuristic guess.
What the quality figures mean
The Quality column and the Outliers count in the Summary table are two views of the same underlying number: the silhouette coefficient of each peptide.
A peptide's silhouette compares how close it sits to its own cluster versus the nearest other cluster, on a scale from −1 to +1. Positive means it is closer to its own group than to any other; negative means it would be better placed elsewhere.
| Reading | Meaning |
|---|---|
| Good clustering | average coefficient ≥ 0.5 |
| Fair clustering | average coefficient ≥ 0.25 |
| Poor clustering | below 0.25 |
| Outliers | the members whose coefficient is negative |
Because both come from the same coefficients, a Poor label and a high outlier count are not two independent pieces of evidence — they are the same finding stated twice. Treat them as one signal.
A Poor rating usually means the series does not actually fall into the number of clusters requested, rather than that anything went wrong. Trying auto-k, or reweighting the components toward the feature you care about, is the useful response.
The consensus pattern is a description, not the rule
Clustering groups peptides by overall similarity. It never applies a per-position rule. The consensus pattern shown for each cluster is derived afterwards, to describe what the members happen to share.
For each position, the most common value among the cluster's members wins — but only if it is held by more than 60% of them. Below that the position is reported as variable. Gaps count as a value in their own right, so a position where most members have nothing is reported as a gap rather than as agreement.
This means a cluster can be tight by distance and still show many variable positions: its members are similar overall without agreeing at any particular place. The consensus is a reading aid, not the definition of the cluster.
The scatter plot is a different calculation
The Cluster Explorer's 2D and 3D projections are produced by UMAP, and this is the biggest trap in the feature.
It is built from a separate, much simpler representation: a presence/absence vector recording which monomers, branches, bridges and chemical objects each peptide contains, with your component weights applied as plain multipliers. That representation is position-blind. It records that a peptide contains a given monomer, not where. None of the alignment-column awareness, the graded analog and family scoring, the gap handling or the per-pair weight renormalisation that define the clustering distance is present in it.
The practical consequences:
- Points that sit close together in the plot are not necessarily close in clustering distance, and vice versa.
- A cluster can legitimately appear scattered across the plot, and two clusters can legitimately appear to overlap, without anything being wrong with either the clustering or the plot.
- Two peptides made of the same residues in a different order are far apart to the clustering and identical to the projection.
Read the projection as a rough map of shared composition. When you need to know whether a grouping is sound, use the Summary table's quality figures, which are computed from the real clustering distances — not from the picture.
Clustering ignores your filters
Hotspot and synergy analysis both run on the peptides currently passing your filters. Clustering does not — it always uses every peptide in the dataset.
This is easy to miss because the panels sit side by side, and nothing in the interface says so. If you have filtered down to a subseries and then run clustering, the clusters describe the whole dataset, not your selection.
Limits worth knowing
- The number of clusters you request is capped at the number of peptides; the slider offers 2 to 20.
- The weight sliders for branches, bridges and chemical objects are disabled and marked (none in dataset) when the dataset has none of that feature.
- There is no peptide-count limit and no warning. Both the distance computation and each clustering sweep grow with the square of the peptide count, so a large dataset simply takes a long time. Clustering runs off the main thread, so the interface stays responsive while it does.
- A projection needs at least two peptides.
Where to go next
- How to Cluster Peptides — running clustering and reading the Cluster Explorer
- Understanding Hotspots and Synergies — the position-level analyses
- Understanding Peptide Alignment — the substitution model clustering shares with the aligner