awslabs Protein Structure Analysis — Pipeline Skill (Thin Scaffold)
Overview
Adds tool-selection logic, format-conversion rules, and niche gotchas for protein structure tasks. The agent already knows Biopython/PyMOL syntax — this skill prevents common parameter and workflow mistakes.
Usage
- Activate when parsing PDB/mmCIF, computing RMSD, detecting pockets, or converting formats
- Activate for Ramachandran plots, contact maps, B-factor analysis, or DSSP assignment
- Activate when preparing structures for downstream docking (PDBQT export)
Core Concepts
SMCRA hierarchy: Structure → Model → Chain → Residue → Atom. Always iterate at the correct level; NMR files have multiple models.
Altloc: Alternate conformations flagged with non-blank code ('A','B'). Filter to one before any geometry calculation.
fpocket output: Writes <basename>_out/ in the current working directory, not next to the input file. Pockets ranked by druggability score (0–1).
Decision Logic
Tool Selection
| Task | Tool | Key consideration |
|---|---|---|
| Parse PDB/mmCIF | Biopython PDBParser/MMCIFParser |
Always pass QUIET=True |
| RMSD superposition | Bio.PDB.Superimposer |
Requires equal-length, 1-to-1 atom lists |
| Binding pocket detection | fpocket CLI | Needs clean PDB (no altloc, no HETATM clutter) |
| Pocket visualization | PyMOL (-cq for headless) |
byres all within 5 of organic for pocket selection |
| Contact analysis | Bio.PDB.NeighborSearch |
4.0 Å default cutoff; returns atom pairs |
| Secondary structure | DSSP via Biopython | Binary is mkdssp on newer installs |
| Format: PDB→mmCIF | Bio.PDB.MMCIFIO |
Lossless for coordinates |
| Format: PDB→PDBQT | obabel -O out.pdbqt -xr |
Add -xh for hydrogens first |
| Ramachandran | PPBuilder → get_phi_psi_list() |
Termini return None — must check |
RMSD Type Selection
| Scenario | Atoms to use | Notes |
|---|---|---|
| Backbone comparison | Cα only | Standard for fold similarity |
| Loop flexibility | All backbone (N, Cα, C, O) | Captures local deviations |
| Binding site comparison | All-atom within 5 Å of ligand | Requires residue selection first |
| Identical sequences | All-atom | Only valid for same-length chains |
Critical Parameters
| Parameter | Value | When to change |
|---|---|---|
| NeighborSearch cutoff | 4.0 Å | 3.5 for H-bonds, 5.0 for hydrophobic |
| Superimposer atoms | Cα | All-atom only for identical sequences |
fpocket -m (min alpha spheres) |
35 (default) | Lower to 15 for small/shallow pockets |
| DSSP binary name | mkdssp |
Use dssp on legacy installs |
obabel -xr flag |
receptor mode | Omit for flexible ligand PDBQT |
| PPBuilder vs CaPPBuilder | PPBuilder | CaPPBuilder only for Cα-only traces |
Common Mistakes
Wrong: Assuming single model in PDB → Right: Always
structure[0]or iterate models → Why: NMR ensembles have many models; raw iteration hits unexpected atomsWrong: Ignoring altloc in geometry → Right: Filter
atom.get_altloc() in ('', 'A')→ Why: Duplicate atoms corrupt RMSD and dihedral calculationsWrong: All-atom RMSD when backbone intended → Right: Restrict to Cα for fold comparison → Why: Side-chains inflate RMSD and break correspondence across non-identical sequences
Wrong: Unequal-length atom lists in Superimposer → Right: Match by residue number, build parallel lists of equal length → Why:
set_atoms()requires strict 1-to-1 correspondenceWrong: No hydrogens before PDBQT export → Right:
obabel -xhthen-xr -O receptor.pdbqt→ Why: Crystal PDBs lack H; docking scoring needs themWrong: Including HETATM/water in backbone calculations → Right: Filter
residue.id[0] == ' '→ Why: Heteroatoms and water corrupt phi/psi and backbone RMSDWrong:
math.degrees()on None phi/psi → Right: Checkif phi is not None and psi is not None→ Why: Chain termini return None; TypeError crashesWrong: Default
dsspbinary name → Right: Passdssp='mkdssp'toDSSP()→ Why: Newer installs only providemkdsspWrong: Expecting fpocket output next to input → Right: Run from target directory or move output after → Why: fpocket writes to CWD, not input file location
Wrong: Forgetting
QUIET=Truein parser → Right:PDBParser(QUIET=True)→ Why: Non-fatal warnings flood stdout and obscure real errors
Response Format
- Lead with the command or code the user needs — explain after
- Structure as: confirm inputs → working code → key parameters explained → gotchas
- One complete working example per task; do not show every alternative
- Keep code comments minimal and functional
- Target: 50-100 lines of code with brief surrounding explanation