polymerist.rdutils.chemlabel
============================

.. py:module:: polymerist.rdutils.chemlabel

.. autoapi-nested-parse::

   For reading, writing, and clearing labels from RDKit Atoms, Bonds, and Mols



Functions
---------

.. autoapisummary::

   polymerist.rdutils.chemlabel.has_fully_mapped_atoms
   polymerist.rdutils.chemlabel.has_uniquely_mapped_atoms
   polymerist.rdutils.chemlabel.map_numbers_by_atom_idxs
   polymerist.rdutils.chemlabel.atom_idxs_by_map_numbers
   polymerist.rdutils.chemlabel.get_bond_by_map_num_pair
   polymerist.rdutils.chemlabel.assign_atom_map_nums_by_ids
   polymerist.rdutils.chemlabel.assign_ordered_atom_map_nums
   polymerist.rdutils.chemlabel.relabel_map_nums
   polymerist.rdutils.chemlabel.mol_to_smiles_and_atom_permutation
   polymerist.rdutils.chemlabel.assign_contiguous_atom_map_nums
   polymerist.rdutils.chemlabel.clear_atom_map_nums
   polymerist.rdutils.chemlabel.clear_atom_isotopes


Module Contents
---------------

.. py:function:: has_fully_mapped_atoms(rdmol: rdkit.Chem.rdchem.Mol) -> bool

   Check whether an RDKit Mol has a map number explicitly assigned to each member Atom


.. py:function:: has_uniquely_mapped_atoms(rdmol: rdkit.Chem.rdchem.Mol, skip_unmapped: bool = False) -> bool

   Check whether an RDKit Mol has distinct atom map numbers for each member Atom
   If skip_unmapped=False (default), will check map numbers on ALL atoms;
   If skip_unmapped=True, however, will only check uniqueness of NONZERO map number (i.e. explicitly-mapped) atoms


.. py:function:: map_numbers_by_atom_idxs(rdmol: rdkit.Chem.rdchem.Mol, *atom_idxs: list[int]) -> Generator[Optional[int], None, None]

   Get assigned atom map numbers for a collection of atom ids, in the same order as the internal RDKit Mol atom IDs


.. py:function:: atom_idxs_by_map_numbers(rdmol: rdkit.Chem.rdchem.Mol, *map_numbers: list[int]) -> Generator[Optional[int], None, None]

   Returns the first occurences of the atom IDs of any number of atoms, indexed by atom map number


.. py:function:: get_bond_by_map_num_pair(rdmol: rdkit.Chem.rdchem.Mol, map_num_pair: tuple[int, int], as_bond: bool = True) -> Optional[Union[int, rdkit.Chem.rdchem.Bond]]

   Get the bond spanning a pair of atoms with given pair of atom map numbers
   Returns the RDkit.Bond object if as_bond=True, and the index of the bond if as_bond=False

   If no bond exists between the atoms, will return None regardless of the value of "as_bond"


.. py:function:: assign_atom_map_nums_by_ids(rdmol: rdkit.Chem.rdchem.Mol, map_nums_by_ids: dict[int, int]) -> None

   Assigns atom map numbers to Atoms in a Mol as identified by a mapping of atom indices to map numbers

   :Parameters: * **rdmol** (*Chem.Mol*) -- An RDKit molecule to assign labels to
                * **map_nums_by_ids** (*dict[int, int]*) -- A dict keyed by atom index and mapping to the corresponding desired atom map numbers


.. py:function:: assign_ordered_atom_map_nums(rdmol: rdkit.Chem.rdchem.Mol, start_from: int = 1) -> None

   Assigns atom's index as its atom map number for all atoms in an RDmol
   Can optionally specify what value to begin counting from (by default 1)


.. py:function:: relabel_map_nums(rdmol: rdkit.Chem.rdchem.Mol, relabeling: dict[int, int]) -> None

   Applies a relabelling of atom map numbers to a subset of mapped atoms (described by a dict of old_map_num : new_map_num)


.. py:function:: mol_to_smiles_and_atom_permutation(mol: rdkit.Chem.rdchem.Mol, *args, **kwargs) -> tuple[str, list[int]]

   Convert RDKit Mol to SMILES string (with any SMILES writer parameters passed to as args/kwargs)
   AND return permutation list which maps atoms in the written SMILES to their order in the passed Mol

   Useful when preserving Mol atom order in SMILES is necessary (not true in general)

   :Parameters: * **mol** (*Chem.Mol*) -- The RDKit Mol object
                * **\*args, \*\*kwargs** -- Additional arguments passed to the SMILES writer

   :returns: * **smiles** (*str*) -- The resulting SMILES string
             * **atom_perm_inv** (*list[int]*) -- List representation of the permutation that restores atom order

               E.g. the following call, using "smiles" returned above, will in general scramble atom order:
               >>> from rdkit.Chem.rdmolfiles import MolToSmiles
               >>> mol = MolFromSmiles(smiles) # atom order doesn't match that of exporting Mol

               However, atom order can easily be restored by calling:
               >>> from rdkit.Chem.rdmolops import RenumberAtoms
               >>> mol = RenumberAtoms(mol, atom_perm_inv)
             * *tuple[str, list[int]]* -- A tuple containing the SMILES string and the atom permutation list.


.. py:function:: assign_contiguous_atom_map_nums(*rdmols: Iterable[rdkit.Chem.rdchem.Mol], start_from: int = 1, in_place: bool = False) -> Optional[list[rdkit.Chem.rdchem.Mol]]

   Assign sequential numbering to a collection of molecules such that their map numbers span a contiguous range of integers
   Can optionally specify what value to begin counting from (by default 1)


.. py:function:: clear_atom_map_nums(rdmol: rdkit.Chem.rdchem.Mol) -> None

   Removes atom map numbers from all atoms in an RDKit Mol


.. py:function:: clear_atom_isotopes(rdmol: rdkit.Chem.rdchem.Mol) -> None

   Removes isotope numbers from all atoms in an RDKit Mol