meeko.polymer module

meeko.polymer.find_graph_paths(graph, start_node, end_nodes, current_path=(), paths_found=())

(DFS Path Search) Recursively find all paths from a start node to any of the specified end nodes in a directed graph.

Parameters:

• graph (dict[int, list[int]]) – A dictionary representing a graph. Keys are node IDs (integers), and values are lists of neighboring node IDs.

• start_node (int) – The node from which to begin path traversal.

• end_nodes (iterable of int) – A set or list of node IDs that are valid end points for a path.

• current_path (tuple[int], optional) – The current traversal path (used during recursion). Default is empty tuple.

• paths_found (list[list[int]], optional) – The list of complete paths found so far. Default is empty tuple, which will be converted internally.

Returns:

A list of paths. Each path is represented as a list of node IDs from start_node to an end_node.

Return type:

list[list[int]]

meeko.polymer.find_inter_mols_bonds(mols_dict)

Finds inter-residue bonds between the RDKit Mols in mols_dict based on distances compared to built-in covalent radii (.utils.rdkitutils.covalent_radius).

Parameters:

mols_dict (dict[str, (Chem.Mol, str)]) – A dictionary to store raw input mols and input residue names by residue IDs. The keys are residue IDs in the format <chain>:<resnum> such as “A:42”, and the values are tuples of an RDKit Mols and input resname.

Returns:

A dictionary representing inter-residue bonds. The keys are tuples of residue IDs in the format <chain>:<resnum>, and the values are lists of tuples of atom indices in the two residues that are bonded.

Return type:

dict[(str, str), list[tuple[int, int]]]

meeko.polymer.mapping_by_mcs(mol, ref)

Find an atom-atom mapping between two molecules based on the maximum common substructure (MCS).

Parameters:

• mol (Chem.Mol) – The first molecule to compare.

• ref (Chem.Mol) – The second molecule to compare.

Returns:

A dictionary mapping atom indices from the first molecule to the second molecule. The keys are atom indices from the first molecule, and the values are atom indices from the second molecule.

Return type:

dict[int, int]

meeko.polymer.divide_int_gracefully(integer, weights, allow_equal_weights_to_differ=False)

Divides an integer into parts based on the provided weights, ensuring that the sum of the parts equals the integer.

Parameters:

• integer (int) – The integer to be divided.

• weights (list[float]) – A list of weights that determine the proportions of the integer.

• allow_equal_weights_to_differ (bool, optional) – If True, allows equal weights to be treated as different groups. Default is False (equal inputs get equal outputs).

Returns:

A list of floats representing the divided integer based on the weights.

Return type:

list[float]

meeko.polymer.rectify_charges(q_list, net_charge=None, decimals=3)

Makes charges N (default is 3) decimals in length and ensures they sum to an integer.

Parameters:

• q_list (list[float]) – List of charges to be rectified.

• net_charge (int or None) – The desired net charge. If None, it will be calculated from the sum of the charges in q_list.

• decimals (int) – The number of decimal places to round the charges to. Default is 3.

Returns:

charges_dec – List of rectified charges, rounded to the specified number of decimal places.

Return type:

list[float]

meeko.polymer.get_updated_positions(monomer, new_positions)

Returns full set of positions for the rdkit_mol in monomer given a partial set of new_positions. Hydrogens not specified in new_positions will have their position reset by RDKit if they are one or two bonds away from an atom in new_positions.

Parameters:

• monomer (Monomer) – Must have rdkit_mol to associate with new positions.

• new_positions (dict[int, (float, float, float)]) – Dictionary mapping the atom indices to their new positions.

Returns:

positions – The updated positions of the atoms in the RDKit molecule.

Return type:

np.ndarray

meeko.polymer.update_H_positions(mol, indices_to_update)

Re-calculates the position of some hydrogens already existing in the mol. Does not guarantee that chirality can be preserved.

Parameters:

• mol (Chem.Mol) – RDKit Mol object with hydrogens.

• indices_to_update (list[int]) – Hydrogen indices to update.

Return type:

None

Raises:

RuntimeError: – If a provided index in indices_to_update is not a Hydrogen, if a Hydrogen only has Hydrogen neighbors, or if the number of visited Hydrogens does not match the number of Hydrogens marked to be deleted.

exception meeko.polymer.PolymerCreationError(error, recommendations=None)

Bases: RuntimeError

Exception raised when the creation of a Polymer object fails.

error

The main error message.

Type:

str

recommendations

Recommendations for resolving the error.

Type:

str

traceback

The traceback of the error.

Type:

str

meeko.polymer.handle_parsing_situations(unmatched_res, unparsed_res, allow_bad_res, res_missed_altloc, res_needed_altloc)

Handle situations where residues are not parsed correctly or do not match templates.

Parameters:

• unmatched_res (set) – Residues that did not match any template.

• unparsed_res (set) – Residues that could not be parsed.

• allow_bad_res (bool) – If True, allows residues that do not match templates to be ignored.

• res_missed_altloc (set) – Residues that were requested with an alternate location but were not found.

• res_needed_altloc (set) – Residues that were found with an alternate location but were not requested.

Raises:

PolymerCreationError – If there are residues that could not be parsed or matched to templates, and allow_bad_res is False.

class meeko.polymer.ResidueChemTemplates(residue_templates, padders, ambiguous)

Bases: BaseJSONParsable

Holds template data required to initialize Polymer

residue_templates

keys are the ID of an instance of ResidueTemplate

Type:

dict[str, ResidueTemplate]

padders

instances of ResiduePadder keyed by a link_label (a string) link_labels establish the relationship between ResidueTemplates and ResiduePadders, determining which padder is to be used to pad each atom of an instance of Monomer that needs padding.

Type:

dict

ambiguous

mapping between input residue names (e.g. the three-letter residue name from PDB files) and IDs (strings) of ResidueTemplates

Type:

dict[str, list[str]]

classmethod json_encoder(obj)

Return type:

Optional[dict[str, Any]]

expected_json_keys: Optional[frozenset[str]] = {'ambiguous', 'padders', 'residue_templates'}

add_dict(data, overwrite=False)

Add or update data from a dictionary to the current instance.

Parameters:

• data (dict) – A dictionary containing new data to be added. The dictionary may contain keys within “residue_templates”, “padders”, and “ambiguous”.

• overwrite (bool, optional) – If True, existing data will be overwritten with new data. If False, new data will be added without overwriting existing data. Default is False.

static lookup_filename(filename, data_path)

Look for a file in the current directory or in the data_path directory. If the file is not found in either location, raise a ValueError. If the file is found in the data_path directory, return the full path. If the file is found in the current directory, return the filename.

Parameters:

• filename (str) – The name of the file to look for.

• data_path (pathlib.Path) – The path to the directory where the file may be located.

Returns:

The full path to the file if found, otherwise raises ValueError.

Return type:

str

Raises:

ValueError – If the file is not found in either the current directory or the data_path directory.

classmethod from_json_file(filename)

Create an instance of ResidueChemTemplates from a JSON file.

Parameters:

filename (str) – The name of the JSON file to read. The file may contain residue templates, padders, and ambiguous residue names.

Returns:

An instance of ResidueChemTemplates created from the JSON file.

Return type:

ResidueChemTemplates

classmethod create_from_defaults()

Create an instance of ResidueChemTemplates using default data (residue_chem_templates.json).

Returns:

An instance of ResidueChemTemplates created from the default JSON file.

Return type:

ResidueChemTemplates

add_json_file(filename)

Add data from a JSON file to the current instance.

Parameters:

filename (str) – The name of the JSON file to read. The file may contain residue templates, padders, and ambiguous residue names.

Return type:

None

class meeko.polymer.Polymer(raw_input_mols, bonds, residue_chem_templates, mk_prep=None, set_template=None, blunt_ends=None, get_atomprop_from_raw=None)

Bases: BaseJSONParsable

Represents polymer with its subunits as individual RDKit molecules.

Used for proteins and nucleic acids. The key class is Monomer, which contains, a padded RDKit molecule containing part of the adjacent residues to enable chemically meaningful parameterizaion. Instances of ResidueTemplate make sure that the input, which may originate from a PDB string, matches the RDKit molecule of the template, even if hydrogens are missing.

monomers

Dictionary to store monomers where keys are residue IDs in the format <chain>:<resnum> such as “A:42” and values are instances of Monomer.

Type:

dict[str, Monomer]

log

Dictionary to store log messages during monomer processing (_get_monomer).

Type:

dict[str, list[str]]

residue_chem_templates

An instance of the ResidueChemTemplates class used to initialize this Polymer.

Type:

ResidueChemTemplates

raw_input_mols

A dictionary of raw input mols used to initialize this Polymer, where keys are residue IDs in the format <chain>:<resnum> such as “A:42” and values are tuples of an RDKit Mols and input resname.

Type:

dict[str, tuple[Chem.Mol, str]]

classmethod json_encoder(obj)

Return type:

Optional[dict[str, Any]]

expected_json_keys: Optional[frozenset[str]] = {'log', 'monomers', 'residue_chem_templates'}

stitch(residues_to_add=None, bonds_to_use=None)

Function to stitch together monomers into a single molecule.

Parameters:

• residues_to_add (set[str], optional) – A set of residue IDs to add to the stitched molecule. If None, all valid monomers will be added. Default is None (all valid monomers).

• bonds_to_use (dict[tuple[str], list[tuple[int]]], optional) – A dictionary of bonds to use for stitching. The keys are tuples of residue IDs, and the values are lists of tuples of atom indices (in rdkit_mol). If None, all available bonds in the polymer will be used. Default is None (all available bonds).

Returns:

An RDKit molecule that results from adding bonds between the specified residues. It may contain multiple fragments if there are multiple chains or gaps.

Return type:

Chem.Mol

classmethod from_pdb_string(pdb_string, chem_templates, mk_prep, set_template=None, residues_to_delete=None, allow_bad_res=False, bonds_to_delete=None, blunt_ends=None, wanted_altloc=None, default_altloc=None)

Construct a Polymer object from a PDB string.

Parameters:

• pdb_string (str) – The PDB string containing the polymer structure.

• chem_templates (ResidueChemTemplates) – An instance of the ResidueChemTemplates class to construct the polymer.

• mk_prep (MoleculePreparation) – An instance of the MoleculePreparation class to construct the polymer.

• set_template (dict[str, str], optional) – A dictionary mapping residue IDs in the format <chain>:<resnum> such as “A:42” to the user-specified ResidueTemplate names. If None, no specific templates will be set. Default is None (the built-in ResidueTemplate ambiguious name mapping will be used).

• residues_to_delete (set[str], optional) – A set of residue IDs to delete from the polymer. If None, no residues will be deleted. Default is None (no residues will be deleted).

• allow_bad_res (bool, optional) – If True, allows residues that do not match templates to be ignored (rdkit_mol will be None). If False, raises an error if any residues do not match templates. Default is False.

• bonds_to_delete (list[tuple[str, str]], optional) – A list of tuples of residue IDs to delete bonds between. If None, no bonds will be deleted. Default is None (no bonds will be deleted).

• blunt_ends (list[tuple[str, int]], optional) – A list of tuples where each tuple is a residue ID and a 0-based atom index (in raw_mol). If None, no blunt ends will be added. Default is None (no blunt ends will be added).

• wanted_altloc (dict[str, str], optional) – A dictionary mapping residue IDs in the format <chain>:<resnum> such as “A:42” to the desired alternate location (altloc) for that residue.

• default_altloc (str, optional) – A string representing the default alternate location (altloc) to be used for residues that do not have a specific altloc specified.

Returns:

An instance of the Polymer class constructed from the PDB string.

Return type:

Polymer

Raises:

• NotImplementedError – If bonds_to_delete includes residue pairs with more than bond2 between them.

• PolymerCreationError – If there are residues that could not be parsed or matched to templates, and allow_bad_res is False.

classmethod from_pqr_string(pqr_string, chem_templates, mk_prep, set_template=None, residues_to_delete=None, allow_bad_res=False, bonds_to_delete=None, blunt_ends=None)

Construct a Polymer object from a PQR string. Adapted from PDB2PQR.

Parameters:

• pqr_string (str) – The PQR string containing the polymer structure.

• chem_templates (ResidueChemTemplates) – An instance of the ResidueChemTemplates class to construct the polymer.

• mk_prep (MoleculePreparation) – An instance of the MoleculePreparation class to construct the polymer.

• set_template (dict[str, str], optional) – A dictionary mapping residue IDs in the format <chain>:<resnum> such as “A:42” to the user-specified ResidueTemplate names. If None, no specific templates will be set. Default is None (the built-in ResidueTemplate ambiguious name mapping will be used).

• residues_to_delete (set[str], optional) – A set of residue IDs to delete from the polymer. If None, no residues will be deleted. Default is None (no residues will be deleted).

• allow_bad_res (bool, optional) – If True, allows residues that do not match templates to be ignored (rdkit_mol will be None). If False, raises an error if any residues do not match templates. Default is False.

• bonds_to_delete (list[tuple[str, str]], optional) – A list of tuples of residue IDs to delete bonds between. If None, no bonds will be deleted. Default is None (no bonds will be deleted).

• blunt_ends (list[tuple[str, int]], optional) – A list of tuples where each tuple is a residue ID and a 0-based atom index (in raw_mol). If None, no blunt ends will be added. Default is None (no blunt ends will be added).

Returns:

An instance of the Polymer class constructed from the PDB string.

Return type:

Polymer

Raises:

• NotImplementedError – If bonds_to_delete includes residue pairs with more than bond2 between them.

• PolymerCreationError – If there are residues that could not be parsed or matched to templates, and allow_bad_res is False.

classmethod from_prody(prody_obj, chem_templates, mk_prep, set_template=None, residues_to_delete=None, allow_bad_res=False, bonds_to_delete=None, blunt_ends=None, wanted_altloc=None, default_altloc=None)

Construct a Polymer object from a ProDy Selection or AtomGroup object.

Parameters:

• prody_obj (ProDy.Selection or ProDy.AtomGroup) – The ProDy object to construct the polymer from.

• chem_templates (ResidueChemTemplates) – An instance of the ResidueChemTemplates class to construct the polymer.

• mk_prep (MoleculePreparation) – An instance of the MoleculePreparation class to construct the polymer.

• set_template (dict[str, str], optional) – A dictionary mapping residue IDs in the format <chain>:<resnum> such as “A:42” to the user-specified ResidueTemplate names. If None, no specific templates will be set. Default is None (the built-in ResidueTemplate ambiguious name mapping will be used).

• residues_to_delete (set[str], optional) – A set of residue IDs to delete from the polymer. If None, no residues will be deleted. Default is None (no residues will be deleted).

• allow_bad_res (bool, optional) – If True, allows residues that do not match templates to be ignored (rdkit_mol will be None). If False, raises an error if any residues do not match templates. Default is False.

• bonds_to_delete (list[tuple[str, str]], optional) – A list of tuples of residue IDs to delete bonds between. If None, no bonds will be deleted. Default is None (no bonds will be deleted).

• blunt_ends (list[tuple[str, int]], optional) – A list of tuples where each tuple is a residue ID and a 0-based atom index (in raw_mol). If None, no blunt ends will be added. Default is None (no blunt ends will be added).

• wanted_altloc (dict[str, str], optional) – A dictionary mapping residue IDs in the format <chain>:<resnum> such as “A:42” to the desired alternate location (altloc) for that residue.

• default_altloc (str, optional) – A string representing the default alternate location (altloc) to be used for residues that do not have a specific altloc specified.

Returns:

An instance of the Polymer class constructed from the PDB string.

Return type:

Polymer

Raises:

• NotImplementedError – If bonds_to_delete includes residue pairs with more than bond2 between them.

• PolymerCreationError – If there are residues that could not be parsed or matched to templates, and allow_bad_res is False.

parameterize(mk_prep, get_atomprop_from_raw=None)

Parameterize the monomers in the polymer using the provided MoleculePreparation instance.

Parameters:

• mk_prep (MoleculePreparation) – An instance of the MoleculePreparation class to parameterize the monomers.

• get_atomprop_from_raw (dict, optional) – A dictionary mapping atom properties to pass from raw_input_mols. The keys are the property names and the values are the default values.

Return type:

None

flexibilize_sidechain(residue_id, mk_prep)

Set the sidechain of a residue as flexible. The Monomer must have been processed and have valid attributes before calling this method.

Parameters:

• residue_id (str) – The ID of the residue to be made flexible.

• mk_prep (MoleculePreparation) – An instance of the MoleculePreparation class to construct the polymer.

Return type:

None

to_pdb(new_positions=None)

Convert the polymer to a PDB string while (optionally) updating the coordinates of specified monomers.

Parameters:

new_positions (dict[str, dict[int, tuple[float, float, float]]], optional) – A dictionary mapping residue IDs to dictionaries of atom indices and their new coordinates.

Returns:

pdb_string – The PDB string representation of the polymer.

Return type:

str

Raises:

ValueError – If any residue IDs in new_positions are not valid monomers.

export_static_atom_params()

Export static atom parameters from the polymer.

Returns:

• atom_params (dict) – A dictionary containing atom parameters.

• coords (list) – A list of coordinates for the atoms.

get_ignored_monomers()

Get monomers that are ignored.

Returns:

A dictionary of ignored monomers. The keys are the residue IDs and the values are the corresponding Monomer objects.

Return type:

dict[str, Monomer]

get_valid_monomers()

Get monomers that are valid (not ignored).

Returns:

A dictionary of valid monomers. The keys are the residue IDs and the values are the corresponding Monomer objects.

Return type:

dict[str, Monomer]

meeko.polymer.add_rotamers_to_polymer_molsetups(rotamer_states_list, polymer)

Add rotamer states to the monomers’ molecule setups in a polymer and get the state indices.

Parameters:

• rotamer_states_list (list[dict[str, list[float]]]) – A list of dictionaries, where each dictionary contains residue IDs as keys and lists of angles as values.

• polymer (Polymer) – The polymer object to which the rotamer states will be added.

Returns:

state_indices_list – A list of dictionaries, where each dictionary contains residue IDs as keys and the corresponding rotamer state indices as values.

Return type:

list[dict[str, int]]

class meeko.polymer.Monomer(raw_input_mol, rdkit_mol, mapidx_to_raw, input_resname=None, template_key=None, atom_names=None)

Bases: BaseJSONParsable

Individual subunit in a Polymer. Often called residue.

raw_rdkit_mol

An RDKit Mol that defines element and connectivity within a residue. Bond orders and formal charges may be incorrect, and hydrogens may be missing. This molecule may originate from a PDB string and it defines also the positions of the atoms.

Type:

Chem.Mol

rdkit_mol

Copy of the molecule from a ResidueTemplate, with positions from raw_rdkit_mol. All hydrogens are real atoms except for those at connections with adjacent residues.

Type:

Chem.Mol

mapidx_to_raw

Mapping of atom indices in rdkit_mol to raw_rdkit_mol.

Type:

dict[int, int]

residue_template_key

The matched residue template key of this Monomer.

Type:

str

input_resname

The input residue name of this Monomer.

Type:

str

atom_names

List of atom names in the same order as rdkit_mol.

Type:

list[str]

padded_mol

Padded molecule with additional atoms around link atoms from adjacent residues.

Type:

Chem.Mol

molsetup

An RDKitMoleculeSetup associated with this residue.

Type:

RDKitMoleculeSetup

molsetup_mapidx

Mapping of atom indices in padded_mol to rdkit_mol.

Type:

dict[int, int]

is_flexres_atom

List indicating whether each atom is a flexible residue atom.

Type:

list[bool]

is_movable

Indicates whether the residue is movable.

Type:

bool

mapidx_from_raw

Mapping of atom indices in raw_rdkit_mol to rdkit_mol.

Type:

dict[int, int]

template

provides access to link_labels in the template

Type:

ResidueTemplate

classmethod json_encoder(obj)

Return type:

Optional[dict[str, Any]]

expected_json_keys: Optional[frozenset[str]] = frozenset({'atom_name', 'input_resname', 'is_flexres_atom', 'is_movable', 'mapidx_from_raw', 'mapidx_to_raw', 'molsetup', 'molsetup_mapidx', 'padded_mol', 'raw_rdkit_mol', 'rdkit_mol', 'residue_template_key'})

set_atom_names(atom_names_list)

Set the atom names for the monomer.

Parameters:

atom_names_list (list[str]) – A list of atom names to set for the monomer. The length of this list must match the number of atoms in the RDKit molecule.

Return type:

None

parameterize(mk_prep, residue_id, get_atomprop_from_raw=None)

Parameterize the monomer using the provided mk_prep object.

Parameters:

• mk_prep (MoleculePreparation) – A MoleculePreparation object that provides the parameterization method.

• residue_id (str) – The residue ID to be used for parameterization.

• get_atomprop_from_raw (dict[str, any], optional) – A dictionary mapping atom property names to default values. If provided, these properties will be set on the atoms in the raw RDKit molecule. The default is None (not passing any properties).

Raises:

• ValueError – If the atom property names in get_atomprop_from_raw are not strings.

• NotImplementedError – If the number of molsetups is not equal to 1.

class meeko.polymer.NoAtomMapWarning(name='')

Bases: Filter

A logging filter to exclude warnings about missing atom mapping numbers in RDKit.

filter(record)

Filter out warnings about missing atom mapping numbers in RDKit.

Parameters:

record (logging.LogRecord) – The log record to be filtered.

Returns:

True if the record should be logged, False otherwise.

Return type:

bool

class meeko.polymer.ResiduePadder(rxn_smarts, adjacent_res_smarts=None, auto_blunt=False)

Bases: BaseJSONParsable

A class for padding RDKit molecules of residues with parts from adjacent residues.

rxn

Reaction SMARTS of a single-reactant, single-product reaction for padding.

Type:

rdChemReactions.ChemicalReaction

adjacent_smartsmol

SMARTS molecule with mapping numbers to copy atom positions from part of adjacent residue.

Type:

Chem.Mol

adjacent_smartsmol_mapidx

Mapping for atoms in adjacent_smartsmol, from mapping numbers to atom indicies.

Type:

list

classmethod json_encoder(obj)

Return type:

Optional[dict[str, Any]]

expected_json_keys: Optional[frozenset[str]] = {'adjacent_res_smarts', 'auto_blunt', 'rxn_smarts'}

meeko.polymer.get_molAtomMapNumbers(mol)

Return the set of mapping numbers in a molecule.

Return type:

set[int]

meeko.polymer.remove_unmapped_atoms_from_mol(mol)

Remove atoms without mapping numbers from a molecule.

Return type:

Mol

meeko.polymer.apply_atom_mappings(mcs_mol, original_mol)

Apply atom mappings from the original molecule to the MCS molecule by substructure match. Be prepared for multiple matches, return a list for further evaluation.

Return type:

list[Mol]

meeko.polymer.remove_atoms_with_mapping(product, mapping_numbers)

Remove atoms with specific atom mapping numbers from a molecule.

Return type:

Mol

class meeko.polymer.ResidueTemplate(smiles, link_labels=None, atom_names=None)

Bases: BaseJSONParsable

Data and methods to pad rdkit molecules of polymer residues with parts of adjacent residues.

mol

molecule with the exact atoms that constitute the system. All Hs are explicit, but atoms bonded to adjacent residues miss an H.

Type:

Chem.Mol

link_labels

Keys are indices of atoms that need padding Values are strings to identify instances of ResiduePadder

Type:

dict[int, str]

atom_names

list of atom names, matching order of atoms in rdkit mol

Type:

list[str]

classmethod json_encoder(obj)

Return type:

Optional[dict[str, Any]]

expected_json_keys: Optional[frozenset[str]] = {'atom_name', 'link_labels', 'mol'}

check(mol, link_labels, atom_names)

Check the validity of a ResidueTemplate using the rdkit mol.

Parameters:

• mol (Chem.Mol) – The molecule to check.

• link_labels (dict[int, str], optional) – Keys are indices of atoms that need padding Values are strings to identify instances of ResiduePadder

• atom_names (list[str], optional) – List of atom names in the same order as the atoms in the given smiles.

Raises:

• ValueError – If the number of atoms in the molecule does not match the length of atom_names.

• RuntimeError – If the molecule is not a valid SMILES representation.

match(input_mol)

Match the input molecule with the template molecule and return the mapping.

Parameters:

input_mol (Chem.Mol) – The input molecule to be matched with the template.

Returns:

A tuple containing two dictionaries: - The first dictionary contains the results of the matching, including the number of found and missing atoms. - The second dictionary contains the mapping between the template and input molecule atom indices.

Return type:

tuple[dict, dict]

Raises:

RuntimeError – If there are repeated values with different keys in the mapping.