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. You can also make the clusters from a dataset column instead. This page explains how the grouping is computed, what the Summary Table's quality figures and Δ stars mean, and why the UMAP 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, each identified by the two residues it links and its type. |
| Chem chains | Position-aware: the same chem chain at the same position costs nothing, a different one at the same position costs at most half, and present-versus-absent costs the full mismatch. |
The backbone and branch comparisons use the same graded substitution model as the center-star 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 Center-Star 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 chem chains 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. The Total shown next to Component Weights is only the sum of the sliders: it does not need to reach 100.
Setting a component's weight to zero leaves that component out, and the other weights are scaled up instead. 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
Auto-detect optimal k (number of clusters) is on by default. Ideation then 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.
Clusters from a column
With Clusters from set to an endpoint, the clusters are not computed: each value of the column is one cluster, and peptides without a value form a (no value) cluster. Only columns with at most 10 different values are offered, so that the clusters stay readable.
Ideation still computes the structural distances with your component weights. It uses them to pick each cluster's medoid, and for the quality figures, the Comparison Matrix, the UMAP plot and the nearest-neighbour lines. Every view of the Cluster Explorer therefore works the same way.
The quality then answers a different question: how structurally alike the members of each group are, not whether the grouping is good. That is why the column reads Structural quality. A grouping by series or by batch often scores low, and that is expected.
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 cluster of a single peptide has no silhouette of its own, so its quality reads N/A. So does a run that gives only one cluster.
After a manual edit, Ideation recomputes the quality figures and the medoids from the same distances. A moved peptide that does not resemble its new cluster shows up as an outlier.
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.
How a cluster's Δ is tested
Under each numeric endpoint value, the Summary Table shows a Δ: the cluster's value minus the value of all the other clustered peptides, in the same aggregation as the column (for example the mean). A Δ alone does not say whether the difference is real or due to a few lucky peptides. So Ideation tests it.
- The test is a Mann-Whitney U test of the cluster's values against the rest. It compares ranks, not raw values, so it does not assume a normal distribution and a single extreme value does not drive it.
- Testing every cluster at once makes some differences look significant by chance. The p-values are therefore adjusted across the clusters of each endpoint (Benjamini-Hochberg), giving a q-value.
- The stars show the adjusted q-value: ★ below 0.05, ★★ below 0.01, ★★★ below 0.001. A starred Δ is also shown in bold.
- A side with fewer than 3 values is not tested.
A Δ without stars does not prove that the cluster is no different. Small clusters rarely reach significance. Hover a Δ to see both values, the counts, p and q.
The UMAP plot is a different calculation
The Cluster Explorer's UMAP View (2D or 3D) is 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 chem chains 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.
Two things help you read the plot:
- Auto parameters sets the UMAP settings from your clusters. n_neighbors (how many neighbours each point looks at) follows the typical cluster size: the median size of the clusters of two peptides or more, between 5 and 50. This keeps each cluster together without merging it with the next one. min_dist (how tightly points can pack) stays small, so the clusters stay apart while near-identical peptides do not hide each other. UMAP also runs with a fixed seed, so the same data and settings always give the same plot.
- The Nearest neighbours lines link each peptide of the selected cluster to its closest peptides by the clustering distance, not by the distance on the plot. A line that crosses the plot shows two peptides the clustering finds close, even though the projection puts them apart.
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. The peptide count on the Run Clustering button is the clue: it is the size of the whole dataset. If you have filtered down to a subseries and then run clustering, the clusters describe the whole dataset, not your selection. The Cluster Explorer also shows and exports every peptide of the dataset.
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 chem chains 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, reading the Cluster Explorer and editing clusters
- Understanding Hotspots and Synergies — the position-level analyses
- Understanding Center-Star Alignment — the substitution model clustering shares with the center-star aligner

