The Structure QC Report grades the geometry of protein models, one model at a time: predicted complexes, designs, MD frames, or crystal structures. It catches construction failures (a distorted helix, side chains driven into each other, a peptide bond flipped to cis, a mangled ligand) before those models reach expensive steps such as docking, MM-GBSA, or model training. It never changes coordinates. It runs on CPU with Biopython, SciPy, and RDKit.
How it works
Only heavy atoms are graded; hydrogens are not placed. Every definition below is CogniChem's own, so the numbers will not match MolProbity's.
- Ramachandran: each residue's φ / ψ pair is classed favored, allowed, or outlier against hand-drawn regions for four residue classes (general, glycine, proline, and the residue before a proline). The regions follow the published shapes of the favored and allowed areas; no reference contour data is used.
- Rotamers: each side-chain χ angle must sit within 40° of a canonical staggered position (or, for aromatic rings, a perpendicular or m−30 position). Angles with naturally broad distributions are not graded.
- Clashes: two heavy atoms clash when their van der Waals radii overlap by 0.4 Å or more. Atoms up to four bonds apart, N / O pairs at hydrogen-bond distance, and metal–ligand contacts are exempt. The clashscore is clashes per 1,000 heavy atoms.
- Peptide bonds: ω near 0° on a residue other than proline is a non-Pro cis-peptide; ω more than 30° from planar trans is a twisted peptide.
- Cβ deviation: the distance of each Cβ from its ideal position built from the backbone; more than 0.25 Å is an outlier.
- Ligands: each ligand's bonds and angles are compared with a copy of the same molecule minimized with the MMFF94 force field, as Z-scores. Bond orders are read from the ligand's own geometry. Ions, waters, common crystallization additives, DNA / RNA nucleotides, and modified amino acids (such as selenomethionine or phosphoserine, which are graded as protein instead) are not graded as ligands.
Reading the grades
Each model gets pass, warn, or fail per metric, plus a count of failed metrics (qc_fail_count) and an overall status. The default levels are versioned and recorded with every run; you can override any warn or fail level, or what counts as one outlier. For predicted models, treat B-factors as pLDDT to flag residues under a confidence cutoff instead of penalizing them: low-confidence regions are marked in the offender list, and the metrics still count them.
Inputs
PDB or CIF files, or structures from an upstream workflow step: a structure ensemble from Boltz-2, FreeBindCraft, or RFAntibody, or a single structure from ESMFold2 or OpenMM MD. Only the first model of a multi-model file is graded. A file that cannot be graded (unreadable, no protein in the selected chains, or over 5,000 residues) gets a failed row with the reason in error; the rest of the batch still runs.
Outputs
| File | Contents |
|---|---|
qc.csv | One row per model: size, every metric, each metric's status, warn and fail counts, the overall status, and error for a model that could not be graded |
offenders.csv | One row per flagged residue or ligand term: chain, residue, metric, value, detail, severity, and whether it is low-confidence, worst first |
structures/ | Each graded input passed through unchanged, every chain and model included (CIF inputs written as PDB) |
summary.json | Thresholds and their version, status counts, median and maximum per metric across the batch, software versions, and warnings |
In a workflow
The graded models come out as a structure ensemble that carries their QC metrics, so a filter step can gate on them: for example, keep only models with no failed metric (qc_fail_count at most 0) before MM-GBSA Rescoring, or only models without non-Pro cis-peptides before the Protein Structure Ensemble Comparator.
Not covered
- Geometry quality is not binding plausibility: a model can pass every check and still bind the wrong way.
- Heavy atoms only: some real hydrogen-bond contacts can read as clashes, and clashes that involve hydrogens are not seen.
- Ligand Z-scores use each ligand's own geometry to assign bond orders, so a badly distorted ligand can be read with the wrong chemistry; its Z-scores are still large. This is not a comparison with the Chemical Component Dictionary.
- Grading only: no side-chain rebuilding or repair (use the Protein Preparer), no RNA or DNA validation, and no docking-pose quality (use the Docking Protocol Validator).
Related tools
Models that pass go on to MM-GBSA Rescoring, the Interaction Profiler, AutoDock Vina, or GNINA; the Protein Preparer fixes structures before docking.