The utils package

These are the utility modules of buildamol. 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

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

The base directory of the package

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

The resources directory of the package

buildamol.utils.defaults.DEFAULT_BOND_LENGTH = 1.6

The default length of a bond in Angstrom

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

The path to the default CHARMM topology file

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

The paths to the default PDBe component files

buildamol.utils.defaults.DEFAULT_SASA_N = 300

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

buildamol.utils.defaults.DEFAULT_SASA_PROBE_RADIUS = 1.4

The default probe radius for calculating solvent accessible surface area

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

buildamol.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 buildamol.utils.convert.OpenMMBioPythonConverter

Bases: PDBIO

Convert OpenMM data structures to Biopython

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

buildamol_to_openmm(obj)

Convert a BuildAMol Molecule 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 buildamol.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 BuildAMol Molecule in a PDB file

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

Convert the internal FileIO to a biopython structure object

class buildamol.utils.convert.PybelBioPythonConverter

Bases: PDBIO

Convert Pybel (openbabel) data structures to Biopython

buildamol_to_pybel(obj)

Convert a BuildAMol 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 buildamol.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

class buildamol.utils.convert.STKBuildAMolConverter

Bases: PDBIO

Convert STK to buildamol and vice versa

buildamol_to_stk(obj)

Convert a BuildAMol object to an STK object

Parameters:

obj (object) – The object to convert

Returns:

The converted object

Return type:

object

stk_to_pdbio(obj)

Convert an STK object to a BuildAMol object

Parameters:

obj (object) – The object to convert

Returns:

The converted object

Return type:

object

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

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

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

buildamol.utils.convert.mol_to_numpy_array(mol, include_bonds: bool = False)

Convert a molecule to a numpy array

Parameters:

• mol (object) – The molecule to convert

• include_bonds (bool, optional) – Whether to include the bonds in the array If False, the bond array will be empty

Returns:

An array of atomic numbers and atom coordinates and an array of bonds between atoms as serial numbers of a,b and bond order

Return type:

tuple,

PDB

Auxiliary tools for PDB files.

buildamol.utils.pdb.decode_pdb(pdb: str)

Decode the contents of a PDB file.

Parameters:

pdb (str) – The PDB file contents.

Returns:

• atoms_table (dict) – The per-model atom tables

• connect_table (list) – A list of tuples of atom serial numbers that are bonded.

buildamol.utils.pdb.encode_atom(atom) → str

Make an ATOM line for a PDB file.

buildamol.utils.pdb.encode_pdb(mol, symmetric: bool = True) → str

Encode a molecule to a PDB file without actually writing it to disk.

Parameters:

• mol (Molecule) – The molecule to write.

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

Returns:

The PDB file contents.

Return type:

str

buildamol.utils.pdb.find_models(filename)

Get the models from a PDB file.

Parameters:

filename (str) – The filename to read.

Returns:

A list of models.

Return type:

list

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

buildamol.utils.pdb.make_atoms_table(mol)

Make a PDB atom table

Parameters:

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

Returns:

The table

Return type:

str

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

buildamol.utils.pdb.parse_atom_lines(filename, model=None)

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

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

buildamol.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 (bam.Molecule) – The molecule to generate the connectivity for.

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

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

buildamol.utils.cif.make_bond_lines(mol)

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

Parameters:

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

Returns:

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

Return type:

list

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

Generate a table of bond information for a molecule.

Parameters:

• mol (bam.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

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

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

Parse the bond table from a BuildAMol generated CIF file.

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

Write a bond table to a CIF file.

Parameters:

• mol (bam.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 buildamol.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 buildamol.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 buildamol.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 buildamol.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 buildamol.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

remove_internal_coordinates()

Remove all internal coordinates

Other auxiliary utilities

Utility and auxiliary functions

class buildamol.utils.auxiliary.AtomIterator(atoms)

Bases: object

Dummy class defining the get_atoms method for iterating over atoms in a list

get_atoms()

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

Bases: object

A dummy progress bar

update(*args, **kwargs)

class buildamol.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()

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

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

buildamol.utils.auxiliary.coord_array(*objs) → ndarray

Creates a numpy array of coordinates from objects with a get_coord() method or a coord attribute

buildamol.utils.auxiliary.deprecation_warning(message)

Issue a deprecation warning

Parameters:

message (str) – The warning message

buildamol.utils.auxiliary.dont_use_ic()

Don’t use internal coordinates when connecting molecules

buildamol.utils.auxiliary.dont_use_numba()

Don’t use Numba

buildamol.utils.auxiliary.element_range(symbol: str, n: int, start: int = 1)

Generate a range of systemic atom ids based on element symbol and number of atoms

Parameters:

• symbol (str) – The element symbol

• n (int) – The number of elements

• start (int, optional) – The start number, by default 1

Returns:

The element names

Return type:

list of str

Examples

>>> element_range("C", 3)
['C1', 'C2', 'C3']

buildamol.utils.auxiliary.filename_to_id(filename)

Extract the id from a filename

Parameters:

filename (str) – The filename

Returns:

The id

Return type:

str

buildamol.utils.auxiliary.get_args(func, namespace)

Filter a dictionary based on the argument-namespace of a function

Parameters:

• func (function) – The function whose argument-namespace will be used for filtering

• namespace (dict) – The dictionary to be filtered

Returns:

The filtered dictionary

Return type:

dict

buildamol.utils.auxiliary.has_package(name)

buildamol.utils.auxiliary.lazy_module(fullname)

buildamol.utils.auxiliary.load_pickle(filename)

Load an object from a pickle file

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

buildamol.utils.auxiliary.njit(func)

buildamol.utils.auxiliary.progress_bar(*args, **kwargs)

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

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

Save an object to a pickle file

buildamol.utils.auxiliary.use_all_numba()

Use Numba if available to speed up all functions

buildamol.utils.auxiliary.use_ic()

Use internal coordinates when connecting molecules (where available)

buildamol.utils.auxiliary.use_numba()

Use Numba if available to speed up some functions