biobuild 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, biobuild 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, biobuild 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 biobuild 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#

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

from biobuild 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 biobuild as bb

mol1 = bb.read_pdb("my_molecule.pdb")
mol2 = bb.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 = bb.get_patch("some_patch")
mol1.attach(mol2, some_patch)
class biobuild.core.Linkage.Linkage(id=None, description: str = None)[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.

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

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.

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_json(filename: str)[source]#

Make a new Linkage instance from a JSON file.

Parameters:

filename (str) – The JSON filename.

to_json(filename: str)[source]#

Write the Linkage instance to a JSON file.

Parameters:

filename (str) – The JSON filename.

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

Make a new Linkage instance to connect two molecules together.

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, 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.

Returns:

The new linkage instance.

Return type:

Linkage

biobuild.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

biobuild.core.Linkage.recipe(atom1, atom2, delete_in_target=None, delete_in_source=None, id: str = None, description: str = None) → 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.

Returns:

The new linkage.

Return type:

Linkage