ProDy is a CPU-only protein structure analysis service for computing non-covalent interaction networks and Cα-based RMSD between PDB/CIF structures. The encode action runs ProDy InSty to extract intra- and inter-chain interactions (hydrogen bonds, salt bridges, disulfide bonds, hydrophobic, pi-stacking, cation-pi, van der Waals, ionic, covalent), with optional interaction/energy matrices and frequent-interactor summaries, typically in 2–10 s per structure. The predict action aligns selected protein chains (sequence- or structure-based) and reports RMSD in 1–5 s per pair for mutation, conformational, and model-quality assessment.
Predict¶
Run the predict action for ProDy.
- POST /api/v3/prody/predict/¶
Predict endpoint for ProDy.
- Request Headers:
Content-Type – application/json
Authorization – Token YOUR_API_KEY
Request
params (object, optional) — Configuration parameters for ProDy RMSD calculation:
alignment_method (string, enum: [“sequence”, “structural”], default: “structural”) — Method for aligning structures: “sequence” or “structural”
items (array of objects, min: 1, max: 8) — Input structures for RMSD calculation:
pdb_a (string, optional, min length: 1) — First PDB structure as string
cif_a (string, optional, min length: 1) — First CIF structure as string
chain_a (string or array of strings, required) — Chain ID(s) to use from first structure
pdb_b (string, optional, min length: 1) — Second PDB structure as string
cif_b (string, optional, min length: 1) — Second CIF structure as string
chain_b (string or array of strings, required) — Chain ID(s) to use from second structure
Example request:
- Status Codes:
200 OK – Successful response
400 Bad Request – Invalid input
500 Internal Server Error – Internal server error
Response
results (array of objects) — One result per input item, in the order requested:
rmsd (float) — Root mean square deviation in Angstroms
alignment_method (string) — Alignment method used
chain_a (string or array of strings) — Chain ID or list of chain IDs from first structure
chain_b (string or array of strings) — Chain ID or list of chain IDs from second structure
matched_residues (int, optional) — Number of matched residues after alignment
Example response:
Encode¶
Run the encode action for ProDy.
- POST /api/v3/prody/encode/¶
Encode endpoint for ProDy.
- Request Headers:
Content-Type – application/json
Authorization – Token YOUR_API_KEY
Request
params (object, optional) — Configuration parameters:
add_hydrogens (boolean, default: false) — Whether to add missing hydrogen atoms to the structure
hydrogen_method (string, optional, enum: [“openbabel”, “pdbfixer”], default: “pdbfixer”) — Method to use for adding hydrogens
compute_all_interactions (boolean, default: true) — Whether to compute all types of interactions
return_interaction_matrix (boolean, default: false) — Whether to include the interaction matrix in the response
return_energy_matrix (boolean, default: false) — Whether to include the interaction energy matrix in the response
return_frequent_interactors (boolean, default: false) — Whether to include frequent interactors in the response
frequent_interactors_min_contacts (integer, minimum: 1, default: 1) — Minimum number of contacts for a residue to be reported as a frequent interactor
items (array of objects, min: 1, max: 8) — Input structures:
pdb (string, optional, min length: 1) — PDB structure as a text string
cif (string, optional, min length: 1) — CIF structure as a text string
chain_ids (array of strings, optional) — Chain identifiers to analyze within the structure
chain_pairs (array of arrays of strings, optional) — Pairs of chain identifiers to analyze for inter-chain interactions, where each pair is a list of two chain ID strings
Example request:
- Status Codes:
200 OK – Successful response
400 Bad Request – Invalid input
500 Internal Server Error – Internal server error
Response
results (array of objects) — One result per input item, in the order requested:
structure_format (string) — Input structure format, values: “PDB” or “CIF”
chains_analyzed (array of strings) — Chain IDs that were analyzed, e.g., [“A”] or [“A”, “B”]
chain_pairs_analyzed (array of tuples of strings, optional) — Chain pairs analyzed for inter-chain interactions, each tuple size: 2, e.g., [[“A”, “B”]]
intra_chain_interactions (object) — Intra-chain interaction summaries keyed by chain ID:
{chain_id} (object) — Summary for a single chain:
chain_id (string, optional) — Chain ID for this intra-chain summary
chain_pair (tuple of strings, optional, size: 2) — Chain pair identifier, unused for intra-chain summaries
interaction_counts (object) — Counts per interaction type for this chain, keys are interaction_type strings (e.g., “hydrogen_bond”, “salt_bridge”, “disulfide_bond”, “hydrophobic”, “pi_stacking”, “cation_pi”, “van_der_waals”, “ionic”, “covalent”), values are ints ≥ 0
total_interactions (int) — Total number of interactions for this chain, ≥ 0
interactions (array of objects) — List of intra-chain interactions:
interaction_type (string) — Interaction type, one of: “hydrogen_bond”, “salt_bridge”, “disulfide_bond”, “hydrophobic”, “pi_stacking”, “cation_pi”, “van_der_waals”, “ionic”, “covalent”
chain1 (string) — Chain ID of first residue
residue1 (string) — First residue identifier, e.g., “ALA 1” or “ALA28”
atom1 (string, optional) — Atom identifier or atom name in first residue, e.g., “N_211” or “CD2_787”
chain2 (string) — Chain ID of second residue
residue2 (string) — Second residue identifier, e.g., “GLY 2” or “GLU24”
atom2 (string, optional) — Atom identifier or atom name in second residue
distance (float, optional, units: Å) — Distance between interacting atoms in Angstroms
energy (float, optional, units: kcal/mol) — Interaction energy in kcal/mol
pair_interactions (object) — Inter-chain interaction summaries keyed by chain pair string:
{chain_pair_key} (object) — Summary for a single chain pair, key format: “A-B”:
chain_pair (tuple of strings, size: 2) — Chain pair, e.g., [“A”, “B”]
interactions (array of objects) — List of inter-chain interactions between the two chains:
interaction_type (string) — Interaction type, one of: “hydrogen_bond”, “salt_bridge”, “disulfide_bond”, “hydrophobic”, “pi_stacking”, “cation_pi”, “van_der_waals”, “ionic”, “covalent”
chain1 (string) — Chain ID of first residue
residue1 (string) — First residue identifier, e.g., “ALA 1” or “PHE102”
atom1 (string, optional) — Atom identifier or atom name in first residue
chain2 (string) — Chain ID of second residue
residue2 (string) — Second residue identifier, e.g., “GLY 2” or “LEU45”
atom2 (string, optional) — Atom identifier or atom name in second residue
distance (float, optional, units: Å) — Distance between interacting atoms in Angstroms
energy (float, optional, units: kcal/mol) — Interaction energy in kcal/mol
interaction_counts (object) — Counts per interaction type for this chain pair, keys are interaction_type strings, values are ints ≥ 0
total_interactions (int) — Total number of interactions for this chain pair, ≥ 0
hydrogens_added (bool) — Whether hydrogen atoms were added during preprocessing
interaction_matrix (array of arrays of floats, optional) — Interaction matrix, 2D array shape: N×N, units: arbitrary interaction scores
energy_matrix (array of arrays of floats, optional) — Interaction energy matrix, 2D array shape: N×N, units: kcal/mol
frequent_interactors (array of objects, optional) — Frequent interactor residues if requested:
residue (string) — Central residue identifier, e.g., “ARG215A”
interactors (array of strings) — Interacting residues with interaction type annotations, free-text entries
contact_count (int) — Number of contacts for this residue, ≥ 1
Example response:
Performance¶
Execution profile: ProDy runs on CPU-only workers with a typical allocation of 4 vCPUs and 16 GB RAM per request, which is sufficient for structures up to the 10,000-residue per-item limit and batches of up to 8 items without memory pressure, even when interaction or energy matrices are returned
Encode runtime and scaling: encode calls are dominated by structure parsing, optional hydrogen addition, and interaction enumeration; medium systems (~200–500 residues across 2–4 chains) usually finish in a few seconds and large complexes (~2,000–5,000 residues) in several seconds; ProDy interaction kernels are not thread-safe, so items within a single request are processed sequentially and throughput scales best via many concurrent API requests rather than larger per-request batches
Predict (RMSD) runtime: RMSD prediction (sequence- or structure-based alignment plus superposition) is substantially cheaper than full interaction analysis; for typical 200–1,000-residue protein pairs, predict calls generally complete faster than an equivalent encode run on the same structures
Relative speed, cost, and accuracy: compared to GPU-backed structure-prediction and generative models such as AlphaFold2, ESMFold, Chai-1, ProteinMPNN, ThermoMPNN, and RFdiffusion3, ProDy is much faster and lower-cost per call because it analyzes existing coordinates rather than generating new structures; for protein–protein interfaces, its distance/angle cutoff-based interaction metrics are consistent with curated tools like PLIP and Arpeggio and provide finer-grained contact classifications than scalar predictors like SPURS or Pro4S, while RMSD values are numerically stable and comparable to other structural biology toolkits used within BioLM
Applications¶
Protein–protein interface mapping for therapeutic target assessment, using the encoder endpoint to detect hydrogen bonds, salt bridges, hydrophobics, π–π and cation–π contacts between specified chain pairs and return residue-level interaction lists and counts; this helps biotech R&D teams pinpoint binding hotspots between domains or subunits (e.g., receptor–coreceptor, scaffold–payload fusions) before committing to mutagenesis, especially when combined with structure-prediction models to turn raw 3D coordinates into a contact map; not optimal when nucleic acids or small-molecule ligands are central to the mechanism, since only protein chains are analyzed
Enzyme stability and activity tuning by quantifying intra-chain interaction networks in candidate designs, using the encoder’s interaction and optional energy matrices plus frequent-interactor summaries to reveal salt-bridge clusters, hydrophobic cores, and aromatic networks that stabilize the fold; process and protein engineers can use these matrices to select stabilizing or destabilizing mutations (e.g., strengthening a buried salt bridge for high-temperature operation, or loosening an overly rigid loop that limits turnover), often downstream of generative or stability-prediction models that propose variants which ProDy then filters based on interaction quality; less informative for very small mini-proteins or peptides where network effects are limited
Antibody–antigen binding interface characterization for therapeutic antibody optimization, by running the encoder on antibody–antigen complex structures (experimental or ML-docked) and computing inter-chain contacts between specified antibody chains and the antigen chain to identify which CDR and framework residues contribute hydrogen bonds, salt bridges, hydrophobic and cation–π interactions at the epitope–paratope surface; antibody engineering teams can use these residue-level contact profiles and frequent-interactor outputs to prioritize affinity maturation targets, de-risk humanization changes that may disrupt key contacts, and triage generative-design variants by retaining designs that preserve critical interactions; not suitable for analyzing small-molecule binding to antibodies, as non-protein ligands are ignored
Comparative structural analysis of designed variants via RMSD-based similarity metrics, using the predictor endpoint to compute Cα RMSD between wild-type and designed proteins (or across design generations) after sequence- or structure-based alignment of selected chains, providing a fast, interpretable measure of how much a new design perturbs the original fold; teams running high-throughput design with sequence-based ML models can first obtain 3D structures, then use ProDy RMSD to filter out variants with large backbone shifts in critical domains while allowing localized loop remodeling, focusing wet-lab screening on designs most likely to retain function; this serves as a geometric consistency check rather than a full stability or activity predictor
Production-quality QC and mechanism-of-action support for biotherapeutics, by applying both encoder and predictor endpoints to final or near-final protein constructs (e.g., Fc fusions, multi-domain biologics, engineered scaffolds) to verify that domain–domain interfaces and intra-domain interaction networks are consistent across different structural models (crystal vs. cryo-EM vs. ML-predicted), using interaction counts, frequent-interactor sets, and RMSD values as reproducibility metrics; this enables translational and CMC teams to generate residue-level justifications for why a construct is expected to be stable and correctly assembled, and to flag designs where predicted structures disagree significantly in interface geometry; less useful for modalities dominated by nucleic-acid components where protein-only analysis misses key biology
Limitations¶
Batch Size: Each request to
/encodeor/predictcan include at most 8 items (theitemslist hasmax_length=8). Larger workloads must be split client-side and results merged manually.Maximum Structure Size:
ProDyParams.max_sequence_lenis10000; structures much larger than this may be slow or impractical to analyze. Very small protein chains (fewer than ~5 residues) may be rejected or yield non‑informative interaction networks.Protein-Only Inputs: All analyzed chains must be proteins. Non‑protein chains (DNA, RNA, ligands, ions, other small molecules) are detected during validation (for example in
ProDyEncodeRequestItem.validate_chains_are_proteinandProDyPredictRequestItem.validate_chains_exist) and cause errors. Interactions involving nucleic acids or small‑molecule ligands are not computed.Hydrogen Handling and Determinism: Enabling
ProDyEncodeRequestParams.add_hydrogens=True(usinghydrogen_method='pdbfixer'or'openbabel') is recommended for accurate hydrogen bond detection but adds roughly 1–5 seconds per structure and can introduce small run‑to‑run variation (about ±1 hydrogen bond) due to different hydrogen placements. Other interaction types are deterministic.Not a Learning or Dynamics Model: ProDy is a rule‑based, static structure analyzer (distance/angle cutoffs). It does not learn from data, simulate dynamics, or predict new structures. It is suited for interaction characterization and RMSD between existing protein structures, not for generative design, stability prediction, binding affinity estimation, or trajectory analysis.
Complex/Edge-case Structures and Scaling: Unusual geometries or very large multi‑chain assemblies can expose bugs or performance bottlenecks in the underlying ProDy library, whose C extensions are effectively single‑threaded. For very large complexes or high‑throughput screening, consider using faster or more scalable models for initial filtering and reserve this API for detailed analysis of a smaller subset of protein structures.
How We Use It¶
ProDy integrates into protein engineering workflows as a structure-aware analysis step that turns static 3D models into comparable interaction summaries and RMSD scores for design, filtering, and ranking. By standardizing how hydrogen bonds, salt bridges, hydrophobic and other contacts, and pairwise RMSD are computed across many candidates, teams can compare variants, prioritize interface or core mutations, and explain model-driven designs in a consistent, auditable way. In practice, ProDy often evaluates structures generated by models such as Boltz / Chai-1 and feeds interaction matrices, hotspot summaries, and RMSD metrics into downstream stability or solubility assessments (for example with SPURS or Pro4S), enabling iterative cycles where candidates are proposed, structurally assessed, and then refined based on quantified interaction networks rather than ad hoc visual inspection.
For antibody and enzyme projects, ProDy-derived interaction profiles help define interface or core design constraints, guide mutagenesis libraries, and focus synthesis budgets on variants with favorable contact patterns.
In large-scale ML pipelines, standardized ProDy outputs become structured features for ranking models, driving active-learning loops, and coordinating multi-round optimization campaigns that connect in silico predictions with experimental readouts.
References¶
Bakan, A., Meireles, L. M., & Bahar, I. (2011). ProDy: Protein Dynamics Inferred from Theory and Experiments. Bioinformatics.
Zhang, S., Krieger, J. M., Zhang, Y., Kaya, C., Kaynak, B., Mikulska-Ruminska, K., Doruker, P., Li, H., & Bahar, I. (2021). ProDy 2.0: Increased Scale and Scope after 10 Years of Protein Dynamics Modelling with Python. Bioinformatics.
