Linkage#

Linkage definitions#

A linkage is a connection between two _molecules_. At its core each linkage simply defines two atoms that should be connected, and what atoms to remove in the process. It is a “pseudo” chemical reaction, so to speak.

Building on the CHARMM force field, BuildAMol distinguishes two kinds of linkages: patches and recipies.

A patch is a linkage that can be applied purely geometrically and does not require numeric optimization. This is because a patch includes geometric data in form of _internal coordinates_ of the atoms in the immediate vicinity of the newly formed bond. Using this data, BuildAMol is able to attach molecule to one another through simple matrix transformations. Conesquently, patches are the most efficient way to connect molecules and are preferable to recipes - the other type of linkage.

A recipe on the other hand is a linkage that requires numeric optimization. This is because a recipe does not include any geometric data, but only the atoms that should be connected. The numeric optimization is then used to find the optimal (or at least suitable) conformation. This is useful for most users who wish to define their own linkage types, but who will likely not wish to painstakingly define the detailed geometry of angles and dihedrals of the atom neighborhood.

The distinction between patches and recipies is purely nominal, as both are represented by the Linkage class. However, there are functional wrappers available to create either a patch or recipe, respectively, which require different arguments (to make sure they are not forgotten and to make the code more readable).

from buildamol import recipe

# Create a custom recipe
my_link = recipe(
    atom1 = "C1",
    atom2 = "O4",
    delete_in_target = ["O1", "HO1"],
    delete_in_source = ["HO4"],
    id = "my_link"
)

Pre-defined patches#

BuildAMol comes with a number of pre-defined patches from the CHARMM force field. These can be accessed through the resources module:

from buildamol import resources

# Get a list of all pre-defined patches
patches = resources.available_patches()

# Check for a specific patch
resources.has_patch("some_patch")

# Get a specific patch
my_patch = resources.get_patch("some_patch")

A custom linkage can be added to the list of pre-defined patches by using the add_patch function:

# add the above defined my_link to the list of pre-defined patches
resources.add_patch(my_link)

Note

Despite the use of “patch” in the function nomenclature, there is no difference between a patch and a recipe in terms of how they are used. Patches and Recipies are represented by the same data class and thus behave identically. Hence, there are also functional wrappers with the “linkage” available that can be used instead (if a user feels more comfortable with this) - they perform the same function.

resources.add_linkage(my_link)
# performs the same as
resources.add_patch(my_link)

# check for a specific linkage
resources.has_linkage("my_link")
# performs the same as
resources.has_patch("my_link")

# etc.

Pre-defined patches can be accessed directly by their id and need not be obtained first through the resources module. They can be directly passed to the Molecule’s attach method or any other function that requires a linkage:

import buildamol as bam

mol1 = bam.read_pdb("my_molecule.pdb")
mol2 = bam.read_pdb("my_other_molecule.pdb")

# Attach mol2 to mol1 using the pre-defined patch "some_patch"
mol1.attach(mol2, "some_patch")

# works the same as doing
some_patch = bam.get_patch("some_patch")
mol1.attach(mol2, some_patch)
class buildamol.core.Linkage.Linkage(id=None, description: str = None, automatically_delete_downstream_atoms: bool = False)[source]#

Bases: AbstractEntity_with_IC

Using the Linkage class, a template reaction instruction is stored for attaching molecules to one another.

Parameters:

  • id (str, optional) – The ID of the linkage.

  • description (str, optional) – An additional description of the linkage.

  • automatically_delete_downstream_atoms (bool, optional) – Whether to automatically delete all atoms downstream of a linker and deleted atom. This is useful for linkers that are part of a larger group that should be removed (e.g. a carboxyl group) without having to specify all atoms to delete manually.

id#

The ID of the linkage.

Type:

str

bond#

The bond to form between the two molecules.

Type:

tuple of str

internal_coordinates#

The internal coordinates of the atoms in the immediate vicinity of the newly formed bond.

Type:

list of InternalCoordinate

deletes#

The atom IDs to delete in a tuple of lists where the first list contains the atom IDs to delete from the first structure (target) and the second one from the second structure (source)

Type:

tuple of list of str

atoms#

The atom IDs of the atoms in the linkage.

Type:

list of str

add_delete(id, _from: str = None)[source]#

Add an atom ID to delete

Parameters:

  • id (str) – The atom ID to delete.

  • _from (str, optional) – The structure from which to delete the atom. Can be either “source” or “target”. If not provided, the structure is inferred from the atom ID, in which case either 1 (target) or 2 (source) must be the first character of the ID.

add_id_to_delete(id, _from: str = None)#

Add an atom ID to delete

Parameters:

  • id (str) – The atom ID to delete.

  • _from (str, optional) – The structure from which to delete the atom. Can be either “source” or “target”. If not provided, the structure is inferred from the atom ID, in which case either 1 (target) or 2 (source) must be the first character of the ID.

add_internal_coordinates(ic)[source]#

Add an internal coordinate to the residue

apply(target, source, target_residue=None, source_residue=None)[source]#

Apply the linkage to the two molecules. This will delete the atoms that should be deleted and form the bond between the two molecules.

Note that this method does NOT perform any kind of geometric changes to the molecules themselves. It only adds the bond between the two molecules. It also does NOT merge the two molecules into one! Use the Molecule.attach method (or the connect toplevel function) to actually connect two molecules!

Parameters:

  • target (Molecule) – The first molecule.

  • source (Molecule) – The second molecule.

  • target_residue (Residue, optional) – The residue in the target molecule to which the source molecule will be patched. By default, the attach_residue in the target molecule will be used.

  • source_residue (Residue, optional) – The residue in the source molecule that will be patched into the target molecule. By default, the attach_residue in the source molecule will be used.

apply_bond(target, source, target_residue=None, source_residue=None)[source]#

Form the bond between the two molecules.

Note that this method does NOT perform any kind of geometric changes to the molecules themselves. It only adds the bond between the two molecules. It also does NOT merge the two molecules into one! Use the Molecule.attach method (or the connect toplevel function) to actually connect two molecules!

Parameters:

  • target (Molecule) – The first molecule.

  • source (Molecule) – The second molecule.

  • target_residue (Residue, optional) – The residue in the target molecule to which the source molecule will be patched. By default, the attach_residue in the target molecule will be used.

  • source_residue (Residue, optional) – The residue in the source molecule that will be patched into the target molecule. By default, the attach_residue in the source molecule will be used.

apply_deletes(target=None, source=None, target_residue=None, source_residue=None)[source]#

Delete atoms that should be deleted from the molecules as part of the linkage.

Parameters:

  • target (Molecule) – The first molecule.

  • source (Molecule) – The second molecule.

  • target_residue (Residue, optional) – The residue in the target molecule to which the source molecule will be patched. By default, the attach_residue in the target molecule will be used.

  • source_residue (Residue, optional) – The residue in the source molecule that will be patched into the target molecule. By default, the attach_residue in the source molecule will be used.

property atom1: str#

The atom ID of the first atom in the bond.

property atom2: str#

The atom ID of the second atom in the bond.

property bond: tuple#

The bond to form between the two molecules.

can_apply(target, source, target_residue=None, source_residue=None) → bool[source]#

Check if the linkage can be applied to the two molecules.

Parameters:

  • target (Molecule) – The first molecule.

  • source (Molecule) – The second molecule.

  • target_residue (Residue, optional) – The residue in the target molecule to which the source molecule will be patched. By default, the attach_residue in the target molecule will be used.

  • source_residue (Residue, optional) – The residue in the source molecule that will be patched into the target molecule. By default, the attach_residue in the source molecule will be used.

Returns:

True if the linkage can be applied, False otherwise.

Return type:

bool

can_be_source(molecule, residue=None)[source]#

Check if the linkage can be applied to the molecule as the source.

Parameters:

  • molecule (Molecule) – The molecule to check.

  • residue (Residue, optional) – The residue in the molecule to which the source molecule will be patched. By default, the attach_residue in the molecule will be used.

Returns:

True if the linkage can be applied to the molecule, False otherwise.

Return type:

bool

can_be_target(molecule, residue=None)[source]#

Check if the linkage can be applied to the molecule as the target.

Parameters:

  • molecule (Molecule) – The molecule to check.

  • residue (Residue, optional) – The residue in the molecule to which the source molecule will be patched. By default, the attach_residue in the molecule will be used.

Returns:

True if the linkage can be applied to the molecule, False otherwise.

Return type:

bool

copy() → Linkage[source]#

Create a copy of the Linkage instance.

Returns:

A new Linkage instance that is a copy of the original.

Return type:

Linkage

property deletes#

Returns the atom IDs to delete in a tuple of lists where the first list contains the atom IDs to delete from the first structure (target) and the second one from the second structure (source)

classmethod from_bond(bond: Bond, id: str = None, description: str = None, automatically_delete_downstream_atoms: bool = True) → Linkage[source]#

Make a new Linkage instance from a bond.

Parameters:

  • bond (Bond) – The bond to form between the two atoms.

  • id (str, optional) – The ID of the linkage.

  • description (str, optional) – An additional description of the linkage.

classmethod from_functional_groups(emol: Molecule, egroup: FunctionalGroup, nmol: Molecule, ngroup: FunctionalGroup, automatically_delete_downstream_atoms: bool = True)[source]#

Create a new Linkage instance from two functional groups.

Parameters:

  • emol (Molecule) – The first (target) molecule that houses the electrophile. The attach residue will be used as reference residue to match atoms to the functional group.

  • egroup (FunctionalGroup) – The electrophile functional group.

  • nmol (Molecule) – The second (source) molecule that houses the nucleophile. The attach residue will be used as reference residue to match atoms to the functional group.

  • ngroup (FunctionalGroup) – The nucleophile functional group.

classmethod from_json(filename: str)[source]#

Make a new Linkage instance from a JSON file.

Parameters:

filename (str) – The JSON filename.

classmethod from_xml(filename: str)[source]#

Make a new Linkage instance from an XML file.

Parameters:

filename (str) – The XML filename.

identify_atoms(target, source, target_residue=None, source_residue=None)[source]#

Identify the atoms in the two molecules that are part of the linkage. If any of the binder or deleter atoms could not be identified, this method will raise a ValueError.

Parameters:

  • target (Molecule) – The first molecule.

  • source (Molecule) – The second molecule.

  • target_residue (Residue, optional) – The residue in the target molecule to which the source molecule will be patched. By default, the attach_residue in the target molecule will be used.

  • source_residue (Residue, optional) – The residue in the source molecule that will be patched into the target molecule. By default, the attach_residue in the source molecule will be used.

Returns:

  • atom1 (Atom) – The first atom in the bond.

  • atom2 (Atom) – The second atom in the bond.

  • delete_in_target (list of Atom) – The atoms to delete in the target molecule.

  • delete_in_source (list of Atom) – The atoms to delete in the source molecule.

reverse(inplace: bool = True) → Linkage[source]#

Reverse the linkage, i.e. swap the atoms in the bond and the deletes.

Parameters:

inplace (bool, optional) – If True, the linkage will be reversed in place. If False, a new reversed linkage will be returned. Default is True.

Returns:

The reversed linkage if inplace is False, otherwise None.

Return type:

Linkage

to_json(filename: str)[source]#

Write the Linkage instance to a JSON file.

Parameters:

filename (str) – The JSON filename.

to_xml(filename: str)[source]#

Write the Linkage instance to an XML file.

Parameters:

filename (str) – The XML filename.

buildamol.core.Linkage.linkage(atom1, atom2, delete_in_target=None, delete_in_source=None, internal_coordinates: dict = None, id: str = None, description: str = None, automatically_delete_downstream_atoms: bool = True) → Linkage[source]#

Make a new Linkage instance to connect two molecules together.

Parameters:

  • atom1 (str) – The atom in the first (target) molecule to connect.

  • atom2 (str) – The atom in the second (source) molecule to connect.

  • delete_in_target (str or tuple of str, optional) – The atom(s) in the first molecule to delete. If not provided, any Hydrogen atom bound to atom1 will be deleted.

  • delete_in_source (str or tuple of str, optional) – The atom(s) in the second molecule to delete. If not provided, any Hydrogen atom bound to atom2 will be deleted.

  • internal_coordinates (dict, optional) –

    The internal coordinates of the atoms in the immediate vicinity of the newly formed bond. If provided, the link can be applied purely geometrically and will not require numeric optimization. If provided, this must be a dictionary where keys are tuples of four atoms ids and values tuples containing (in order):

    • the bond length between the first and second atom (first and third in case of an improper)

    • the bond length between the third and fourth atom

    • the bond angle between the first, second and third atom

    • the bond angle between the second, third and fourth atom

    • the dihedral angle between the first, second, third and fourth atom

    • True if the internal coordinate is improper, False otherwise

  • id (str, optional) – The ID of the linkage.

  • description (str, optional) – A description of the linkage.

  • automatically_delete_downstream_atoms (bool, optional) – Whether to automatically delete all atoms downstream of a linker and deleted atom. This is useful for linkers that are part of a larger group that should be removed (e.g. a carboxyl group) without having to specify all atoms to delete manually.

Returns:

The new linkage instance.

Return type:

Linkage

buildamol.core.Linkage.patch(atom1, atom2, delete_in_target, delete_in_source, internal_coordinates: dict, id: str = None, description: str = None) → Linkage[source]#

Make a new Linkage instance that describes a “patch” between two molecules. A patch is a linkage that can be applied purely geometrically and does not require numeric optimization. As such, it requires the internal coordinates of the atoms in the immediate vicinity of the newly formed bond.

Parameters:

  • atom1 (str or tuple of str) – The atom in the first (target) molecule to connect.

  • atom2 (str or tuple of str) – The atom in the second (source) molecule to connect.

  • delete_in_target (str or tuple of str) – The atom(s) in the first molecule to delete.

  • delete_in_source (str or tuple of str) – The atom(s) in the second molecule to delete.

  • internal_coordinates (dict, optional) –

    The internal coordinates of the atoms in the immediate vicinity of the newly formed bond. If provided, the link can be applied purely geometrically and will not require numeric optimization. If provided, this must be a dictionary where keys are tuples of four atoms ids and values tuples containing (in order):

    • the bond length between the first and second atom (first and third in case of an improper)

    • the bond length between the third and fourth atom

    • the bond angle between the first, second and third atom

    • the bond angle between the second, third and fourth atom

    • the dihedral angle between the first, second, third and fourth atom

    • True if the internal coordinate is improper, False otherwise

  • id (str, optional) – The id of the linkage.

  • description (str, optional) – A description of the linkage.

Returns:

The new linkage.

Return type:

Linkage

buildamol.core.Linkage.recipe(atom1, atom2, delete_in_target=None, delete_in_source=None, id: str = None, description: str = None, automatically_delete_downstream_atoms: bool = True) → Linkage[source]#

Make a new Linkage instance that describes a “recipe” to connect two molecules. A recipe is a linkage that can be applied numerically and requires numeric optimization as it does not have the internal coordinates of the atoms in the immediate vicinity of the newly formed bond.

Parameters:

  • atom1 (str or tuple of str) – The atom in the first (target) molecule to connect.

  • atom2 (str or tuple of str) – The atom in the second (source) molecule to connect.

  • delete_in_target (str or tuple of str) – The atom(s) in the first molecule to delete. If not provided, any Hydrogen atom bound to atom1 will be deleted.

  • delete_in_source (str or tuple of str) – The atom(s) in the second molecule to delete. If not provided, any Hydrogen atom bound to atom2 will be deleted.

  • id (str, optional) – The id of the linkage.

  • description (str, optional) – A description of the linkage.

  • automatically_delete_downstream_atoms (bool, optional)

Returns:

The new linkage.

Return type:

Linkage