Protein Structure Analysis

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 _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 atoms

• Wrong: Ignoring altloc in geometry → Right: Filter atom.get_altloc() in ('', 'A') → Why: Duplicate atoms corrupt RMSD and dihedral calculations

• Wrong: 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 correspondence

• Wrong: No hydrogens before PDBQT export → Right: obabel -xh then -xr -O receptor.pdbqt → Why: Crystal PDBs lack H; docking scoring needs them

• Wrong: Including HETATM/water in backbone calculations → Right: Filter residue.id[0] == ' ' → Why: Heteroatoms and water corrupt phi/psi and backbone RMSD

• Wrong: math.degrees() on None phi/psi → Right: Check if phi is not None and psi is not None → Why: Chain termini return None; TypeError crashes

• Wrong: Default dssp binary name → Right: Pass dssp='mkdssp' to DSSP() → Why: Newer installs only provide mkdssp

• Wrong: 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=True in 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: awslabs
• Source: awslabs/hcls-agent-skills
• License: MIT-0

Install and usage instructions live in the source repository linked above.