Provenance in the PDBQT files

A PDBQT file travels without the session that made it. Its header records how it was made from the PDB entry, line by line.

Every receptor and ligand file ADapt writes starts with REMARK lines. These records describe what was done to the PDB data: which biomolecule was used, which residues were mutated or completed, which alternate locations were kept, how hydrogens and charges were assigned. Anyone holding the file can see how it was built without having the session that built it, and can rebuild the same receptor, with ADapt or with ADFR's command line.

A receptor header

Written from the ASU of 6GGD, with zinc A:401 in the receptor at an edited charge of +1.5, SER 96 of chain A mutated to ALA, LYS 120 of chain A left as is, and the A location chosen for SER 166:

REMARK 850 AGFR version 1.2dev
REMARK 850 AGFR source 6ggd.pdb
REMARK 850 AGFR biomolecule ASU: chains A B
REMARK 850 AGFR mutation A:SER:96:_ -> ALA
REMARK 850 AGFR side chain completed A:ARG:209:_
   …                                     (11 more)
REMARK 850 AGFR altlocs A:SER:166:_ @A (0.42)
REMARK 850 AGFR altlocs A:CYS:182:_ @A (0.57)
   …                                     (12 more)
REMARK 850 AGFR protonated using reduce
REMARK 850 AGFR partial charge assigned using OpenBabel Gasteiger model
REMARK 850 AGFR custom charge for A:ZN:401: = 1.5000
REMARK 850 AGFR end

The receptor records

In the order they appear. A residue is written as chain:name:number:insertion code, for example A:SER:96:_; _ means no insertion code.

Record	What it records	Good to know
`version 1.2dev`	The version of the ADFR suite that prepared the file.	This is ADFR's version string, not ADapt's version nor the `adfr` Python package's (`adfr-0.0.22`); both of those are in the session record.
`source 6ggd.pdb`	The PDB file the receptor was built from.	The PDB id is taken from this name; keep the id as the file name.
`biomolecule ASU: chains A B`	The tab the receptor was written from (ASU, Biomol N, or "ASU and Biomol N"), the chains of the asymmetric unit it uses and, for an assembly built by crystal symmetry, the number of copies: `Biomol 1: chains A, 2 copies`.	Added by ADapt; ADFR's header writer has a commented-out placeholder for it. See biological assembly.
`mutation A:SER:96:_ -> ALA`	Each residue that was mutated: the residue as it is in the PDB file, and the residue it was replaced by.	The new side chain is the best-scoring rotamer. Symmetry copies of the chain are mutated too. See mutations.
`side chain completed A:ARG:209:_`	Each residue whose missing side-chain atoms were rebuilt (best-scoring rotamer).	Lists every completion queued in the file, including those in chains the tab does not contain. A residue set to Include as is is not listed (A:LYS:120 above). See side chains.
`altlocs A:SER:166:_ @A (0.42)`	For each residue with alternate locations in the receptor, the location used and its occupancy.	The only record of which location was used. When locations tie in occupancy, ADFR's default changes from run to run, so this line is how you know. See alternate locations.
`protonated using reduce`	Hydrogens were added by `reduce`.
`partial charge assigned using OpenBabel Gasteiger model`	Partial charges are Gasteiger charges from Open Babel.
`custom charge for A:ZN:401: = 1.5000`	Each ion with a manual charge in the receptor, and the charge it was given.	ADFR reads this from the asymmetric unit, so the line is written when the receptor comes from an ASU or ASU and Biomol N tab. From a Biomol N tab it is missing, but the charge is still in the ion's atom record (the charge column). A blank insertion code is written empty here, not as `_`. ADapt writes the charge actually used; ADFR's command line reports the default here even when `--ionCharges` changed it. See metals.
`end`	The end of the header.

The ligand records

REMARK 850 file prepared by AGFR version 1.2dev
REMARK 850 source .pdb
REMARK 850 AGFR biomolecule Biomol 2: chains B
REMARK 850 AGFR ligand from B:EYB:402:_
REMARK 4 active torsions:
REMARK  status: ('A' for Active; 'I' for Inactive)
REMARK    0  A    between atoms: C10_7 and C18_14
   …

Record	What it records	Good to know
`file prepared by AGFR version 1.2dev`	The ADFR suite version.	As in the receptor.
`source .pdb`	Meant to name the source file.	ADFR leaves the name empty in ligand files; the receptor's `source` line names it.
`biomolecule Biomol 2: chains B`	The tab the ligand was written from, as in the receptor.	Added by ADapt, in every ligand file (one per fragment).
`ligand from B:EYB:402:_`	The residues of the PDB file the ligand was made of, in file order, with their real chain.	Added by ADapt. A ligand of several residues, such as a peptide, takes several lines of four residues each: `ligand from B:SER:10:_ B:THR:11:_ B:GLY:12:_ B:GLY:13:_`, and so on. Each file of a ligand split into fragments names only its own residues.
`4 active torsions` and the `between atoms` lines	The ligand's rotatable bonds, all active, each between two atoms named `NAME_number`.	They match the torsion tree that follows (`ROOT`, `BRANCH`): the flexibility AutoDock will explore.

The ligand's chain. The atom records of a ligand file label its chain A whatever chain it came from, because the identifier is lost in ADFR's Open Babel conversion. The coordinates are those of the chosen fragment, and the ligand from line gives its true chain and residues.

Reading the records

grep '^REMARK 850' 6ggd_rec.pdbqt                  # the whole header
grep 'AGFR biomolecule' *.pdbqt                     # which biomolecule each file came from
grep 'AGFR ligand from' *_lig*.pdbqt                # which residues each ligand file holds
grep -E 'AGFR (mutation|side chain completed)' 6ggd_rec.pdbqt
grep 'AGFR altlocs' 6ggd_rec.pdbqt                  # the conformations that were used

Rebuilding a receptor from its header

Most records correspond to an option of ADFR's command line, so a receptor can be rebuilt without ADapt:

Record	Option of `python -m ADFR.bin.runAGFR -r <file> --toPdbqt`
`biomolecule Biomol 2: …`	`--bioMol 2` (`--bioMol ASU` for the asymmetric unit)
`mutation A:SER:96:_ -> ALA`	`--mutate "A:SER:96::ALA"` (several separated by `;`)
`custom charge for A:ZN:401: = 1.5000`	`--ionCharges "A:ZN:401::1.5"` (see the note below)
hetero groups kept in the receptor	`--heteroToKeep "chid A resnum 401"` (a ProDy selection)
residues removed from the receptor	`--protToRemove "chid C"`
`altlocs …`, side chains left as is	no option: these choices need ADapt or AGFRgui

ADapt's tests check this correspondence: for the same choices, the receptor ADapt writes is byte-identical to the command line's, apart from the biomolecule line. See Checking against ADFR's command line.

An ion charge set on ADFR's command line is misreported in its own header. With --ionCharges "A:ZN:401::1.5", ADFR writes the zinc atom with charge 1.50, but its custom charge line says = 2.0000, the default, because that line is read from the asymmetric unit, which the option does not change. ADapt sets the charge there too, so its header reports the charge actually written. The atom records of the two files are identical (a test checks this).

reduce's choices: the receptor PDB

The protonated using reduce line says that reduce added the hydrogens, not what it decided. For each histidine it chooses the protonation (HD1, HE2 or both), and it may flip the side chain of a histidine, asparagine or glutamine by 180°. Those choices are in the <id>_rec_H.pdb written with every receptor: its header is the PDBQT's, followed by reduce's own USER MOD lines and every atom, hydrogens included:

USER  MOD reduce.3.23.130521 H: found=0, std=0, add=3340, rem=0, adj=160
USER  MOD Set 1.1: L 198 HIS     :     no HD1:sc=   0.771  K(o=1.6,f=-4.4)
USER  MOD Set 3.1: L 190 ASN     :FLIP  amide:sc=   0.105  F(o=-0.34,f=0.18)

The same decisions, and the chain renames made for reduce in an assembly built by symmetry, are in the save's reduce entry in session.json. See the protonated receptor.

What the header does not record

Some facts about a file are not in its header. Every ADapt session keeps them in its session.json (see Writing the PDBQT files):

which hetero groups and waters were kept (their atoms are in the file, but no line says they were chosen);
the version and git commit of ADapt, the adfr package version, and checksums of the ADFR source files that ran;
the input file's checksum, and where it came from (an upload, or an RCSB URL);
every edit, in order, and every file written, with its checksum;
reduce's version and its His/Asn/Gln decisions, which are also in _rec_H.pdb.

← Writing the PDBQT files ADapt and AGFRgui →