ProDy¶

Physics-based protein structure analysis tool computing non-covalent interactions (hydrogen bonds, salt bridges, hydrophobic contacts, pi-stacking, cation-pi, repulsive ionic) and RMSD between structures.

License: MIT · Molecules: protein, complex · Tasks: feature_extraction, utility

Actions: encode, predict · Variants: 1

At a glance¶

Use it when

You need to characterize protein-protein interfaces in detail, identifying all non-covalent interactions at residue-level resolution with energy estimates
You are analyzing antibody-antigen complexes and want to identify critical interface contacts for antibody engineering or epitope mapping
You need to understand the intramolecular interaction network within a protein to identify residues critical for structural stability
You want to compare wild-type and mutant structures via RMSD and then analyze how mutations alter the interaction network
You need interaction network characterization for rational mutagenesis -- the interaction matrix reveals which contacts contribute most to binding or stability
You are building an automated structural analysis pipeline that combines structure prediction with detailed interaction characterization

Strengths

Comprehensive non-covalent interaction analysis detects 6 interaction types: hydrogen bonds, salt bridges, hydrophobic contacts, pi-stacking, cation-pi, and repulsive ionic -- the most complete interaction toolkit in this catalog
Both intra-chain and inter-chain interaction analysis, enabling characterization of protein-protein interfaces (antibody-antigen, enzyme-substrate, homo/hetero-oligomer contacts)
Interaction energy matrix available on request (via return_energy_matrix) provides a global quantitative view of the interaction network for identifying energetically significant contacts
Frequent interactor analysis identifies 'hotspot' residues that make many contacts -- these are prime targets for mutagenesis and correlate with binding affinity contributions
Interaction matrix and energy matrix output options provide a global view of the interaction network for systems-level structural analysis
RMSD computation with both structural alignment (default) and sequence-based alignment for comparing homologous proteins with different sequences
Established tool with extensive literature validation (2,500+ citations since 2011), plus ProDy 2.0 updates (2021) adding SignDy and CryoDy capabilities
CPU-only operation (4 CPUs, 16 GB RAM) -- no GPU required for structural analysis

Limitations

Protein-only interaction analysis -- DNA/RNA chains and small molecule ligands are not included in interaction calculations
Sequential processing of chain pairs (C extensions not thread-safe) -- large complexes with many chain pairs may be slow
Higher resource requirements than Biotite (16 GB RAM vs 8 GB) due to the comprehensive interaction computation
No visualization capabilities -- returns structured data (interaction lists, matrices) but cannot generate molecular graphics
No TM-score computation for size-independent structure comparison
Limited to static structure analysis -- no molecular dynamics trajectory support despite ProDy's full local capabilities
Interaction distance cutoffs use fixed defaults that may not be optimal for all protein types (e.g., membrane proteins with different interaction characteristics)

Reach for something else when

You only need simple RMSD comparison and chain extraction -- use Biotite which is lighter and simpler for these basic tasks
You need to analyze protein-ligand or protein-nucleic acid interactions -- ProDy's InSty module is protein-only
You need molecular dynamics simulation or trajectory analysis -- ProDy in this catalog provides static structure analysis only
You need visualization of interactions -- use PyMOL or ChimeraX locally for molecular graphics
You need sequence-based analysis without structure -- ProDy requires 3D structure (PDB/CIF) input
You need fast analysis of many structures in parallel -- sequential chain pair processing may be a bottleneck for high-throughput workflows

Alternatives

Model	Better when	Worse when
biotite	Biotite is lighter-weight (8 GB vs 16 GB RAM) and simpler for basic tasks (RMSD computation, chain extraction) where detailed interaction analysis is not needed	Biotite provides only RMSD and chain extraction -- no interaction analysis, no hydrogen bond/salt bridge detection, no energy estimates

API & schema¶

Call an action with POST /api/v1/{slug}/{action} — the request envelope is {"items": [...], "params": {...}} and a success returns {"results": [...]}. See the HTTP API page for the base URL, error shape, and full contract.

`encode`¶

Call it

curl -X POST http://127.0.0.1:8000/api/v1/prody/encode \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {}
  ]
}'

Request — ProDyEncodeRequest

Field	Type	Required	Constraints	Description
`params`	ProDyEncodeRequestParams	no		Optional parameters controlling this action (defaults are used when omitted).
`items`	list[ProDyEncodeRequestItem]	yes	items 1–8	Batch of inputs to process in a single request. Up to 8 structures per request.

Nested types

HydrogenMethod

Allowed values: openbabel, pdbfixer

ProDyEncodeRequestItem

Field	Type	Required	Description
`pdb`	string \| null	no	Input structure in PDB format. Provide exactly one of pdb or cif.
`cif`	string \| null	no	Input structure in mmCIF format. Provide exactly one of pdb or cif.
`chain_ids`	list[string] \| null	no	List of chain IDs to analyze. If None, all chains are analyzed.
`chain_pairs`	list[list] \| null	no	List of chain pairs (tuple of two chain IDs) to analyze interactions between. If None, all chain pairs are analyzed. Format: [['A', 'B'], ['A', 'C']]

ProDyEncodeRequestParams

Field	Type	Required	Constraints	Description
`add_hydrogens`	boolean	no	default `False`	Whether to add missing hydrogen atoms to the structure
`hydrogen_method`	HydrogenMethod \| null	no	default `pdbfixer`	Method to use for adding hydrogens (openbabel or pdbfixer)
`return_interaction_matrix`	boolean	no	default `False`	Whether to return the interaction matrix
`return_energy_matrix`	boolean	no	default `False`	Whether to return the interaction energy matrix
`return_frequent_interactors`	boolean	no	default `False`	Whether to return frequent interactors
`frequent_interactors_min_contacts`	integer	no	≥1; default `1`	Minimum number of contacts for frequent interactors

Raw JSON Schema

{
  "$defs": {
    "HydrogenMethod": {
      "description": "Method for adding missing hydrogen atoms.",
      "enum": [
        "openbabel",
        "pdbfixer"
      ],
      "title": "HydrogenMethod",
      "type": "string"
    },
    "ProDyEncodeRequestItem": {
      "additionalProperties": false,
      "description": "Input structure for ProDy InSty analysis.",
      "properties": {
        "pdb": {
          "anyOf": [
            {
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Input structure in PDB format. Provide exactly one of pdb or cif.",
          "title": "Pdb"
        },
        "cif": {
          "anyOf": [
            {
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Input structure in mmCIF format. Provide exactly one of pdb or cif.",
          "title": "Cif"
        },
        "chain_ids": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "List of chain IDs to analyze. If None, all chains are analyzed.",
          "title": "Chain Ids"
        },
        "chain_pairs": {
          "anyOf": [
            {
              "items": {
                "maxItems": 2,
                "minItems": 2,
                "prefixItems": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "string"
                  }
                ],
                "type": "array"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "List of chain pairs (tuple of two chain IDs) to analyze interactions between. If None, all chain pairs are analyzed. Format: [['A', 'B'], ['A', 'C']]",
          "title": "Chain Pairs"
        }
      },
      "title": "ProDyEncodeRequestItem",
      "type": "object"
    },
    "ProDyEncodeRequestParams": {
      "additionalProperties": false,
      "description": "Parameters for ProDy InSty analysis.",
      "properties": {
        "add_hydrogens": {
          "default": false,
          "description": "Whether to add missing hydrogen atoms to the structure",
          "title": "Add Hydrogens",
          "type": "boolean"
        },
        "hydrogen_method": {
          "anyOf": [
            {
              "$ref": "#/$defs/HydrogenMethod"
            },
            {
              "type": "null"
            }
          ],
          "default": "pdbfixer",
          "description": "Method to use for adding hydrogens (openbabel or pdbfixer)"
        },
        "return_interaction_matrix": {
          "default": false,
          "description": "Whether to return the interaction matrix",
          "title": "Return Interaction Matrix",
          "type": "boolean"
        },
        "return_energy_matrix": {
          "default": false,
          "description": "Whether to return the interaction energy matrix",
          "title": "Return Energy Matrix",
          "type": "boolean"
        },
        "return_frequent_interactors": {
          "default": false,
          "description": "Whether to return frequent interactors",
          "title": "Return Frequent Interactors",
          "type": "boolean"
        },
        "frequent_interactors_min_contacts": {
          "default": 1,
          "description": "Minimum number of contacts for frequent interactors",
          "minimum": 1,
          "title": "Frequent Interactors Min Contacts",
          "type": "integer"
        }
      },
      "title": "ProDyEncodeRequestParams",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "params": {
      "$ref": "#/$defs/ProDyEncodeRequestParams",
      "description": "Optional parameters controlling this action (defaults are used when omitted)."
    },
    "items": {
      "description": "Batch of inputs to process in a single request. Up to 8 structures per request.",
      "items": {
        "$ref": "#/$defs/ProDyEncodeRequestItem"
      },
      "maxItems": 8,
      "minItems": 1,
      "title": "Items",
      "type": "array"
    }
  },
  "required": [
    "items"
  ],
  "title": "ProDyEncodeRequest",
  "type": "object"
}

Response — ProDyEncodeResponse

Field	Type	Required	Constraints	Description
`results`	list[ProDyEncodeResponseResult]	yes		Per-input results, returned in the same order as the request items.

Nested types

ChainInteractionSummary

Field	Type	Required	Description
`chain_id`	string \| null	no	Chain ID (for intra-chain interactions)
`chain_pair`	list \| null	no	Chain pair (for inter-chain interactions)
`interaction_counts`	object	yes	Count of each interaction type
`total_interactions`	integer	yes	Total number of interactions
`interactions`	list[Interaction]	no	List of all interactions

ChainPairInteractions

Field	Type	Required	Constraints	Description
`chain_pair`	list	yes	items 2–2	Chain pair (e.g., ('A', 'B'))
`interactions`	list[Interaction]	yes		Interactions between the two chains
`interaction_counts`	object	yes		Count of each interaction type for this pair
`total_interactions`	integer	yes		Total number of interactions for this pair

FrequentInteractor

Field	Type	Required	Description
`residue`	string	yes	Residue identifier (e.g., 'ARG215A')
`interactors`	list[string]	yes	List of interacting residues with interaction types
`contact_count`	integer	yes	Number of contacts

Interaction

Field	Type	Required	Description
`interaction_type`	InteractionType	yes	Type of interaction
`chain1`	string	yes	Chain ID of first residue
`residue1`	string	yes	Residue identifier (e.g., 'ALA 1')
`atom1`	string \| null	no	Atom name in first residue
`chain2`	string	yes	Chain ID of second residue
`residue2`	string	yes	Residue identifier (e.g., 'GLY 2')
`atom2`	string \| null	no	Atom name in second residue
`distance`	number \| null	no	Distance in Angstroms
`energy`	number \| null	no	Interaction energy in kcal/mol

InteractionType

Allowed values: hydrogen_bond, salt_bridge, hydrophobic, pi_stacking, cation_pi, repulsive_ionic

ProDyEncodeResponseResult

Field	Type	Required	Constraints	Description
`structure_format`	string	yes		Format of input structure (PDB or CIF)
`chains_analyzed`	list[string]	yes		List of chain IDs that were analyzed
`chain_pairs_analyzed`	list[list] \| null	no		List of chain pairs that were analyzed for inter-chain interactions
`intra_chain_interactions`	object	no		Intra-chain interactions keyed by chain ID (e.g., {'A': {...}, 'B': {...}})
`pair_interactions`	object	no		Inter-chain interactions keyed by chain pair (e.g., {'A-B': {...}})
`hydrogens_added`	boolean	no	default `False`	Whether hydrogen atoms were added to the structure
`interaction_matrix`	list[list[number]] \| null	no		Interaction matrix (2D array) if requested
`energy_matrix`	list[list[number]] \| null	no		Interaction energy matrix (2D array) if requested
`frequent_interactors`	list[FrequentInteractor] \| null	no		Frequent interactors if requested

Raw JSON Schema

{
  "$defs": {
    "ChainInteractionSummary": {
      "description": "Summary of interactions for a chain or chain pair.",
      "properties": {
        "chain_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Chain ID (for intra-chain interactions)",
          "title": "Chain Id"
        },
        "chain_pair": {
          "anyOf": [
            {
              "maxItems": 2,
              "minItems": 2,
              "prefixItems": [
                {
                  "type": "string"
                },
                {
                  "type": "string"
                }
              ],
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Chain pair (for inter-chain interactions)",
          "title": "Chain Pair"
        },
        "interaction_counts": {
          "additionalProperties": {
            "type": "integer"
          },
          "description": "Count of each interaction type",
          "title": "Interaction Counts",
          "type": "object"
        },
        "total_interactions": {
          "description": "Total number of interactions",
          "title": "Total Interactions",
          "type": "integer"
        },
        "interactions": {
          "description": "List of all interactions",
          "items": {
            "$ref": "#/$defs/Interaction"
          },
          "title": "Interactions",
          "type": "array",
          "default": []
        }
      },
      "required": [
        "interaction_counts",
        "total_interactions"
      ],
      "title": "ChainInteractionSummary",
      "type": "object"
    },
    "ChainPairInteractions": {
      "description": "Interactions for a specific chain pair.",
      "properties": {
        "chain_pair": {
          "description": "Chain pair (e.g., ('A', 'B'))",
          "maxItems": 2,
          "minItems": 2,
          "prefixItems": [
            {
              "type": "string"
            },
            {
              "type": "string"
            }
          ],
          "title": "Chain Pair",
          "type": "array"
        },
        "interactions": {
          "description": "Interactions between the two chains",
          "items": {
            "$ref": "#/$defs/Interaction"
          },
          "title": "Interactions",
          "type": "array"
        },
        "interaction_counts": {
          "additionalProperties": {
            "type": "integer"
          },
          "description": "Count of each interaction type for this pair",
          "title": "Interaction Counts",
          "type": "object"
        },
        "total_interactions": {
          "description": "Total number of interactions for this pair",
          "title": "Total Interactions",
          "type": "integer"
        }
      },
      "required": [
        "chain_pair",
        "interactions",
        "interaction_counts",
        "total_interactions"
      ],
      "title": "ChainPairInteractions",
      "type": "object"
    },
    "FrequentInteractor": {
      "description": "A frequent interactor residue.",
      "properties": {
        "residue": {
          "description": "Residue identifier (e.g., 'ARG215A')",
          "title": "Residue",
          "type": "string"
        },
        "interactors": {
          "description": "List of interacting residues with interaction types",
          "items": {
            "type": "string"
          },
          "title": "Interactors",
          "type": "array"
        },
        "contact_count": {
          "description": "Number of contacts",
          "title": "Contact Count",
          "type": "integer"
        }
      },
      "required": [
        "residue",
        "interactors",
        "contact_count"
      ],
      "title": "FrequentInteractor",
      "type": "object"
    },
    "Interaction": {
      "description": "A single interaction between two residues/atoms.",
      "properties": {
        "interaction_type": {
          "$ref": "#/$defs/InteractionType",
          "description": "Type of interaction"
        },
        "chain1": {
          "description": "Chain ID of first residue",
          "title": "Chain1",
          "type": "string"
        },
        "residue1": {
          "description": "Residue identifier (e.g., 'ALA 1')",
          "title": "Residue1",
          "type": "string"
        },
        "atom1": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Atom name in first residue",
          "title": "Atom1"
        },
        "chain2": {
          "description": "Chain ID of second residue",
          "title": "Chain2",
          "type": "string"
        },
        "residue2": {
          "description": "Residue identifier (e.g., 'GLY 2')",
          "title": "Residue2",
          "type": "string"
        },
        "atom2": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Atom name in second residue",
          "title": "Atom2"
        },
        "distance": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Distance in Angstroms",
          "title": "Distance"
        },
        "energy": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Interaction energy in kcal/mol",
          "title": "Energy"
        }
      },
      "required": [
        "interaction_type",
        "chain1",
        "residue1",
        "chain2",
        "residue2"
      ],
      "title": "Interaction",
      "type": "object"
    },
    "InteractionType": {
      "description": "Types of interactions computed by ProDy InSty.",
      "enum": [
        "hydrogen_bond",
        "salt_bridge",
        "hydrophobic",
        "pi_stacking",
        "cation_pi",
        "repulsive_ionic"
      ],
      "title": "InteractionType",
      "type": "string"
    },
    "ProDyEncodeResponseResult": {
      "description": "Result of ProDy InSty analysis for a single structure.",
      "properties": {
        "structure_format": {
          "description": "Format of input structure (PDB or CIF)",
          "title": "Structure Format",
          "type": "string"
        },
        "chains_analyzed": {
          "description": "List of chain IDs that were analyzed",
          "items": {
            "type": "string"
          },
          "title": "Chains Analyzed",
          "type": "array"
        },
        "chain_pairs_analyzed": {
          "anyOf": [
            {
              "items": {
                "maxItems": 2,
                "minItems": 2,
                "prefixItems": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "string"
                  }
                ],
                "type": "array"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "List of chain pairs that were analyzed for inter-chain interactions",
          "title": "Chain Pairs Analyzed"
        },
        "intra_chain_interactions": {
          "additionalProperties": {
            "$ref": "#/$defs/ChainInteractionSummary"
          },
          "description": "Intra-chain interactions keyed by chain ID (e.g., {'A': {...}, 'B': {...}})",
          "title": "Intra Chain Interactions",
          "type": "object",
          "default": {}
        },
        "pair_interactions": {
          "additionalProperties": {
            "$ref": "#/$defs/ChainPairInteractions"
          },
          "description": "Inter-chain interactions keyed by chain pair (e.g., {'A-B': {...}})",
          "title": "Pair Interactions",
          "type": "object",
          "default": {}
        },
        "hydrogens_added": {
          "default": false,
          "description": "Whether hydrogen atoms were added to the structure",
          "title": "Hydrogens Added",
          "type": "boolean"
        },
        "interaction_matrix": {
          "anyOf": [
            {
              "items": {
                "items": {
                  "type": "number"
                },
                "type": "array"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Interaction matrix (2D array) if requested",
          "title": "Interaction Matrix"
        },
        "energy_matrix": {
          "anyOf": [
            {
              "items": {
                "items": {
                  "type": "number"
                },
                "type": "array"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Interaction energy matrix (2D array) if requested",
          "title": "Energy Matrix"
        },
        "frequent_interactors": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/FrequentInteractor"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Frequent interactors if requested",
          "title": "Frequent Interactors"
        }
      },
      "required": [
        "structure_format",
        "chains_analyzed"
      ],
      "title": "ProDyEncodeResponseResult",
      "type": "object"
    }
  },
  "properties": {
    "results": {
      "description": "Per-input results, returned in the same order as the request items.",
      "items": {
        "$ref": "#/$defs/ProDyEncodeResponseResult"
      },
      "title": "Results",
      "type": "array"
    }
  },
  "required": [
    "results"
  ],
  "title": "ProDyEncodeResponse",
  "type": "object"
}

`predict`¶

Call it

curl -X POST http://127.0.0.1:8000/api/v1/prody/predict \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "chain_a": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIE",
      "chain_b": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIE"
    }
  ]
}'

Request — ProDyPredictRequest

Field	Type	Required	Constraints	Description
`params`	ProDyPredictRequestParams	no		Optional parameters controlling this action (defaults are used when omitted).
`items`	list[ProDyPredictRequestItem]	yes	items 1–8	Batch of inputs to process in a single request. Up to 8 structure pairs per request.

Nested types

AlignmentMethod

Allowed values: sequence, structural

ProDyPredictRequestItem

Field	Type	Required	Description
`pdb_a`	string \| null	no	First input structure in PDB format. Provide exactly one of pdb_a or cif_a.
`cif_a`	string \| null	no	First input structure in mmCIF format. Provide exactly one of pdb_a or cif_a.
`chain_a`	string \| list[string]	yes	Chain ID(s) to use from first structure. Can be a single chain ID or a list of chain IDs.
`pdb_b`	string \| null	no	Second input structure in PDB format. Provide exactly one of pdb_b or cif_b.
`cif_b`	string \| null	no	Second input structure in mmCIF format. Provide exactly one of pdb_b or cif_b.
`chain_b`	string \| list[string]	yes	Chain ID(s) to use from second structure. Can be a single chain ID or a list of chain IDs.

ProDyPredictRequestParams

Field	Type	Required	Constraints	Description
`alignment_method`	AlignmentMethod	no	default `structural`	Method for aligning structures: 'sequence' or 'structural' (default: structural)

Raw JSON Schema

{
  "$defs": {
    "AlignmentMethod": {
      "description": "Method for aligning structures for RMSD calculation.",
      "enum": [
        "sequence",
        "structural"
      ],
      "title": "AlignmentMethod",
      "type": "string"
    },
    "ProDyPredictRequestItem": {
      "additionalProperties": false,
      "description": "Input structures for RMSD calculation.",
      "properties": {
        "pdb_a": {
          "anyOf": [
            {
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "First input structure in PDB format. Provide exactly one of pdb_a or cif_a.",
          "title": "Pdb A"
        },
        "cif_a": {
          "anyOf": [
            {
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "First input structure in mmCIF format. Provide exactly one of pdb_a or cif_a.",
          "title": "Cif A"
        },
        "chain_a": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          ],
          "description": "Chain ID(s) to use from first structure. Can be a single chain ID or a list of chain IDs.",
          "title": "Chain A"
        },
        "pdb_b": {
          "anyOf": [
            {
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Second input structure in PDB format. Provide exactly one of pdb_b or cif_b.",
          "title": "Pdb B"
        },
        "cif_b": {
          "anyOf": [
            {
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Second input structure in mmCIF format. Provide exactly one of pdb_b or cif_b.",
          "title": "Cif B"
        },
        "chain_b": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          ],
          "description": "Chain ID(s) to use from second structure. Can be a single chain ID or a list of chain IDs.",
          "title": "Chain B"
        }
      },
      "required": [
        "chain_a",
        "chain_b"
      ],
      "title": "ProDyPredictRequestItem",
      "type": "object"
    },
    "ProDyPredictRequestParams": {
      "additionalProperties": false,
      "description": "Parameters for ProDy RMSD calculation.",
      "properties": {
        "alignment_method": {
          "$ref": "#/$defs/AlignmentMethod",
          "default": "structural",
          "description": "Method for aligning structures: 'sequence' or 'structural' (default: structural)"
        }
      },
      "title": "ProDyPredictRequestParams",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "params": {
      "$ref": "#/$defs/ProDyPredictRequestParams",
      "description": "Optional parameters controlling this action (defaults are used when omitted)."
    },
    "items": {
      "description": "Batch of inputs to process in a single request. Up to 8 structure pairs per request.",
      "items": {
        "$ref": "#/$defs/ProDyPredictRequestItem"
      },
      "maxItems": 8,
      "minItems": 1,
      "title": "Items",
      "type": "array"
    }
  },
  "required": [
    "items"
  ],
  "title": "ProDyPredictRequest",
  "type": "object"
}

Response — ProDyPredictResponse

Field	Type	Required	Constraints	Description
`results`	list[ProDyPredictResponseResult]	yes		Per-input results, returned in the same order as the request items.

Nested types

ProDyPredictResponseResult

Field	Type	Required	Description
`rmsd`	number	yes	Root mean square deviation in Angstroms
`alignment_method`	string	yes	Alignment method used
`chain_a`	string \| list[string]	yes	Chain ID(s) from first structure
`chain_b`	string \| list[string]	yes	Chain ID(s) from second structure
`matched_residues`	integer \| null	no	Number of matched residues after alignment (for sequence alignment)

Raw JSON Schema

{
  "$defs": {
    "ProDyPredictResponseResult": {
      "description": "Result of RMSD calculation between two structures.",
      "properties": {
        "rmsd": {
          "description": "Root mean square deviation in Angstroms",
          "title": "Rmsd",
          "type": "number"
        },
        "alignment_method": {
          "description": "Alignment method used",
          "title": "Alignment Method",
          "type": "string"
        },
        "chain_a": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          ],
          "description": "Chain ID(s) from first structure",
          "title": "Chain A"
        },
        "chain_b": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          ],
          "description": "Chain ID(s) from second structure",
          "title": "Chain B"
        },
        "matched_residues": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Number of matched residues after alignment (for sequence alignment)",
          "title": "Matched Residues"
        }
      },
      "required": [
        "rmsd",
        "alignment_method",
        "chain_a",
        "chain_b"
      ],
      "title": "ProDyPredictResponseResult",
      "type": "object"
    }
  },
  "properties": {
    "results": {
      "description": "Per-input results, returned in the same order as the request items.",
      "items": {
        "$ref": "#/$defs/ProDyPredictResponseResult"
      },
      "title": "Results",
      "type": "array"
    }
  },
  "required": [
    "results"
  ],
  "title": "ProDyPredictResponse",
  "type": "object"
}

Usage¶

One-line summary: Physics-based protein structure analysis tool computing non-covalent interactions (hydrogen bonds, salt bridges, hydrophobic contacts, pi-stacking, cation-pi, repulsive ionic) and RMSD between structures.

Overview¶

ProDy integration for computing protein-protein interactions and structural comparisons using ProDy's InSty module.

This model provides two actions:

Encode (InSty): Computes protein-protein interactions including hydrogen bonds, salt bridges, hydrophobic interactions, pi-stacking, cation-pi, and repulsive ionic interactions
Predict (RMSD): Calculates root mean square deviation (RMSD) between two protein structures

Architecture¶

Property	Value
Architecture	Algorithmic (physics-based cutoffs, no learned weights)
Task	Interaction detection, RMSD calculation
Input	PDB or CIF structure
Output	Interaction lists + counts (encode), RMSD value (predict)
GPU	None (CPU-only)

Capabilities & Limitations¶

CAN be used for: - Computing non-covalent interactions within a single protein chain (intra-chain) - Computing interactions between multiple protein chains (inter-chain) - Detecting hydrogen bonds, salt bridges, hydrophobic contacts, pi-stacking, cation-pi, repulsive ionic interactions - Calculating RMSD between two protein structures with structural or sequence alignment - Adding missing hydrogen atoms via PDBFixer or OpenBabel before analysis

CANNOT be used for: - Non-protein chains (DNA, RNA, ligands are not supported) - Structures with fewer than 5 residues (insufficient for meaningful interaction analysis) - Thread-safe parallel processing (ProDy C extensions are not thread-safe; batch processing is sequential) - Fully deterministic hydrogen bond counts (may vary by +/-1 between runs due to borderline detection at cutoff thresholds)

Other considerations: - Core interactions (salt bridges, hydrophobic) are fully deterministic - CIF files are automatically converted to PDB format before processing

Usage Examples¶

Encode (Interaction Analysis)¶

from models.prody.schema import (
    ProDyEncodeRequest,
    ProDyEncodeRequestItem,
    ProDyEncodeRequestParams,
    HydrogenMethod,
)

request = ProDyEncodeRequest(
    params=ProDyEncodeRequestParams(
        add_hydrogens=True,
        hydrogen_method=HydrogenMethod.OPENBABEL,
    ),
    items=[
        ProDyEncodeRequestItem(
            cif=cif_string,
            chain_ids=["A", "B"],
            chain_pairs=[("A", "B")],
        )
    ],
)

Predict (RMSD)¶

from models.prody.schema import (
    ProDyPredictRequest,
    ProDyPredictRequestItem,
    ProDyPredictRequestParams,
    AlignmentMethod,
)

request = ProDyPredictRequest(
    params=ProDyPredictRequestParams(
        alignment_method=AlignmentMethod.SEQUENCE,
    ),
    items=[
        ProDyPredictRequestItem(
            cif_a=structure_a_cif,
            chain_a="A",
            cif_b=structure_b_cif,
            chain_b="A",
        )
    ],
)

Architecture & training¶

Architecture¶

Model Type & Innovation¶

ProDy is not a neural network -- it is an algorithmic protein structure analysis library that computes molecular interactions and structural comparisons using physics-based distance and angle cutoffs. The BioLM implementation wraps ProDy's InSty (Interactions and Stability) module and RMSD calculation into a serving endpoint.

The key utility is that ProDy computes non-covalent interactions (hydrogen bonds, salt bridges, hydrophobic contacts, pi-stacking, cation-pi, repulsive ionic) between residues using standardized geometric criteria, and RMSD between protein structures using structural or sequence-based alignment.

Parameters & Layers¶

ProDy is parameter-free -- it uses physics-based cutoffs rather than learned weights.

Interaction Type	Distance Cutoff	Other Criteria
Hydrogen bond	2.7-3.4 Angstrom	Angle constraints
Salt bridge	3.3-3.5 Angstrom	Charged residue pairs
Hydrophobic	3.4-4.5 Angstrom	Non-polar residue contacts
Pi-stacking	Variable	Aromatic ring geometry
Cation-pi	Variable	Cation and aromatic ring
Repulsive ionic	Variable	Like-charge pairs

Training Data¶

Not applicable -- ProDy is a physics-based tool with no training data.

Loss Function & Objective¶

Not applicable.

Tokenization / Input Processing¶

Property	Details
Structure input	PDB or CIF format
Chain validation	Must be protein chains (DNA/RNA/ligands rejected)
Minimum residues	5 (for meaningful interaction analysis)
Hydrogen addition	PDBFixer (default, more accurate) or OpenBabel (faster)
CIF conversion	OpenMM (primary) or ProDy (fallback)

Performance & Benchmarks¶

Published Benchmarks¶

ProDy's interaction detection follows standard crystallographic distance/angle criteria. Validation is inherent in the method rather than requiring benchmark comparisons.

BioLM Verification Results¶

Metric	Threshold	Status
Hydrogen bond counts	Exact (+/-1 tolerance)	PASS
Salt bridge counts	Exact match	PASS
Hydrophobic counts	Exact match	PASS
RMSD (identical structures)	Near-zero (~1e-14)	PASS
RMSD (different structures)	5% relative tolerance	PASS

Hydrogen bond counts may vary by +/-1 between runs due to borderline detection at distance/angle cutoffs after non-deterministic hydrogen placement.

Comparison to Alternatives¶

Tool	Key Advantage	Key Disadvantage
ProDy (this)	Comprehensive interaction types, energy matrices, frequent interactors	Requires hydrogen addition for H-bond detection
PLIP	Integrated visualization	Fewer interaction types
Arpeggio	More interaction types, handles nucleic acids	Heavier dependencies
GetContacts	Fast contact analysis	Less robust hydrogen handling

Error Bars & Confidence¶

ProDy is deterministic for non-hydrogen interactions. Hydrogen bond counts may vary +/-1 due to non-deterministic hydrogen placement by PDBFixer/OpenBabel energy minimization.

Strengths & Limitations¶

Pros¶

Comprehensive interaction analysis (6 interaction types) with standardized cutoffs
RMSD calculation with structural or sequence-based alignment
CPU-only -- no GPU required, low resource footprint
Handles both single-chain and multi-chain interaction analysis
Returns interaction matrices, energy matrices, and frequent interactor analysis
Supports both PDB and CIF input formats

Cons¶

Hydrogen bond counts are slightly non-deterministic (+/-1)
ProDy C extensions are not thread-safe; batch processing is sequential
Requires at least 5 residues for meaningful analysis
Only analyzes protein chains (nucleic acids and small molecules rejected)
Hydrogen addition adds processing time (~1-5s per structure)

Known Failure Modes¶

Non-protein chains: Requesting analysis of DNA, RNA, or ligand chains raises a ValueError with the detected molecule type
Very small structures: Structures with fewer than 5 residues are rejected
ProDy index errors: Some unusual structure geometries trigger internal ProDy indexing bugs
Hydrophobic calculation bugs: Known ProDy issue with certain structure geometries

Implementation Details¶

Inference Pipeline¶

Encode (InSty) pipeline:

Request
  |-- 1. Validate structure (PDB/CIF, protein chains only)
  |-- 2. Parse structure (ProDy parsePDB/parseMMCIF)
  |-- 3. Add hydrogens if requested (PDBFixer or OpenBabel)
  |-- 4. Create ProDy Interactions object
  |-- 5. Calculate protein interactions (calcProteinInteractions)
  |-- 6. Extract intra-chain interactions per chain
  |-- 7. Extract inter-chain interactions per chain pair
  |-- 8. Build interaction/energy matrices if requested
  |-- 9. Get frequent interactors if requested
  |-- 10. Return ProDyEncodeResponse

Predict (RMSD) pipeline:

Request
  |-- 1. Parse both structures (ProDy)
  |-- 2. Select specified chains (protein only)
  |-- 3. Extract CA atoms
  |-- 4. Match chains (structural or sequence alignment)
  |-- 5. Calculate transformation and apply
  |-- 6. Compute RMSD
  |-- 7. Return ProDyPredictResponse

Memory & Compute Profile¶

Component	Resource
CPU	4 cores
Memory	16 GB RAM
GPU	None (CPU-only)
Inference time (encode)	2-10s per structure (depends on chain count and hydrogen addition)
Inference time (predict)	1-5s per pair

Determinism & Reproducibility¶

Setting	Value
`random.seed`	42
`numpy.random.seed`	42
Hydrogen bonds	+/-1 non-determinism
All other interactions	Fully deterministic

Caching Behavior¶

Response caching is available as an optional, off-by-default gateway feature (BIOLM_CACHE_ENABLED) -- see the gateway docs; it is not handled by the model container. Memory snapshots are disabled (enable_memory_snapshot=False) to ensure fresh code execution on each container start.

Versions & Changelog¶

Version	Date	Changes
v1	2026-02-14	Initial implementation with encode (InSty) and predict (RMSD) actions
v1 (updated)	2026-02-14	Added chain validation (protein-only, with molecule type detection)
v1 (updated)	2026-02-14	Added multi-chain analysis with chain_pairs parameter

Biology¶

Molecule Coverage¶

Primary Molecule Type(s)¶

ProDy analyzes protein structures -- both single-chain and multi-chain complexes. It accepts PDB or CIF format structures and requires that analyzed chains contain protein residues (not DNA, RNA, or small molecules).

Performance characteristics by structure type:

Single-chain proteins: Full intra-chain interaction analysis. All 6 interaction types detected.
Protein complexes: Both intra-chain and inter-chain interaction analysis. Chain pairs can be specified explicitly or all pairs are analyzed.
Antibody-antigen complexes: Supported. Inter-chain interaction analysis between antibody and antigen chains reveals binding interface contacts.
Enzyme-substrate complexes: Protein chains are analyzed; small-molecule ligands are excluded from interaction calculation.
Membrane proteins: Supported if structure is available. Interactions within transmembrane domains are detected normally.

Cross-Applicability¶

Molecule Type	Applicability	Evidence	Caveats
Proteins (single-chain)	High	Primary use case	Full interaction analysis
Protein complexes	High	Multi-chain analysis with chain pairs	Sequential processing (C extensions not thread-safe)
Antibodies	High	Protein chains analyzed normally	Only protein-protein interactions; no CDR-specific logic
Enzymes	High	Active-site interactions detectable	Ligand interactions not computed
DNA/RNA chains	Not supported	Rejected with error	Chains must be protein
Ligands/small molecules	Not supported	Not analyzed	ProDy InSty is protein-only

Biological Problems Addressed¶

Protein-Protein Interface Characterization¶

Problem: Understanding which residues mediate protein-protein interactions is essential for drug design, antibody engineering, and understanding disease mechanisms. Crystallographic structures show the 3D arrangement but do not directly enumerate the non-covalent interactions that stabilize the interface.

How ProDy helps: The encode action with chain_pairs specified computes all inter-chain interactions between two protein chains. It returns hydrogen bonds, salt bridges, hydrophobic contacts, pi-stacking, cation-pi, and repulsive ionic interactions with residue-level resolution, distances, and optional energy estimates.

Biological meaning: The interaction profile reveals the chemical nature of the binding interface. A salt-bridge-rich interface suggests electrostatic complementarity; a hydrophobic-dominated interface indicates burial of non-polar surface area. Frequent interactor analysis identifies "hotspot" residues that make many contacts -- these are often critical for binding and are prime targets for mutagenesis.

Structural Comparison via RMSD¶

Problem: Comparing protein structures -- before/after mutation, across conformational states, between homologs -- requires quantitative structural similarity metrics. RMSD (root mean square deviation) is the standard metric.

How ProDy helps: The predict action computes RMSD between two structures after alignment. It supports structural alignment (default) and sequence-based alignment for homologous proteins with different sequences.

Biological meaning: RMSD quantifies the average displacement of matched atoms (CA atoms) between two structures. An RMSD of 0-1 Angstrom indicates nearly identical conformations; 1-3 Angstrom indicates similar fold with local differences; >5 Angstrom indicates major structural changes. This is used to assess conformational changes upon ligand binding, mutation effects on structure, and homology model quality.

Intra-Chain Interaction Networks¶

Problem: Identifying the network of non-covalent interactions within a protein reveals which residues stabilize the fold, form functional sites, or create allosteric pathways.

How ProDy helps: The encode action computes all intra-chain interactions within each specified chain. The interaction matrix and energy matrix options provide a global view of the interaction network.

Biological meaning: Dense clusters of hydrogen bonds and salt bridges often indicate structured, stable regions. Hydrophobic cores are revealed by dense hydrophobic contact networks. Pi-stacking and cation-pi interactions in aromatic clusters can indicate functional sites. The energy matrix quantifies the energetic contribution of each interaction.

Applied Use Cases¶

ProDy is an established bioinformatics tool (published 2011, >2500 citations). Applied use cases include:

Drug-target interaction analysis: Characterizing binding interfaces between therapeutic targets and partner proteins
Mutation impact assessment: Comparing wild-type and mutant structures via RMSD
Antibody-antigen interface mapping: Identifying critical interface contacts for antibody engineering
Protein engineering: Understanding which interactions stabilize the fold to guide rational design
Quality assessment: RMSD comparison of computational models against experimental structures

Complementary Models¶

ESMFold / Chai-1 (this catalog): Structure prediction models that generate the 3D structures ProDy then analyzes
SPURS (this catalog): Uses structure as input for stability prediction; ProDy can characterize the interactions SPURS implicitly evaluates

Alternative Models¶

Alternative	Advantage Over ProDy	Disadvantage vs ProDy
PLIP	Built-in visualization	Fewer interaction types
Arpeggio	More interaction types, nucleic acid support	Heavier dependencies
MDAnalysis	Molecular dynamics trajectory support	More complex API for simple interaction analysis
GetContacts	Fast contact extraction	Less robust hydrogen handling

When to choose ProDy: Use ProDy when you need comprehensive protein-protein interaction analysis with energy estimates, interaction matrices, and frequent interactor identification.

When to choose alternatives: Use PLIP for quick visualization; use Arpeggio when nucleic acid interactions are needed; use MDAnalysis for trajectory analysis.

Biological Background¶

Non-covalent interactions are the forces that hold protein structures together and mediate protein-protein recognition. Unlike covalent bonds, they are individually weak (1-40 kcal/mol) but collectively strong enough to stabilize 3D structure and drive specific molecular recognition.

Types of interactions ProDy detects:

Hydrogen bonds: The most common non-covalent interaction in proteins. Formed between a hydrogen donor (N-H, O-H) and an acceptor (O, N). Critical for secondary structure (alpha-helices, beta-sheets) and specificity of molecular recognition. Typical distance: 2.7-3.4 Angstrom.
Salt bridges: Electrostatic interactions between oppositely charged residues (e.g., Lys/Arg with Asp/Glu). Important for protein stability and can contribute 1-5 kcal/mol to binding free energy. Typical distance: 3.3-3.5 Angstrom.
Hydrophobic interactions: The thermodynamic driving force for protein folding. Non-polar residues (Leu, Ile, Val, Phe, Trp) pack together in the protein interior to minimize contact with water. Typical distance: 3.4-4.5 Angstrom.
Pi-stacking: Interactions between aromatic rings (Phe, Tyr, Trp, His). Can be face-to-face (sandwich), edge-to-face (T-shaped), or offset stacked. Important in protein-ligand and protein-protein interfaces.
Cation-pi: Interactions between positively charged residues (Lys, Arg) and aromatic rings. Energetically significant (1-5 kcal/mol) and common in protein-protein interfaces.
Repulsive ionic: Repulsive interactions between like-charged residues (e.g., two Asp or two Lys nearby). These destabilize local structure and are relevant for understanding charge-charge repulsion in protein design.

RMSD (Root Mean Square Deviation): The standard metric for quantifying structural similarity between two protein conformations. Calculated as the square root of the mean squared distance between corresponding atom positions after optimal superposition. Lower RMSD indicates more similar structures.

Key terminology: - InSty: ProDy's Interactions and Stability module for computing non-covalent interactions - Hotspot residue: A residue that contributes disproportionately to binding affinity; often identified by having many interaction contacts - Structural alignment: Superimposing structures by minimizing RMSD between corresponding atoms - Sequence alignment: Matching structures by aligning their amino acid sequences before RMSD calculation

Sources & license¶

License: MIT (text)

Papers

ProDy: Protein Dynamics Inferred from Theory and Experiments — Bioinformatics, 2011 · DOI

Source repositories

github: https://github.com/prody/ProDy
pypi: https://pypi.org/project/ProDy/
github: https://github.com/openmm/pdbfixer
github: https://github.com/openbabel/openbabel

ProDy¶

At a glance¶

API & schema¶

encode¶

predict¶

Usage¶

Overview¶

Architecture¶

Capabilities & Limitations¶

Usage Examples¶

Encode (Interaction Analysis)¶

Predict (RMSD)¶

Architecture & training¶

Architecture¶

Model Type & Innovation¶

Parameters & Layers¶

Training Data¶

Loss Function & Objective¶

Tokenization / Input Processing¶

Performance & Benchmarks¶

Published Benchmarks¶

BioLM Verification Results¶

Comparison to Alternatives¶

Error Bars & Confidence¶

Strengths & Limitations¶

Pros¶

Cons¶

Known Failure Modes¶

Implementation Details¶

Inference Pipeline¶

Memory & Compute Profile¶

Determinism & Reproducibility¶

Caching Behavior¶

Versions & Changelog¶

Biology¶

Molecule Coverage¶

Primary Molecule Type(s)¶

Cross-Applicability¶

Biological Problems Addressed¶

Protein-Protein Interface Characterization¶

Structural Comparison via RMSD¶

Intra-Chain Interaction Networks¶

Applied Use Cases¶

Related Models¶

Complementary Models¶

Alternative Models¶

Biological Background¶

Sources & license¶

`encode`¶

`predict`¶