ResidueDefinition

class openff.pablo.ResidueDefinition(residue_name: str | None, description: str, linking_bond: BondDefinition | None, crosslink: BondDefinition | None, atoms: tuple[AtomDefinition, ...], bonds: tuple[BondDefinition, ...], virtual_sites: tuple[str, ...])[source]

Bases: object

Description of a residue from the Chemical Component Dictionary (CCD).

Attributes

residue_name

The 3-letter residue code used in PDB files, or None if only used anonymously.

description

A longer description of the residue

linking_bond

Description of how this residue may bond to its neighbours in a polymer

crosslink

Optional description of a crosslink between this residue and another.

atoms

The atom definitions that make up this residue.

bonds

The bond definitions that make up this residue

virtual_sites

Atom names that represent virtual sites.

Constructor Methods

anon_from_molecule

Create an anoymous ResidueDefinition from an openff.toolkit.Molecule.

anon_from_sdf

Create an anonymous residue definition from an SDF file of a single molecule

anon_from_smiles

Create an anonymous ResidueDefinition from a SMILES string.

anon_from_smiles_marked_leaving

Create an anonymous ResidueDefinition from a partially mapped SMILES.

from_capped_molecule

Create a linking ResidueDefinition from an openff.toolkit.Molecule

from_molecule

Create a ResidueDefinition from an openff.toolkit.Molecule.

from_smiles

Create a ResidueDefinition from a mapped SMILES string.

Instance and Static Methods

atoms_bonded_to

Iterator over atoms bonded to the one with the given canonical name.

bonds_to

All bonds to the given atom, ordered with atom1 as the given atom.

deprotonated_at

Return a copy of self with proton name abstracted.

protonated_at

Return a copy of self with heavy_atom_name protonated by proton_name.

react

Perform a SMARTS reaction on some residue definitions

replace

Return a copy of self with the specified attributes replaced.

to_openff_molecule

Create a Molecule representing the complete, unlinked residue.

vary_protonation

Compute all combinations of the specified protonation variants

visualize

with_synonyms

Return a copy of self with the given synonyms added

Properties

canonical_name_to_atom

Map from each atoms' name and synonyms to the atom definition.

is_anonymous

True if atom names may be used for matching, False otherwise.

n_core_atoms

The number of non-leaving atoms in the residue.

n_expected_atoms

The number of atoms that a matching residue without any linkages has.

name_to_atom

Map from each atoms' name and synonyms to the atom definition.
classmethod anon_from_molecule(molecule: Molecule, description: str | None = None, virtual_sites: Collection[str] = ()) → Self[source]

Create an anoymous ResidueDefinition from an openff.toolkit.Molecule.

Parameters:

  • molecule – The Molecule object. Leaving atoms are identified from the atom metadata; atom’s whose metadata includes a truthy value for the key "leaving_atom" are marked as leaving atoms.

  • description – An optional string describing the residue. Taken from molecule "description" property if None. See openff.pablo.ResidueDefinition.description

  • virtual_sites – Virtual sites expected by the residue. See openff.pablo.ResidueDefinition.virtual_sites

classmethod anon_from_sdf(file: str | Path | TextIO, description: str | None = None) → Self[source]

Create an anonymous residue definition from an SDF file of a single molecule

classmethod anon_from_smiles(smiles: str, leaving_atoms: Collection[int] = (), virtual_sites: Collection[str] = (), description: str | None = None) → Self[source]

Create an anonymous ResidueDefinition from a SMILES string.

Parameters:
classmethod anon_from_smiles_marked_leaving(smiles: str, *, virtual_sites: Collection[str] = (), description: str | None = None) → Self[source]

Create an anonymous ResidueDefinition from a partially mapped SMILES.

The mapped atoms are treated as leaving atoms.

Parameters:
atoms: tuple[AtomDefinition, ...]

The atom definitions that make up this residue.

Atoms may be marked as leaving only if they are associated with a linking or crosslinking bond; see the API documentation for those fields. All atoms must have unique canonical names.

atoms_bonded_to(atom_name: str) → Iterator[str][source]

Iterator over atoms bonded to the one with the given canonical name.

bonds: tuple[BondDefinition, ...]

The bond definitions that make up this residue

bonds_to(atom_name: str) → Iterator[BondDefinition][source]

All bonds to the given atom, ordered with atom1 as the given atom.

property canonical_name_to_atom: dict[str, AtomDefinition]

Map from each atoms’ name and synonyms to the atom definition.

Optional description of a crosslink between this residue and another.

A crosslink is a bond between this residue and another. Crosslinks differ from linking bonds primarily because they may occur between residues that are do not appear sequentially in the PDB file. Crosslinks cannot occur within a residue; use a bond or residue variant instead.

If the residue does not form cross links, None. Otherwise, a BondDefinition. The atom1 and atom2 attributes give the canonical atom names of the atoms that form the crosslink. atom1 is the name of the atom in this residue, and atom2 is in the other residue. Any atoms that the bond between residues replaces should be marked as atom.leaving=True; there must be either zero or one leaving fragments for each atom in a linking bond for the residue definition to validate, and there must be exactly one for a bond to form.

A crosslink will be formed between two residues if and only if all of the below are true:

  • The two residues’ crosslink attributes are identical except that their atom names are reversed

  • All leaving atoms associated with each residues’ crosslink.atom1 attribute are absent in that residue. Leaving atoms are those that have the AtomDefinition.leaving attribute set to True. A leaving atom is associated with atom a if it is bonded to a, or it is bonded to a leaving atom associated with a.

  • There is at least one leaving atom associated with each cross-linking atom

The charge of linking atoms is not modified; any change in valence is accounted for via the removal of leaving atoms.

deprotonated_at(name: str) → Self[source]

Return a copy of self with proton name abstracted.

The hydrogen with canonical name name is removed, and the formal charge of the atom bonded to it is decremented. If the named atom is not hydrogen, is missing, or is bonded to a number of other atoms other than 1, PabloError is raised.

description: str

A longer description of the residue

classmethod from_capped_molecule(molecule: Molecule, residue_name: str, leaving_atom_indices: Collection[int], linking_bond: BondDefinition, crosslink: BondDefinition | None = None, virtual_sites: Collection[str] = (), description: str | None = None) → Self[source]

Create a linking ResidueDefinition from an openff.toolkit.Molecule

Parameters:
classmethod from_molecule(molecule: Molecule, residue_name: str | None = None, description: str | None = None, linking_bond: BondDefinition | None = None, crosslink: BondDefinition | None = None, virtual_sites: Collection[str] = ()) → Self[source]

Create a ResidueDefinition from an openff.toolkit.Molecule.

Parameters:
classmethod from_smiles(mapped_smiles: str, atom_names: Mapping[int, str], residue_name: str, leaving_atoms: Collection[int] = (), linking_bond: BondDefinition | None = None, crosslink: BondDefinition | None = None, virtual_sites: Collection[str] = (), description: str | None = None) → Self[source]

Create a ResidueDefinition from a mapped SMILES string.

Parameters:
property is_anonymous: bool

True if atom names may be used for matching, False otherwise.

linking_bond: BondDefinition | None

Description of how this residue may bond to its neighbours in a polymer

If the residue is only found as a monomer, None. Otherwise, a BondDefinition. The atom1 and atom2 attributes give the canonical atom names of the atoms that form the linking bond. atom1 is the name of the atom in the residue preceding the bond, and atom2 is in the residue after the bond. Any atoms that the bond between residues replaces should be marked as atom.leaving=True; there must be either zero or one leaving fragments for each atom in a linking bond for the residue definition to validate, and there must be exactly one for a bond to form.

A linking bond will be formed to join two residues if and only if all of the below are true:

  • The residues’ atom records are sequential in the PDB file

  • The residues have the same chain ID

  • There is no TER record between the residues in the PDB file

  • The two residues have identical linking_bond attributes

  • All leaving atoms associated with linking_bond.atom1 are absent in the first encountered residue, and all leaving atoms associated with linking_bond.atom2 are absent in the latter residue. Leaving atoms are those that have the AtomDefinition.leaving attribute set to True. A leaving atom is associated with atom a if it is bonded to a, or it is bonded to a leaving atom associated with a.

  • There is at least one leaving atom associated with each linking atom

The charge of linking atoms is not modified; any change in valence is accounted for via the removal of leaving atoms.

property n_core_atoms: int

The number of non-leaving atoms in the residue.

Excludes virtual sites. A matching residue can have no fewer than this many atoms.

property n_expected_atoms: int

The number of atoms that a matching residue without any linkages has.

In practice, the number of atoms including leaving atoms, plus the number of virtual sites. A residue with linkages can have no more than this many atoms.

property name_to_atom: dict[str, AtomDefinition]

Map from each atoms’ name and synonyms to the atom definition.

protonated_at(heavy_atom_name: str, proton_name: str, ignore_synonym_clashes: bool = False) → Self[source]

Return a copy of self with heavy_atom_name protonated by proton_name.

The formal charge of the atom with canonical name heavy_atom_name is incremented, a new hydrogen atom named proton_name is added, and a bond is created between the two named atoms. If the heavy atom is missing or the new proton name clashes with an existing name or synonym, PabloError is raised. The new atom has the same value for the leaving attribute as the heavy atom. The synonym clash check may be suppressed with the ignore_synonym_clashes argument, but the canonical names are always checked.

static react(reactants: Sequence[ResidueDefinition], reactant_smarts: Sequence[str], product_smarts: Sequence[str], product_residue_names: Sequence[str | None] | None = None, product_descriptions: Sequence[str | None] | None = None, product_linking_bonds: Sequence[BondDefinition | None] | None = None, product_crosslinks: Sequence[BondDefinition | None] | None = None, product_virtual_sites: Sequence[Collection[str]] | None = None) → list[tuple[ResidueDefinition, ...]][source]

Perform a SMARTS reaction on some residue definitions

Parameters:

  • reactants – The residue definitions involved in the reaction. Names and synonyms for the products are taken from these. Chemical information is also derived from these, but may be modified by the reaction.

  • reactant_smarts – Mapped SMARTS patterns identifying atoms in the reactants that will be involved in the reaction. There may be more or fewer of these than reactants to allow for complex and intramolecular reactions.

  • product_smarts – Mapped SMARTS patterns describing any altered chemistry in the products. All atom mappings in the reactant smarts must be present in a product SMARTS. Each product SMARTS corresponds to a single product ResidueDefinition.

  • product_residue_names – The residue names of the products. One for each product SMARTS. May be None or omitted, in which case the product is anonymous — note that this means atom names in the reactants are discarded. If there are fewer residue names than product SMARTS, any unnamed products are made anonymous.

  • product_descriptions – The descriptions of the products. If there are fewer descriptions than product SMARTS, the given descriptions are assigned to the first products.

  • product_linking_bonds – The linking bonds of the products. If there are fewer linking bonds than product SMARTS, the given linking bonds are assigned to the first products. Must be None or omitted if the product is anonymous.

  • product_crosslinks – The crosslinks of the products. If there are fewer crosslinks than product SMARTS, the given crosslinks are assigned to the first products. Must be None or omitted if the product is anonymous.

  • product_virtual_sites – The virtual sites of the products. If there are fewer virtual sites than product SMARTS, the given virtual sites are assigned to the first products.

replace(*, residue_name: str | __UNSET__ = __UNSET__(), description: str | __UNSET__ = __UNSET__(), linking_bond: BondDefinition | None | __UNSET__ = __UNSET__(), crosslink: BondDefinition | None | __UNSET__ = __UNSET__(), atoms: Iterable[AtomDefinition] | __UNSET__ = __UNSET__(), bonds: Iterable[BondDefinition] | __UNSET__ = __UNSET__(), virtual_sites: Iterable[str] | __UNSET__ = __UNSET__()) → Self[source]

Return a copy of self with the specified attributes replaced.

residue_name: str | None

The 3-letter residue code used in PDB files, or None if only used anonymously.

to_openff_molecule() → Molecule[source]

Create a Molecule representing the complete, unlinked residue.

vary_protonation(*, acidic: Iterable[str] = (), basic: Iterable[tuple[str, str]] = (), ignore_synonym_clashes: bool = False, skip_errors: bool = False) → list[Self][source]

Compute all combinations of the specified protonation variants

The first element of the returned list is guaranteed to be the unmodified starting residue definition; to get a list of just the new variants, use resdef.vary_protonation(...)[1:].

Note that all combinations of protonations and deprotonations are generated; this means that if acidic has length n and basic has length m, 2**(n+m) variants will be generated.

Parameters:

  • acidic – Each element specifies an atom name to remove, decrementing the formal charge on the neighbouring heavy atom. Multiply bonded, unbonded, missing or non-hydrogen atoms raise PabloError unless skip_errors is True.

  • basic – Each tuple specifies an atom name to protonate (increment the formal charge and form a bond) and the name of the added proton. Missing heavy atoms or new atom names that clash with existing names raise PabloError unless skip_errors is True.

  • ignore_synonym_clashes – If set to True, protons added by the basic argument may have names that clash with the synonyms of other atoms. This can be useful in the early stages of a multi-step residue definition patching process. Added protons may never have names that clash with the canonical names of other atoms.

  • skip_errors – If set to True, missing, clashing, or improperly bonded atoms are skipped rather than raising PabloError.

virtual_sites: tuple[str, ...]

Atom names that represent virtual sites.

All these names must be present for the residue definition to match.

visualize(*, width: int = -1, height: int = 300, highlight: Iterable[str] = ()) → SVG[source]
with_synonyms(synonyms: Mapping[str, Sequence[str]]) → Self[source]

Return a copy of self with the given synonyms added

synonyms is a mapping from canonical atom names to its additional synonyms. Existing synonyms are preserved.