rdtools.atommap#

A module of atom map number operations.

rdtools.atommap.clear_atom_map_numbers(mol: Mol) → None#

Clear atom map numbers of the molecule.

Parameters:

mol (Chem.Mol) – The molecule to clear atom map numbers.

rdtools.atommap.get_atom_map_numbers(mol: Mol) → list[int]#

Get atom map numbers of the molecule.

Parameters:

mol (Chem.Mol) – The molecule to get atom map numbers.

Returns:

list[int] – The atom map numbers of the molecule.

rdtools.atommap.has_atom_map_numbers(mol: Mol) → bool#

Check whether the molecule has atom map numbers.

Parameters:

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

Returns:

bool – Whether the molecule has atom map numbers.

rdtools.atommap.map_h_atoms_in_reaction(rmol: Mol, pmol: Mol) → Tuple[Mol, Mol]#

Map H atoms in a reaction given that heavy atoms are mapped already.

The function only applies to the case where each atom in rmol paired to an atom in pmol and vise verse. Atom map numbers are assumed to start from 1. This is originally work for the results from rxnmapper, and viability to other input is unknown.

Parameters:

  • rmol (Chem.Mol) – The reactant molecule.

  • pmol (Chem.Mol) – The product molecule.

Returns:

Tuple[Chem.Mol, Chem.Mol] – The reactant and product molecule with mapped H atoms.

rdtools.atommap.move_atommaps_to_notes(mol: Mol, clear_atommap: bool = True) → None#

Move atom map numbers to the atomNote property.

This helps to make the display slightly cleaner.

Parameters:

  • mol (Chem.Mol) – The molecule to move atom map numbers to the atomNote property.

  • clear_atommap (bool, optional) – Whether to clear the atom map numbers after moving. Defaults to True. If True, the atom map numbers will be cleared.

rdtools.atommap.move_notes_to_atommaps(mol: Mol) → None#

Move atom map numbers from atomNote to the atomMap property.

This is only valid if there is no other info in atomNote.

Parameters:

mol (Chem.Mol) – The molecule to move atom map numbers to the atomMap property.

rdtools.atommap.needs_renumber(mol: Mol) → bool#

Check whether the molecule needs renumbering.

Expect atom map numbers to be non-zero and monotonically increasing but not necessarily continuous.

Parameters:

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

Returns:

bool – Whether the molecule needs renumbering.

rdtools.atommap.renumber_atoms(mol: Mol, new_order: Iterable[int] | dict[int, int] | None = None, update_atom_map: bool = True) → Mol#

Renumber the atoms of the molecule.

Parameters:

  • mol (Chem.Mol) – The molecule to renumber atoms.

  • new_order (Optional[Union[Iterable[int], dict[int, int]]], optional) – The new ordering the atoms. - If provided as a list, it should a list of atom indexes and should have a length of the number of atoms. E.g., if newOrder is [3,2,0,1], then atom 3 in the original molecule will be atom 0 in the new one. - If provided as a dict, it should be a mapping between atoms. E.g., if newOrder is {0: 3, 1: 1, 2: 2, 3: 0}, then atom 0 in the original molecule will be atom 3 in the new one. Unlike the list case, the newOrder can be a partial mapping, but one should make sure all the pairs are consistent. E.g.,``{0: 3}`` and {0: 3, 3: 0} are also acceptable input for {0: 3, 1: 1, 2: 2, 3: 0}, but you can’t have inconsistent ones like {0: 3, 3: 2}. - If no value provided (default), then the molecule will be renumbered based on the current atom map numbers. It is helpful when the sequence of atom map numbers and atom indexes are inconsistent.

  • update_atom_map (bool, optional) – Whether to update the atom map numbers of the molecule. Defaults to True.

Returns:

Chem.Mol – The molecule with renumbered atoms.

rdtools.atommap.renumber_atoms_by_atom_map_numbers(mol: Mol, update_atom_map: bool = True) → Mol#

Renumber the atoms according to the atom map numbers in the molecule.

It is okay if the atom map number is not continuous, as the renumbering is based on the ordering of the atom map number.

Parameters:

  • mol (Chem.Mol) – The molecule to renumber atoms.

  • update_atom_map (bool, optional) – Whether to update the atom map numbers of the molecule. Defaults to True. If False, the atom map numbers will be kept. If True, the atom map numbers will be reset be consistent with atomic number.

Returns:

Chem.Mol – The molecule with renumbered atoms.

rdtools.atommap.renumber_atoms_by_map_dict(mol: Mol, new_order: dict[int, int], update_atom_map: bool = True) → Mol#

Renumber the atoms of the molecule according to a dict-based mapping.

Parameters:

  • mol (Chem.Mol) – The molecule to renumber atoms.

  • new_order (dict[int, int]) – The dict-based mapping, it should be a mapping between atoms. E.g., if newOrder is {0: 3, 1: 1, 2: 2, 3: 0}, then atom 0 in the original molecule will be atom 3 in the new one. Unlike the list case, the newOrder can be a partial mapping, but one should make sure all the pairs are consistent. E.g.,``{0: 3}`` and {0: 3, 3: 0} are also acceptable input for {0: 3, 1: 1, 2: 2, 3: 0}, but you can’t have inconsistent ones like {0: 3, 3: 2}.

  • update_atom_map (bool, optional) – Whether to update the atom map numbers of the molecule. Defaults to True.

Returns:

Chem.Mol – The molecule with renumbered atoms.

rdtools.atommap.renumber_atoms_by_substruct_match_result(mol: Mol, substruct_match_result: Iterable[int], as_ref: bool = True, update_atom_map: bool = True) → Mol#

Renumber the atoms of the molecule according to the substruct match result.

Parameters:

  • mol (Chem.Mol) – The molecule to renumber atoms.

  • substruct_match_result (Iterable[int]) – The substruct match result. it should be a tuple of atom indices. E.g., if the substruct match result is (0, 2, 3), then atom 0 in the original molecule will be atom 0 in the new one, atom 2 in the original molecule will be atom 1 in the new one, and atom 3 in the original molecule will be atom 2 in the new one.

  • as_ref (bool, optional) – The molecule to renumber is used as the reference molecule during the substructure match (i.e., mol is the query molecule).

  • update_atom_map (bool, optional) – Whether to update the atom map numbers of the molecule. Defaults to True.

Returns:

Chem.Mol – The molecule with renumbered atoms.

rdtools.atommap.reset_atom_map_numbers(mol: Mol) → None#

Reset atom map numbers according to the atom indices.

Parameters:

mol (Chem.Mol) – The molecule to reset atom map numbers.

rdtools.atommap.reverse_map(map: Iterable[int], as_list: Literal[True]) → List[int]#
rdtools.atommap.reverse_map(map: Iterable[int], as_list: Literal[False]) → npt.NDArray[np.int_]
rdtools.atommap.reverse_map(map: Iterable[int]) → List[int]

Inverse-transform the index and value relationship in a mapping.

E.g., when doing a subgraph match, RDKit will returns a list that the indexes correspond to the reference molecule and the values correspond to the probing molecule. To recover the reference molecule, one needs to get the reverse map and renumber the atoms of probing molecule with the reverse map.

Parameters:

  • map (Iterable[int]) – An atom mapping as a list (1D array).

  • as_list (bool, optional) – Output result as a list object. Otherwise, the output is a np.ndarray.

Returns:

Union[npt.NDArray[np.int_], List[int]] – An inverted atom map from the given match atom map

rdtools.atommap.update_product_atom_map_after_reaction(mol: Mol, ref_mol: Mol) → list[Atom]#

Update the atom map number of the product molecule after reaction.

The renumbering is according to the reference molecule (usually the reactant). The operation is in-place.

Parameters:

  • mol (Chem.Mol) – The product molecule after reaction.

  • ref_mol (Chem.Mol) – The reference molecule (usually the reactant).

Returns:

list[Chem.Atom] – atoms that are updated.