StructClustR

StructClustR is an interactive R/Shiny app for rapidly clustering related protein structures and selecting real structures as cluster representatives. It accepts PDB and mmCIF files and is designed for small-to-medium predicted structural ensembles.

What it does

• Reads protein C-alpha atoms and matches them by chain, residue number, and insertion code.
• Falls back to C-alpha position when identifiers differ but every model has the same C-alpha count.
• Superposes each model pair before calculating RMSD.
• Runs k-means on MDS coordinates by default, with PAM/k-medoids on the fitted RMSD matrix as a distance-based alternative.
• Lets you select k manually (default: 3) or request a silhouette-based suggestion. Automatic selection prefers a solution without singleton clusters when possible.
• Selects the within-cluster medoid as the representative, so every representative is an actual uploaded model.
• Preserves the true file format and extension of every representative.
• Displays an MDS map, cluster diagnostics, assignments, summary statistics, an RMSD heatmap, and a direct PDB/mmCIF 3D viewer.
• Exports representative structures alone or a complete reproducible results bundle.

Install

R 4.2 or newer is recommended. Install the required packages once:

install.packages(c(
  "shiny", "bio3d", "plotly", "bslib", "waiter", "r3dmol",
  "DT", "colourpicker", "cluster", "zip"
))

The optional PDB/mmCIF converter also needs Python and Biopython:

python -m pip install biopython

Python is not required for clustering, exporting representatives, or viewing structures.

Run

From the project directory:

shiny::runApp(".")

or:

Rscript run_app.R

Then upload at least three related .pdb and/or .cif models and click Run analysis.

Reading the results

• Average silhouette measures how well each model fits its assigned cluster compared with its nearest alternative cluster. Values above 0.5 usually indicate clear separation; values near zero indicate overlapping groups.
• Mean pairwise RMSD describes cluster compactness.
• RMSD to representative shows how far each structure is from its cluster medoid.
• The MDS map is a visualization of RMSD relationships. K-means uses the complete MDS embedding rather than only the two displayed dimensions; PAM operates directly on the RMSD matrix.

Automatic k selection is a useful starting point, not a biological conclusion. Inspect the candidate-k chart, cluster sizes, representative structures, and the RMSD heatmap before choosing a final partition.

Export contents

The complete analysis ZIP contains:

• representatives/ with correctly named PDB or CIF files;
• cluster_summary.csv;
• model_assignments.csv;
• pairwise_rmsd.csv;
• analysis_info.txt with the method and key run settings.

Input assumptions

The models should describe the same protein, peptide, or complex. StructClustR uses the C-alpha trace, so ligands and non-protein atoms do not influence the RMSD. If models differ substantially in chain naming, residue numbering, sequence length, or missing residues, review the matching mode shown above the results.

License

MIT License.

Author

Ivan Sanchis, PhD

Laboratorio de Péptidos Bioactivos

Facultad de Bioquímica y Ciencias Biológicas, Universidad Nacional del Litoral

Santa Fe, Argentina