haddock.libs.libligand module
Ligand topology utilities.
- haddock.libs.libligand.extract_ligand(pdb_file: str | Path, resnames: list[str], dest: str | Path) Path[source]
Write a PDB with a single copy of each of the given residue names.
prodrg can only handle a single small molecule. When the ligand is part of a larger system (e.g. a protein/ligand complex), the surrounding macromolecule must be stripped out before prodrg is run, otherwise it fails to generate topology and parameter files.
When a ligand is present in several copies (same residue name, different residue numbers/chains), all copies share the same topology, so only the first copy of each residue name is kept to avoid feeding prodrg redundant (and potentially too many) atoms.
Atoms that CNS mislabelled as a two-letter metal element (e.g. a phosphate
PBwritten with elementPb) are corrected back to their real single-letter element so prodrg can parametrise them.- Parameters:
pdb_file (FilePath) – Path to the input PDB file (may contain a full system).
resnames (list[str]) – Residue names to keep (typically the unknown ligand residues).
dest (FilePath) – Path to the PDB file to write with only the selected residues.
- Returns:
Path – Path to the written ligand-only PDB file (
dest).
- haddock.libs.libligand.find_chain_residues(pdb_file: str | Path, resnames: list[str], cutoff: float = 2.0) list[str][source]
Find the residues covalently linked to their neighbours in a chain.
Such residues (e.g. a modified amino acid within a protein) cannot be parameterised by prodrg, which treats every residue as a free molecule and does not create the bonds to the rest of the chain.
A residue is linked when its N (or P) is within
cutoffof the C (or O3’) of the previous residue in the same chain, or its C (or O3’) withincutoffof the N (or P) of the next one.- Parameters:
pdb_file (FilePath) – PDB file containing the residues.
resnames (list[str]) – Names of the residues to check.
cutoff (float) – Maximum bond length, in Angstrom.
- Returns:
list[str] – The linked residues, as
"<resname> (chain <chain>, residue <resid>)".
- haddock.libs.libligand.find_linked_sugars(pdb_file: str | Path, resnames: list[str], cutoff: float = 2.0) list[str][source]
Find the sugars linked to another residue by a glycosidic bond.
Like residues within a chain, such sugars (e.g. an unsupported glycan unit bound to a protein) cannot be parameterised by prodrg, which does not create the glycosidic bonds.
A residue is a sugar when it has the ring atoms of a pyranose or a furanose (see
_SUGAR_RINGS). It is linked when its anomeric carbon (C1, or C2 for ketoses such as sialic acids) is withincutoffof an O, N or S atom of another residue (e.g. ASN ND2, or O4 of another sugar), or when one of its O atoms is withincutoffof the anomeric carbon of another sugar.- Parameters:
pdb_file (FilePath) – PDB file containing the residues.
resnames (list[str]) – Names of the residues to check.
cutoff (float) – Maximum bond length, in Angstrom.
- Returns:
list[str] – The linked sugars and their partners, as
"<resname> (chain <chain>, residue <resid>) linked to <partner>".
- haddock.libs.libligand.identify_unknown_hetatms(pdb_file: str | Path) list[str][source]
Return residue names in a PDB that are not in the supported residues.
- Parameters:
pdb_file (FilePath) – Path to the PDB file to inspect.
- Returns:
list[str] – Unique residue names not found in the supported residues set, in order of first appearance.
- haddock.libs.libligand.ion_naming_hint(pdb_file: str | Path, resnames: list[str]) str[source]
Explain the ion naming for unknown residues that look like ions.
A residue looks like an ion when it consists of a single atom, or when its name is an ion element followed by a charge that is not defined (e.g.
CU3, orLIwithout a charge).- Parameters:
pdb_file (FilePath) – PDB file containing the residues.
resnames (list[str]) – Names of the unknown residues.
- Returns:
str – The explanation, or an empty string if no residue looks like an ion.
- haddock.libs.libligand.run_prodrg(pdb_file: str | Path, output_dir: str | Path, ligand_resnames: list[str] | None = None) tuple[Path, Path][source]
Run prodrg on a ligand PDB and write CNS topology and parameter files.
The resulting files are written to
output_dirnamed after the input PDB stem.prodrg can only process a single small molecule at a time. When
ligand_resnameslists several distinct ligands, prodrg is run once per ligand (on a single extracted copy of each) and the resulting topology and parameter files are concatenated into one.topand one.param. Each ligand is given a uniqueCNSSEPcharacter so that prodrg generates non-overlapping atom type names across the concatenated files; the characters used are also chosen to avoid the separators already present in the built-incofactors.toptopology, so a single auto-generated ligand likewise cannot clash with the cofactor atom types.- Parameters:
pdb_file (FilePath) – Path to the ligand PDB file. It may also be a full system (e.g. a protein/ligand complex), in which case
ligand_resnamesmust be provided so that only the ligand residues are passed to prodrg.output_dir (FilePath) – Directory where the named
.topand.paramfiles are written.ligand_resnames (Optional[list[str]]) – Residue names of the ligand(s) to extract before running prodrg. When provided, each distinct ligand is extracted (a single copy) and passed to prodrg separately, stripping out the rest of the system (e.g. the protein). When
None, the wholepdb_fileis passed to prodrg unchanged.
- Returns:
tuple[Path, Path] – Paths to the written
<stem>_prodrg.topand<stem>_prodrg.paramfiles.- Raises:
RuntimeError – If prodrg exits with a non-zero return code or the expected output files are not created.