[teese]

Problem

Prodes describes the structure it is given and does not correct one. When a residue's side chain was not modelled in the deposited file, which is ordinary for exposed charged residues at moderate resolution, that residue carries no charge, and nothing in the output records that it happened. Every charge-derived feature is then wrong with no signal to the user, and the README told users nothing about it.

No ticket. The work follows from a comparison of Prodes against PDB2PQR and APBS.

What changed

• New Preparing your structure section in README.rst, plus docs/structure_preparation.md. Quick start and the worked loop in Using the features in a model repair first, then run PROPKA on the repaired file.
• PDB2PQR goes in its own conda environment, not environment.yml, so the two projects' pins cannot constrain each other.
• Two advisory notes: multi-chain pKa warnings, and feature selection inside cross-validation.

Results

Why the advice is needed. PDB entry 4HKZ is a Fab with two lysines modelled only as far as CB. The columns below differ only in whether those two side chains are present:

	side chains unmodelled	side chains rebuilt
Formal charge at pH 7.4	-2	0
Isoelectric point	6.46	7.61
Mean surface electrostatic potential	-0.013 V	+0.011 V
Surface points with positive potential (NSurfPosEpFormal)	12,976	13,684

31 of the 54 default features move, and a pI of 6.46 and a pI of 7.61 point at different resins.

Whether the advice works. PDB2PQR was installed with the exact command this README gives, then run over 855 structures: 826 monomers predicted by Boltz2 and 29 crystal structures.

structure set	structures	repaired	failed
Boltz2 predicted monomers	826	826	0
crystal structures	29	28	1
total	855	854	1

173 seconds of wall clock on six worker processes; a median of 1.02 seconds per predicted structure. The one failure is PDB2PQR refusing a structure it should refuse, described below.

No test was added or changed; the full existing suite of 403 tests passes in an environment built fresh from the updated environment.yml. All pre-commit hooks pass, and every command added to the README was run end to end.

Not verified

• No code changed, so no feature value moves because of this pull request.
• The 4HKZ effect size depends on resolution and on how many charged residues are disordered; many deposited structures are complete.
• PDB2PQR refuses some structures. The README documents that with crambin, where the refusal is a PDB2PQR defect; 5CHA above is the better example, where the refusal is correct. The README has not been updated to use it.
• --ff=PARSE is documented without comparing the six force fields PDB2PQR ships. Only geometry reaches Prodes, so it should not matter, but that was reasoned, not measured.
• The before-and-after feature comparison covers 40 of the 826 predicted structures and no crystal structures. Multimers and AlphaFold database structures were not run at all.
• The feature selection note is advice about statistics rather than about this package, and is arguably outside a README's scope. It is a separate commit so it can be dropped on its own.
• Property_point.set_lipo scores the C terminal OXT at the maximum of the hydrophobicity scale, which is inverted for a carboxylate oxygen. The constant is documented here but deliberately not changed, because changing it moves feature values and belongs in its own release.

Detail

Running PROPKA after the repair, not before

A residue whose side chain is missing has no pKa to predict, so PROPKA run on the deposited file silently omits those groups. On 4HKZ, PROPKA finds 145 titratable groups in the deposited file and 149 in the repaired one. The four extra are the two rebuilt lysine side chains and the two C-termini that only exist once OXT has been added. Among the 145 groups both runs share, six shift by more than 0.5 pKa units.

PDB2PQR does not replace PROPKA

PDB2PQR can run PROPKA internally with --titration-state-method=propka, but it writes no .pka file for prodes.io.pka_converter to read, and it fixes a single pH where Prodes deliberately separates prediction from calculation so that one prediction serves many pH values. The propka3 step stays. What changes is the file it is pointed at.

Why the repaired file keeps its original name

Prodes takes the ID column of the output from the file name it was given. A repaired file called 1GDW_prep.pdb labels that row 1GDW_prep, which is tedious to undo across a dataset, so the documented commands write the repaired file into a prepared/ subdirectory under its original name. PROPKA writes its .pka file into the working directory rather than beside its input, which the documented commands also account for.

Traps documented

--ffout renames residues into a force field's own scheme, putting ASH, GLH, LYN and HID into the file, and Prodes raises KeyError on any of those. PDB2PQR 3.6.1 accepts a .cif but produced an empty .pqr from a valid one in testing. PDB2PQR applies terminal patches at chain breaks, which Prodes discards because it re-titrates from scratch.

Why a separate environment

Prodes never imports PDB2PQR; it only reads the repaired PDB file PDB2PQR writes, so the two never have to be importable at the same time. Installing them together buys nothing and costs a shared solve: two independently maintained projects on separate release cycles, and the first time one moves a shared dependency the other has not caught up with, the environment stops solving and takes a working Prodes install with it. pip install pdb2pqr into one environment is documented as the alternative, with the note that the PyPI package pins docutils<0.18 while the conda-forge build does not.

References

PDB2PQR asks for two citations and prints both on every run. Both were checked against CrossRef and PubMed. The Protein Science article is volume 27, issue 1, pages 112-128, January 2018 issue, published online October 2017; the DOI is 10.1002/pro.3280. The PDB2PQR paper itself is Nucleic Acids Research 35(Web Server), W522-W525 (2007), DOI 10.1093/nar/gkm276.

The one structure PDB2PQR refused

PDB entry 5CHA, alpha-chymotrypsin. Residue VAL A 9 is modelled with its backbone nitrogen and no other atom: no CA, C, O, CB, CG1, CG2 or OXT, and the same for VAL E 9. Alpha-chymotrypsin is produced by cleaving chymotrypsinogen into three chains, and these are the ragged ends at a cleavage site. A residue with one atom cannot be rebuilt from its neighbours, so PDB2PQR stops with Too few atoms present to reconstruct or cap residue. Prodes reads the same file without a word and describes those residues as a lone nitrogen each.

What the repair does to a predicted structure

Every one of the 826 Boltz2 models needed exactly one atom, and in every case it was OXT, the second oxygen of the C terminal carboxylate, which Boltz2 does not write. No gaps, no alternate conformations, no non-standard residues. Crystal structures are the opposite: 10 of the 29 needed atoms rebuilt, up to 30 atoms across 8 residues, and 29 distinct non-standard residues appear across the two crystal sets.

Structure sources disagree about whether to write OXT at all: every AlphaFold database model sampled has one, no Boltz2 monomer has one, and 21 of 29 crystal structures have one. Prodes gives every OXT a fixed hydrophobicity of 1.0, the maximum on the default mj_scaled scale. Adding the atom therefore moves a median of 9 of the 54 features on a Boltz2 model, and two hydrophobicity features move in one direction.

That artefact is not created by this pull request; it already applies to every AlphaFold structure and most crystal structures. What repairing every structure does is make it uniform, so it becomes a constant rather than a difference between structure sources. docs/structure_preparation.md records this in full.

Checks

README.rst parses under docutils with no warnings other than a missing Pygments package. The four Quick start commands were run on 1GDW, and the Python loop under Using the features in a model was run over two structures, in an environment created from the updated environment.yml.