The utils package

These are the utility modules of Biobuild. They mostly serve in the background and keep everything going. Most users will not directly need to use these. However, they are documented here for completeness.

Default settings and constants

biobuild.utils.constants.BASE = '/home/docs/checkouts/readthedocs.org/user_builds/biobuild/envs/stable/lib/python3.11/site-packages/biobuild'

The base directory of the package

biobuild.utils.constants.RESOURCES = '/home/docs/checkouts/readthedocs.org/user_builds/biobuild/envs/stable/lib/python3.11/site-packages/biobuild/resources'

The resources directory of the package

biobuild.utils.defaults.DEFAULT_BOND_LENGTH = 1.6

The default length of a bond in Angstrom

biobuild.utils.defaults.DEFAULT_CHARMM_TOPOLOGY_FILE = '/home/docs/checkouts/readthedocs.org/user_builds/biobuild/envs/stable/lib/python3.11/site-packages/biobuild/resources/topology.pkl'

The path to the default CHARMM topology file

biobuild.utils.defaults.DEFAULT_PDBE_COMPONENT_FILES = {'amino_acids': '/home/docs/checkouts/readthedocs.org/user_builds/biobuild/envs/stable/lib/python3.11/site-packages/biobuild/resources/components_amino_acids.pkl', 'base': '/home/docs/checkouts/readthedocs.org/user_builds/biobuild/envs/stable/lib/python3.11/site-packages/biobuild/resources/components_base.pkl', 'lipids': '/home/docs/checkouts/readthedocs.org/user_builds/biobuild/envs/stable/lib/python3.11/site-packages/biobuild/resources/components_lipids.pkl', 'nucleotides': '/home/docs/checkouts/readthedocs.org/user_builds/biobuild/envs/stable/lib/python3.11/site-packages/biobuild/resources/components_nucleotides.pkl', 'small_molecules': '/home/docs/checkouts/readthedocs.org/user_builds/biobuild/envs/stable/lib/python3.11/site-packages/biobuild/resources/components_small.pkl', 'sugars': '/home/docs/checkouts/readthedocs.org/user_builds/biobuild/envs/stable/lib/python3.11/site-packages/biobuild/resources/components_sugars.pkl'}

The paths to the default PDBe component files

biobuild.utils.defaults.DEFAULT_SASA_N = 300

The default number of points used to calculate solvent accessible surface area

biobuild.utils.defaults.DEFAULT_SASA_PROBE_RADIUS = 1.4

The default probe radius for calculating solvent accessible surface area

biobuild.utils.defaults.get_default_instance(key)

Get the default instance of a class

Parameters:

key (str) – The key of the default instance

Returns:

The default instance of the class

Return type:

obj

biobuild.utils.defaults.set_default_instance(key, obj)

Set the default instance of a class

Parameters:

• key (str) – The key of the default instance

• obj – The new default instance

File-format related utilities

Conversion

Functions to convert different data formats

class biobuild.utils.convert.OpenMMBioPythonConverter

Bases: PDBIO

Convert OpenMM data structures to Biopython

biobuild_to_openmm(obj)

Convert a biobuild Molecule to an OpenMM object

Parameters:

obj (object) – The object to convert

Returns:

The converted object

Return type:

object

biopython_to_openmm(obj)

Convert a biopython object to an OpenMM object

Parameters:

obj (object) – The object to convert

Returns:

The converted object

Return type:

object

openmm_to_biopython(topology, positions)

Convert an OpenMM object to a biopython object

Parameters:

obj (object) – The object to convert

Returns:

The converted object

Return type:

object

class biobuild.utils.convert.PDBIO

Bases: object

The base class for intermediary PDB file-based conversions

biopython_to_pdbio(obj)

Store a biopython object in a PDB file

cleanup()

Remove the temporary PDB file

molecule_to_pdbio(obj)

Store a biobuild Molecule in a PDB file

pdbio_to_biopython(id: str = 'temp') → Structure

Convert the internal FileIO to a biopython structure object

class biobuild.utils.convert.PybelBioPythonConverter

Bases: PDBIO

Convert Pybel (openbabel) data structures to Biopython

biobuild_to_pybel(obj)

Convert a biobuild object to a pybel object

Parameters:

obj (object) – The object to convert

Returns:

The converted object

Return type:

object

convert(obj, full_structure: bool = False)

Convert between Biopython and Pybel (openbabel) data structures

Parameters:

• obj (object) – The object to convert. The following conversions are supported: - A pybel Molecule -> biopython Structure - A pybel Residue -> biopython Residue - A pybel Atom -> biopython Atom - A pybel Residue -> biopython Structure (if full_structure=True) - A pybel Atom -> biopython Structure (if full_structure=True)

• full_structure (bool, optional) – If True a new full structure object is made instead of simply the hierarchical class equivalent.

Returns:

The converted object

Return type:

object

pybel_atom_to_biopython(obj)

Convert a pybel Atom to a biopython Atom

Parameters:

obj (pybel.Atom) – The pybel Atom to convert

Returns:

The converted biopython Atom

Return type:

bio.Atom.Atom

pybel_molecule_to_biopython(obj)

Convert a pybel Molecule to a biopython Structure

Parameters:

obj (pybel.Molecule) – The pybel Molecule to convert

Returns:

The converted biopython Structure

Return type:

bio.Structure.Structure

pybel_residue_to_biopython(obj)

Convert a pybel Residue to a biopython Residue

Parameters:

obj (pybel.Residue) – The pybel Residue to convert

Returns:

The converted biopython Residue

Return type:

bio.Residue.Residue

class biobuild.utils.convert.RDKITBiopythonConverter

Bases: PDBIO

A class to convert between RDKit and biopython objects This is done simply by using a temporary PDB pseudo-file

biopython_to_rdkit(obj)

Convert a biopython object to an RDKit object

Parameters:

obj (object) – The object to convert

Returns:

The converted object

Return type:

object

rdkit_to_biopython(obj)

Convert an RDKit object to a biopython object

Parameters:

obj (object) – The object to convert

Returns:

The converted object

Return type:

object

biobuild.utils.convert.is_biopython(obj)

Check if an object is a biopython object

Parameters:

obj (object) – The object to check

Returns:

True if the object is a biopython object, False otherwise

Return type:

bool

biobuild.utils.convert.is_pybel(obj)

Check if an object is a pybel object

Parameters:

obj (object) – The object to check

Returns:

True if the object is a pybel object, False otherwise

Return type:

bool

biobuild.utils.convert.is_rdkit(obj)

Check if an object is an rdkit object

Parameters:

obj (object) – The object to check

Returns:

True if the object is an rdkit object, False otherwise

Return type:

bool

PDB

Auxiliary tools for PDB files.

biobuild.utils.pdb.left_adjust(s, n)

Left adjust a string to a certain length.

Parameters:

• s (str) – The string to adjust.

• n (int) – The length to adjust to.

Returns:

The adjusted string.

Return type:

str

biobuild.utils.pdb.make_atoms_table(mol)

Make a PDB atom table

Parameters:

mol (bb.Molecule) – The molecule to generate the table for.

Returns:

The table

Return type:

str

biobuild.utils.pdb.make_connect_table(mol, symmetric=True)

Make a “CONECT” table for a PDB file. This is necessary since Biopython by default does not do that…

Parameters:

• mol (Molecule) – The molecule to generate the connectivity for.

• symmetric (bool, optional) – Whether to generate symmetric bonds (i.e. if A is bonded to B, then B is bonded to A as well). Default is True. And both are written to the file.

Returns:

connect_lines – The lines to add to the PDB file.

Return type:

str

biobuild.utils.pdb.parse_connect_lines(filename)

Parse “CONECT” lines from a PDB file. This is necessary since Biopython by default does not do that…

Parameters:

filename (str) – The filename to parse.

Returns:

bonds – A list of tuples of atom serial numbers that are bonded.

Return type:

list

biobuild.utils.pdb.right_adjust(s, n)

Right adjust a string to a certain length.

Parameters:

• s (str) – The string to adjust.

• n (int) – The length to adjust to.

Returns:

The adjusted string.

Return type:

str

biobuild.utils.pdb.write_connect_lines(mol, filename)

Write “CONECT” lines to a PDB file. This is necessary since Biopython by default does not do that…

Parameters:

• mol (bb.Molecule) – The molecule to generate the connectivity for.

• filename (str) – The filename to write to.

biobuild.utils.pdb.write_pdb(mol, filename, symmetric: bool = True)

Write a molecule to a PDB file.

Parameters:

• mol (Molecule) – The molecule to write.

• filename (str) – The filename to write to.

• symmetric (bool, optional) – Whether to write the molecule in a symmetric way, by default True.

CIF

Functions to work with CIF files.

biobuild.utils.cif.make_bond_lines(mol)

Generate a list of lines for a CIF file that describe the connectivity of the molecule.

Parameters:

mol (bb.Molecule) – The molecule to generate the connectivity for.

Returns:

lines – A list of lines that describe the connectivity of the molecule.

Return type:

list

biobuild.utils.cif.make_bond_table(mol, fmt_header: str = '_bond')

Generate a table of bond information for a molecule.

Parameters:

• mol (bb.Molecule) – The molecule to generate the connectivity for.

• fmt_header (str, optional) – The format string to use for the header of the table, by default “_bond”

Returns:

table – The table of bond information.

Return type:

str

biobuild.utils.cif.make_header(fmt_header: str = '_bond')

Generate a header for a CIF file.

Parameters:

fmt_header (str, optional) – The format string to use for the header of the table, by default “_bond”

Returns:

header – The header of the table.

Return type:

str

biobuild.utils.cif.parse_bond_table(filename, fmt_header: str = '_bond')

Parse the bond table from a biobuild generated CIF file.

biobuild.utils.cif.write_bond_table(mol, filename, fmt_header: str = '_bond')

Write a bond table to a CIF file.

Parameters:

• mol (bb.Molecule) – The molecule to generate the connectivity for.

• filename (str) – The filename to write the CIF file to.

• fmt_header (str, optional) – The format string to use for the header of the table, by default “_bond”

Structure-related utilities

IC

Abstract classes for storing force field data from CHARMM topology and parameter files

class biobuild.utils.ic.InternalCoordinates(atom1: str, atom2: str, atom3: str, atom4: str, bond_length_12: float, bond_length_34: float, bond_angle_123: float, bond_angle_234: float, dihedral: float, bond_length_13: float = None, improper: bool = False)

Bases: object

A representation of a single Internal Coordinate

Parameters:

• atom1 – The first atom in the internal coordinate

• atom2 – The second atom in the internal coordinate

• atom3 – The third atom in the internal coordinate

• atom4 – The fourth atom in the internal coordinate

• bond_length_12 – The bond length between atoms 1 and 2

• bond_length_34 – The bond length between atoms 3 and 4

• bond_angle_123 – The bond angle between atoms 1, 2 and 3

• bond_angle_234 – The bond angle between atoms 2, 3 and 4

• dihedral – The dihedral angle between atoms 1, 2, 3 and 4

• bond_length_13 – The bond length between atoms 1 and 3 (optional, for impropers)

• improper – Whether the internal coordinate is an improper (optional)

property angles

Returns the bond angles that constitute the internal coordinate

property atoms

Returns the atoms that constitute the internal coordinate

classmethod from_quartet(quartet)

Make an InternalCoordinate from a Quartet

get_reference_atoms(_src)

Get reference atoms with available coordinates from a source. Note, that this method does not check if reference coordinates are actually available, so make sure to only provide source objects that have cartesian coordinates contained.

Parameters:

_src (object) – The source object to get the reference atom from. This can be: - a list or tuple of Atoms - an object with a get_atoms method (e.g. a biopython Residue)

Returns:

A list of reference atoms with available coordinates

Return type:

list

property ids

Returns the ids of the atoms that constitute the internal coordinate

property is_improper

Returns True if the internal coordinate is improper

property is_proper

Returns True if the internal coordinate is proper

property lengths

Returns the bond lengths that constitute the internal coordinate

Abstract

Abstract classes for storing force field data from CHARMM topology and parameter files

class biobuild.utils.abstract.AbstractAtom(id: str, type: str = None, charge: float = None, mass: float = None, element: str = None, parent=None, is_wildcard: bool = False, coord: ndarray = None)

Bases: object

A representation of a single Atom

property element

get_parent()

Get the parent of the atom

set_parent(obj)

Set the parent of the atom

to_biopython(serial_number: int = 1)

Returns a Bio.PDB.Atom object

Parameters:

serial_number (int) – The serial number of the atom

class biobuild.utils.abstract.AbstractBond(atom1: AbstractAtom | str, atom2: AbstractAtom | str, K: float = None, length: float = None)

Bases: object

A representation of a single Bond between two atoms (or atom types) optionally, a bond spring constant (K) and length can be supplied.

property atoms

find_atoms(obj)

Find the atoms of the bond in an object. This will return a tuple of identified atoms with the same id if they exist in the object, None for any atom that was not found.

get_parent()

Get the parent of the bond (i.e. it’s residue)

migrate_atoms(obj)

Migrate the atoms of the bond to a new object. This will update the atom1 and atom2 attributes of the bond to point to the atoms in the new object if they can be found.

class biobuild.utils.abstract.AbstractEntity(id=None)

Bases: object

A representation of a single collection entity (Residue, Patch, etc.)

add_atom(atom)

Add an atom to the residue

add_bond(bond)

Add a bond to the residue

property atoms

get_atom(id) → AbstractAtom

Get an atom by its ID

Parameters:

id (str) – The ID or type of the atom

Returns:

atom – The atom with the given ID. If no atom is found, None is returned.

Return type:

AbstractAtom

get_atoms_by_type(_type)

Get a list of atoms by their type

Parameters:

_type (str) – The type of the atom

Returns:

atoms – A list of atoms with the given type.

Return type:

list

get_bond(id1, id2) → AbstractBond

Get a bond by its atom IDs

has_atom(_atom)

Check if the entity has an atom

Parameters:

_atom (AbstractAtom) – The atom to check for

Returns:

has_atom – True if the atom is in the entity, False otherwise

Return type:

bool

class biobuild.utils.abstract.AbstractEntity_with_IC(id=None)

Bases: AbstractEntity

property IC_atom_ids

Returns a set of all atom IDs of all atoms for which the patch also stores internal coordinates.

add_ic(ic)

Add an internal coordinate to the residue

add_internal_coordinates(ic)

Add an internal coordinate to the residue

get_internal_coordinates(*ids, mode: str = 'exact')

Get internal coordinates by their atom IDs

Parameters:

• ids (str) – The IDs of the atoms in the internal coordinate (this can also be any data object that has an id attribute)

• mode (str) – The mode to use for matching the internal coordinates. Supported modes are: - exact: The internal coordinate must match the given atom IDs exactly (requires that four ids are given) - partial: The internal coordinate must match the given atom IDs where they are provided, but wildcards can be set to None (requires that four ids or None are given in order) - multi_partial: The internal coordinate must match any given atom IDs where they are provided, but wildcards can be set to None (requires that four ids or None are given in order) - anywhere: The internal coordinate must contain all of the given atom IDs in any order (requires at least one id) - anywhere_partial: The internal coordinate must contain any of the given atom IDs in any order (requires at least one id)

Returns:

ics – A list of internal coordinates

Return type:

list

property has_IC

Other auxiliary utilities

Utility and auxiliary functions

class biobuild.utils.auxiliary.DummyBar(*args, **kwargs)

Bases: object

A dummy progress bar

class biobuild.utils.auxiliary.DummyStructure(residues)

Bases: object

A dummy pdb structure

Used for the surface residue inference

Parameters:

residues (list of Bio.PDB.Residue.Residue) – The residues to include in the structure

get_atoms()

get_chains()

get_models()

get_residues()

biobuild.utils.auxiliary.chain_id_maker(cdx: int)

Make a string chain id from a counting integer

Parameters:

cdx (int) – The counting integer

Returns:

The chain id

Return type:

str

biobuild.utils.auxiliary.change_suffix(filename, suffix)

Change the suffix of a filename

Parameters:

• filename (str) – The filename

• suffix (str) – The new suffix

Returns:

The filename with the new suffix

Return type:

str

biobuild.utils.auxiliary.filename_to_id(filename)

Extract the id from a filename

Parameters:

filename (str) – The filename

Returns:

The id

Return type:

str

biobuild.utils.auxiliary.load_pickle(filename)

Load an object from a pickle file

biobuild.utils.auxiliary.make_formula(atoms)

Make a chemical formula from a list of atoms

Parameters:

atoms (list of Atoms) – The atoms. Each atom must have an element attribute (str).

Returns:

The chemical formula

Return type:

str

biobuild.utils.auxiliary.remove_nonprintable(text)

Remove non-printable characters from a string

Parameters:

text (str) – The string

Returns:

The string without non-printable characters

Return type:

str

biobuild.utils.auxiliary.save_pickle(obj, filename)

Save an object to a pickle file