datamol

Module mol

mol

add_hs(mol, explicit_only=False, add_coords=False, only_on_atoms=None, add_residue_info=False, copy=True)

Adds hydrogens to the molecule.

Parameters:

Name	Type	Description	Default
mol	Mol	a molecule.	required
explicit_only	bool	whether to only add explicit hydrogens.	False
add_coords	bool	whether to add 3D coordinates to the hydrogens.	False
only_on_atoms	Optional[List[int]]	a list of atoms to add hydrogens only on.	None
add_residue_info	bool	whether to add residue information to the hydrogens. Useful for PDB files.	False
copy	bool	whether to copy the input molecule.	True

Source code in datamol/mol.py

def add_hs(
    mol: Mol,
    explicit_only: bool = False,
    add_coords: bool = False,
    only_on_atoms: Optional[List[int]] = None,
    add_residue_info: bool = False,
    copy: bool = True,
):
    """Adds hydrogens to the molecule.

    Args:
        mol: a molecule.
        explicit_only: whether to only add explicit hydrogens.
        add_coords: whether to add 3D coordinates to the hydrogens.
        only_on_atoms: a list of atoms to add hydrogens only on.
        add_residue_info: whether to add residue information to the hydrogens.
            Useful for PDB files.
        copy: whether to copy the input molecule.
    """

    if copy:
        mol = copy_mol(mol)

    mol = AddHs(
        mol,
        explicitOnly=explicit_only,
        addCoords=add_coords,
        onlyOnAtoms=only_on_atoms,
        addResidueInfo=add_residue_info,
    )

    return mol

adjust_singleton(mol)

Remove all atoms that are essentially disconnected singleton nodes in the molecular graph. For example, the chlorine atom and methane fragment will be removed in Cl.[N:1]1=CC(O)=CC2CCCCC12.CC.C", but not the ethane fragment.

Parameters:

Name	Type	Description	Default
mol	Mol	a molecule.	required

Source code in datamol/mol.py

def adjust_singleton(mol: Mol) -> Optional[Mol]:
    """Remove all atoms that are essentially disconnected singleton nodes in the molecular graph.
    For example, the chlorine atom and methane fragment will be removed in Cl.[N:1]1=CC(O)=CC2CCCCC12.CC.C",
    but not the ethane fragment.

    Args:
        mol: a molecule.
    """
    to_rem = []
    em = RWMol(mol)
    for atom in mol.GetAtoms():
        if atom.GetExplicitValence() == 0:
            to_rem.append(atom.GetIdx())
    to_rem.sort(reverse=True)
    for a_idx in to_rem:
        em.RemoveAtom(a_idx)
    return em.GetMol()

atom_indices_to_mol(mol, copy=False)

Add the molAtomMapNumber property to each atoms.

Parameters:

Name	Type	Description	Default
mol	Mol	a molecule	required
copy	bool	Whether to copy the molecule.	False

Source code in datamol/mol.py

def atom_indices_to_mol(mol: Mol, copy: bool = False):
    """Add the `molAtomMapNumber` property to each atoms.

    Args:
        mol: a molecule
        copy: Whether to copy the molecule.
    """

    if copy is True:
        mol = copy_mol(mol)

    for atom in mol.GetAtoms():
        atom.SetProp("molAtomMapNumber", str(atom.GetIdx()))
    return mol

atom_list_to_bond(mol, atom_indices, bond_as_idx=False)

Return a list of existing bond indices between a list of atom indices.

Parameters:

Name	Type	Description	Default
mol	Mol	A molecule.	required
atom_indices	List[int]	A list of atom indices.	required

Source code in datamol/mol.py

def atom_list_to_bond(
    mol: Mol,
    atom_indices: List[int],
    bond_as_idx: bool = False,
):
    """Return a list of existing bond indices between a list of
    atom indices.

    Args:
        mol: A molecule.
        atom_indices: A list of atom indices.
    """

    # Build an atom map
    atom_map = {}
    submol = PathToSubmol(mol, atom_indices, useQuery=True, atomMap=atom_map)
    atom_map_reversed = {v: k for k, v in atom_map.items()}

    bonds = []

    for bond in submol.GetBonds():
        a1, a2 = bond.GetBeginAtomIdx(), bond.GetEndAtomIdx()
        ori_a1 = atom_map_reversed[a1]
        ori_a2 = atom_map_reversed[a2]

        if ori_a1 in atom_indices and ori_a2 in atom_indices:
            ori_bond = mol.GetBondBetweenAtoms(ori_a1, ori_a2)
            if bond_as_idx:
                bonds.append(ori_bond.GetIdx())
            else:
                bonds.append(ori_bond)

    return bonds

clear_mol_props(mol, copy=True, include_private=False, include_computed=False)

Clear all properties from a molecule.

Parameters:

Name	Type	Description	Default
mol	Mol	A molecule.	required
copy	bool	Whether to copy the molecule.	True

Source code in datamol/mol.py

def clear_mol_props(
    mol: Mol,
    copy: bool = True,
    include_private: bool = False,
    include_computed: bool = False,
):
    """Clear all properties from a molecule.

    Args:
        mol: A molecule.
        copy: Whether to copy the molecule.
    """

    if copy:
        mol = copy_mol(mol)

    props = mol.GetPropsAsDict(includePrivate=include_private, includeComputed=include_computed)

    for key in props.keys():
        mol.ClearProp(key)

    return mol

compute_ring_system(mol, include_spiro=True)

Compute the list of ring system in a molecule. This is based on RDKit's cookbook: https://www.rdkit.org/docs/Cookbook.html#rings-aromaticity-and-kekulization

Parameters:

Name	Type	Description	Default
mol	Mol	input molecule	required
include_spiro	bool	whether to include spiro rings.	True

Returns:

Name	Type	Description
ring_system	List[Set[int]]	list of ring system (atom indices).

Source code in datamol/mol.py

def compute_ring_system(mol: Mol, include_spiro: bool = True) -> List[Set[int]]:
    """Compute the list of ring system in a molecule. This is based on RDKit's cookbook:
    https://www.rdkit.org/docs/Cookbook.html#rings-aromaticity-and-kekulization

    Args:
        mol: input molecule
        include_spiro: whether to include spiro rings.

    Returns:
        ring_system: list of ring system (atom indices).
    """
    ri = mol.GetRingInfo()
    systems = []
    for ring in ri.AtomRings():
        ringAts = set(ring)
        nSystems = []
        for system in systems:
            nInCommon = len(ringAts.intersection(system))
            if nInCommon and (include_spiro or nInCommon > 1):
                ringAts = ringAts.union(system)
            else:
                nSystems.append(system)
        nSystems.append(ringAts)
        systems = nSystems
    return systems

copy_mol(mol)

Copy a molecule and return a new one.

Parameters:

Name	Type	Description	Default
mol	Mol	a molecule to copy.	required

Source code in datamol/mol.py

def copy_mol(mol: Mol) -> Mol:
    """Copy a molecule and return a new one.

    Args:
        mol: a molecule to copy.
    """
    return copy.deepcopy(mol)

copy_mol_props(source, destination, include_private=False, include_computed=False)

Copy properties from one source molecule to another destination molecule.

Parameters:

Name	Type	Description	Default
source	Mol	a molecule to copy from.	required
destination	Mol	a molecule to copy to.	required
include_private	bool	Include private properties.	False
include_computed	bool	Include computed properties.	False

Source code in datamol/mol.py

def copy_mol_props(
    source: Mol,
    destination: Mol,
    include_private: bool = False,
    include_computed: bool = False,
):
    """Copy properties from one source molecule to another destination
    molecule.

    Args:
        source: a molecule to copy from.
        destination: a molecule to copy to.
        include_private: Include private properties.
        include_computed: Include computed properties.
    """

    props = source.GetPropsAsDict(includePrivate=include_private, includeComputed=include_computed)
    set_mol_props(destination, props)

decrease_bond(bond)

Remove one single bond from the input bond. Note that you should first kekulize your molecules and remove non-standard bond.

Parameters:

Name	Type	Description	Default
bond	Chem.rdchem.Bond	a bond.	required

Source code in datamol/mol.py

def decrease_bond(bond: Chem.rdchem.Bond) -> Optional[Union[list, Chem.rdchem.Bond]]:
    """Remove one single bond from the input bond. Note that you should
    first kekulize your molecules and remove non-standard bond.

    Args:
        bond: a bond.
    """
    if bond.GetBondType() == TRIPLE_BOND:
        return DOUBLE_BOND
    if bond.GetBondType() == DOUBLE_BOND:
        return SINGLE_BOND
    if bond.GetBondType() == SINGLE_BOND:
        return None
    return bond

fix_mol(mol, n_iter=1, remove_singleton=False, largest_only=False, inplace=False)

Fix error in molecule using a greedy approach.

Parameters:

Name	Type	Description	Default
mol	Mol	input molecule to fix	required
n_iter	int	Number of valence fix iteration to apply	1
remove_singleton	bool	Whether adjust_singleton should be applied	False
largest_only	bool	Whether only the largest fragment should be kept	False
inplace	bool	Whether to return a copy of the mol or perform in place operation	False

Returns:

Type	Description
Optional[Mol]	Fixed molecule.

Source code in datamol/mol.py

def fix_mol(
    mol: Mol,
    n_iter: int = 1,
    remove_singleton: bool = False,
    largest_only: bool = False,
    inplace: bool = False,
) -> Optional[Mol]:
    """Fix error in molecule using a greedy approach.

    Args:
        mol: input molecule to fix
        n_iter: Number of valence fix iteration to apply
        remove_singleton: Whether `adjust_singleton` should be applied
        largest_only: Whether only the largest fragment should be kept
        inplace: Whether to return a copy of the mol or perform in place operation

    Returns:
        Fixed molecule.
    """

    if not inplace:
        mol = copy.copy(mol)

    m = sanitize_mol(mol) or mol  # fail back to mol when the fixer fail

    if m is not None:
        m = remove_dummies(m)
        for _ in range(n_iter):
            m = fix_valence(m)

        if remove_singleton:
            m = adjust_singleton(m)

        if largest_only:
            # m = max(Chem.rdmolops.GetMolFrags(m, asMols=True, sanitizeFrags=False), key=lambda m: m.GetNumAtoms())
            m = rdMolStandardize.FragmentParent(m, skipStandardize=True)

    return m

fix_valence(mol, inplace=False, allow_ring_break=False)

Identify and try to fix valence issues by removing any supplemental bond that should not be in the graph.

Parameters:

Name	Type	Description	Default
mol		input molecule with incorrect valence for some atoms	required
inplace	bool	Whether to modify in place or make a copy	False
allow_ring_break	bool	Whether bond removal involving ring is allowed.	False

Returns:

Type	Description
Optional[Mol]	Fixed potential valence issue in molecule or original molecule when nothing is broken
Optional[Mol]	of if failed.

Source code in datamol/mol.py

def fix_valence(mol, inplace: bool = False, allow_ring_break: bool = False) -> Optional[Mol]:
    """Identify and try to fix valence issues by removing any supplemental bond
    that should not be in the graph.

    Args:
        mol: input molecule with incorrect valence for some atoms
        inplace: Whether to modify in place or make a copy
        allow_ring_break: Whether bond removal involving ring is allowed.

    Returns:
        Fixed potential valence issue in molecule or original molecule when nothing is broken
        of if failed.
    """
    if not inplace:
        mol = copy.copy(mol)

    vm = rdMolStandardize.RDKitValidation()
    if len(vm.validate(mol)) == 0:  # don't fix something that is not broken
        return mol

    try:
        m = remove_hs(
            mol,
            implicit_only=False,
            update_explicit_count=True,
            sanitize=False,
        )
        m.UpdatePropertyCache(False)

        # first pass using explicit false count
        for atom in m.GetAtoms():
            while incorrect_valence(atom) and atom.GetTotalNumHs() > 0:
                cur_hydrogen = atom.GetTotalNumHs()
                atom.SetNumExplicitHs(max(0, cur_hydrogen - 1))
                atom.SetFormalCharge(max(0, atom.GetFormalCharge() - 1))
                # atom.SetNumRadicalElectrons(0)
            atom.UpdatePropertyCache(False)

        em = RWMol(m)
        bonds = em.GetBonds()
        bonds = [
            bond
            for bond in bonds
            if any(
                [
                    incorrect_valence(bond.GetBeginAtom()),
                    incorrect_valence(bond.GetEndAtom()),
                ]
            )
        ]
        for bond in bonds:
            a1 = bond.GetBeginAtom()
            a2 = bond.GetEndAtom()
            if incorrect_valence(a1) or incorrect_valence(a2):
                mbond = decrease_bond(bond)
                if allow_ring_break or (mbond or not bond.IsInRing()):
                    em.RemoveBond(a1.GetIdx(), a2.GetIdx())
                    if mbond is not None:
                        em.AddBond(a1.GetIdx(), a2.GetIdx(), mbond)
            a1.UpdatePropertyCache(False)
            a2.UpdatePropertyCache(False)
        m = em.GetMol()

    except Exception:
        return None

    return m

fix_valence_charge(mol, inplace=False)

Fix valence issues that are due to incorrect charges.

Parameters:

Name	Type	Description	Default
mol	Mol	Input molecule with incorrect valence for some atoms	required
inplace	bool	Whether to modify in place or make a copy.	False

Returns:

Type	Description
Optional[Mol]	Fixed molecule via charge correction or original molecule if failed.

Source code in datamol/mol.py

def fix_valence_charge(mol: Mol, inplace: bool = False) -> Optional[Mol]:
    """Fix valence issues that are due to incorrect charges.

    Args:
        mol: Input molecule with incorrect valence for some atoms
        inplace: Whether to modify in place or make a copy.

    Returns:
        Fixed molecule via charge correction or original molecule if failed.
    """

    vm = rdMolStandardize.RDKitValidation()

    # Don't fix something that is not broken
    if len(vm.validate(mol)) > 0:

        if not inplace:
            mol = copy.copy(mol)

        mol.UpdatePropertyCache(False)
        for a in mol.GetAtoms():
            n_electron = (
                a.GetImplicitValence()
                + a.GetExplicitValence()
                - PERIODIC_TABLE.GetDefaultValence(a.GetSymbol())
            )
            a.SetFormalCharge(n_electron)

    return mol

incorrect_valence(a, update=False)

Check if an atom connection is not valid or all the atom of a molecule.

Parameters:

Name	Type	Description	Default
a	Union[Mol, Chem.rdchem.Atom]	atom or molecule to check for valence issue.	required
update	bool	Update owning molecule property cache first.	False

Returns:

Type	Description
bool	Whether the input atom valence is correct.

Source code in datamol/mol.py

def incorrect_valence(a: Union[Mol, Chem.rdchem.Atom], update: bool = False) -> bool:
    """Check if an atom connection is not valid or all the atom of a molecule.

    Args:
        a: atom or molecule to check for valence issue.
        update: Update owning molecule property cache first.

    Returns:
        Whether the input atom valence is correct.
    """
    if isinstance(a, Mol):
        a.UpdatePropertyCache(False)
        vm = rdMolStandardize.RDKitValidation()
        return len(vm.validate(a)) > 0

    if update:
        m = a.GetOwningMol()
        m.UpdatePropertyCache(False)
    return (a.GetImplicitValence() == 0) and (
        a.GetExplicitValence() > max(PERIODIC_TABLE.GetValenceList(a.GetSymbol()))
    )

is_transition_metal(at)

Check if atom is a transition metal.

Parameters:

Name	Type	Description	Default
at	Chem.rdchem.Atom	an atom.	required

Source code in datamol/mol.py

def is_transition_metal(at: Chem.rdchem.Atom) -> bool:
    """Check if atom is a transition metal.

    Args:
        at: an atom.
    """
    n = at.GetAtomicNum()
    return (n >= 22 and n <= 29) or (n >= 40 and n <= 47) or (n >= 72 and n <= 79)

keep_largest_fragment(mol)

Only keep largest fragment of each molecule.

Source code in datamol/mol.py

def keep_largest_fragment(mol: Mol) -> Optional[Mol]:
    """Only keep largest fragment of each molecule."""
    return max(
        GetMolFrags(mol, asMols=True),
        default=mol,
        key=lambda m: m.GetNumAtoms(),
    )

make_scaffold_generic(mol, include_bonds=False)

Make the atom in a scaffold or molecule generic.

Parameters:

Name	Type	Description	Default
mol	Mol	A molecule or a scaffold.	required
include_bonds	bool	Whether we should also update bond order or keep as is.	False

Source code in datamol/mol.py

def make_scaffold_generic(mol: Mol, include_bonds: bool = False):
    """Make the atom in a scaffold or molecule generic.

    Args:
        mol: A molecule or a scaffold.
        include_bonds: Whether we should also update bond order or keep as is.
    """

    for atom in mol.GetAtoms():
        if atom.GetAtomicNum() != 1:
            atom.SetAtomicNum(0)

        atom.SetFormalCharge(0)
        atom.SetChiralTag(rdchem.ChiralType.CHI_UNSPECIFIED)
        atom.SetNoImplicit(0)
        atom.SetNumExplicitHs(0)

    if include_bonds:
        for bond in mol.GetBonds():
            bond.SetBondType(UNSPECIFIED_BOND)

    return mol

protect_atoms(mol, substruct=None, atoms=None, in_place=False)

Protect a list of atoms or substruct in a molecule.

The _protected attributes of a molecule is used by RDKit in several functions, especially for reactions where "protected" atoms are disallowed from taking part in reactions.

Parameters:

Name	Type	Description	Default
mol	Mol	input molecule to protect	required
substruct	Optional[Mol]	optional substructure query to identify atoms to protect	None
atoms	Optional[Union[List[int], int]]	optional list of atom indices to protect	None
in_place	bool	whether to perform the protection in place or return a copy of the molecule	False

Source code in datamol/mol.py

def protect_atoms(
    mol: Mol,
    substruct: Optional[Mol] = None,
    atoms: Optional[Union[List[int], int]] = None,
    in_place: bool = False,
) -> Mol:
    """Protect a list of atoms or substruct in a molecule.

    The _protected attributes of a molecule is used by RDKit in several functions, especially for reactions
    where "protected" atoms are disallowed from taking part in reactions.

    Args:
        mol: input molecule to protect
        substruct: optional substructure query to identify atoms to protect
        atoms: optional list of atom indices to protect
        in_place: whether to perform the protection in place or return a copy of the molecule
    """
    if atoms is None:
        atoms = []
    elif not isinstance(atoms, (tuple, list)):
        atoms = [atoms]

    # do not perform protection in place
    if in_place:
        mol_copy = mol
    else:
        mol_copy = copy_mol(mol)

    if substruct is not None:
        matches = mol_copy.GetSubstructMatches(substruct)
        atoms.extend(itertools.chain(*matches))

    for a in atoms:
        if a is None:
            continue
        mol_copy.GetAtomWithIdx(a).SetProp("_protected", "1")

    return mol_copy

randomize_atoms(mol)

Randomize the position of the atoms in a mol.

Parameters:

Name	Type	Description	Default
mol	Mol	a molecule.	required

Returns:

Name	Type	Description
mol	Optional[Mol]	a molecule.

Source code in datamol/mol.py

def randomize_atoms(mol: Mol) -> Optional[Mol]:
    """Randomize the position of the atoms in a mol.

    Args:
        mol: a molecule.

    Returns:
        mol: a molecule.
    """
    if mol.GetNumAtoms() == 0:
        return mol

    atom_indices = list(range(mol.GetNumAtoms()))
    random.shuffle(atom_indices)
    return RenumberAtoms(mol, atom_indices)

remove_dummies(mol, dummy='*')

Remove dummy atoms from molecules.

Source code in datamol/mol.py

def remove_dummies(mol: Mol, dummy: str = "*") -> Optional[Mol]:
    """Remove dummy atoms from molecules."""

    du = to_mol(dummy)
    out = mol

    try:
        out = ReplaceSubstructs(mol, du, to_mol("[H]"), True)[0]
        out = remove_hs(out)
    except Exception:
        out = DeleteSubstructs(mol, du)
    return out

remove_hs(mol, implicit_only=False, update_explicit_count=False, sanitize=True, copy=True)

Removes hydrogens from a molecule.

Parameters:

Name	Type	Description	Default
mol	Mol	a molecule.	required
implicit_only	bool	whether to only remove implicit hydrogens.	False
update_explicit_count	bool	whether to update the explicit hydrogen count.	False
sanitize	bool	whether to sanitize the molecule after the hydrogens are removed.	True
copy	bool	whether to copy the input molecule.	True

Source code in datamol/mol.py

def remove_hs(
    mol: Mol,
    implicit_only: bool = False,
    update_explicit_count: bool = False,
    sanitize: bool = True,
    copy: bool = True,
):
    """Removes hydrogens from a molecule.

    Args:
        mol: a molecule.
        implicit_only: whether to only remove implicit hydrogens.
        update_explicit_count: whether to update the explicit hydrogen count.
        sanitize: whether to sanitize the molecule after the hydrogens are removed.
        copy: whether to copy the input molecule.
    """

    if copy:
        mol = copy_mol(mol)

    mol = RemoveHs(
        mol,
        implicitOnly=implicit_only,
        updateExplicitCount=update_explicit_count,
        sanitize=sanitize,
    )

    return mol

reorder_atoms(mol, break_ties=True, include_chirality=True, include_isotopes=True)

Reorder the atoms in a mol. It ensures a single atom order for the same molecule, regardless of its original representation.

Parameters:

Name	Type	Description	Default
mol	Mol	a molecule.	required
break_ties	bool	Force breaking of ranked ties.	True
include_chirality	bool	Use chiral information when computing rank.	True
include_isotopes	bool	Use isotope information when computing rank.	True

Returns:

Name	Type	Description
mol	Optional[Mol]	a molecule.

Source code in datamol/mol.py

def reorder_atoms(
    mol: Mol,
    break_ties: bool = True,
    include_chirality: bool = True,
    include_isotopes: bool = True,
) -> Optional[Mol]:
    """Reorder the atoms in a mol. It ensures a single atom order for the same molecule,
    regardless of its original representation.

    Args:
        mol: a molecule.
        break_ties: Force breaking of ranked ties.
        include_chirality: Use chiral information when computing rank.
        include_isotopes: Use isotope information when computing rank.

    Returns:
        mol: a molecule.
    """
    if mol.GetNumAtoms() == 0:
        return mol

    new_order = CanonicalRankAtoms(
        mol,
        breakTies=break_ties,
        includeChirality=include_chirality,
        includeIsotopes=include_isotopes,
    )
    new_order = sorted([(y, x) for x, y in enumerate(new_order)])
    return RenumberAtoms(mol, [y for (x, y) in new_order])

replace_dummies_atoms(mol, atom='C', dummy='*', replace_all=True)

Remove dummy atoms from molecules.

Parameters:

Name	Type	Description	Default
mol	Mol	molecule with dummies	required
atom	str	replacement atom, default is carbon	'C'
dummy	str	dummy atom representation	'*'
replace_all	bool	Whether to replace all dummies	True

Returns:

Name	Type	Description
mol	Optional[Mol]	Molecule with dummy replaced

Source code in datamol/mol.py

def replace_dummies_atoms(
    mol: Mol,
    atom: str = "C",
    dummy: str = "*",
    replace_all: bool = True,
) -> Optional[Mol]:
    """Remove dummy atoms from molecules.

    Args:
        mol: molecule with dummies
        atom: replacement atom, default is carbon
        dummy: dummy atom representation
        replace_all: Whether to replace all dummies

    Returns:
        mol: Molecule with dummy replaced
    """
    du = to_mol(dummy)
    replacement = to_mol(atom)
    out = ReplaceSubstructs(mol, du, replacement, replaceAll=replace_all)[0]
    return out

same_mol(mol1, mol2, use_non_standard_inchikey=False)

Check two molecules are the same by comparing their InChiKey.

Invalid molecules (None) are always considered as not the same.

Parameters:

Name	Type	Description	Default
mol1	Optional[Mol]	A molecule.	required
mol2	Optional[Mol]	A molecule.	required
use_non_standard_inchikey	bool	Whether to use the standard or non-standard InChiKey.	False

Source code in datamol/mol.py

def same_mol(
    mol1: Optional[Mol],
    mol2: Optional[Mol],
    use_non_standard_inchikey: bool = False,
) -> bool:
    """Check two molecules are the same by comparing their InChiKey.

    Invalid molecules (None) are always considered as not the same.

    Args:
        mol1: A molecule.
        mol2: A molecule.
        use_non_standard_inchikey: Whether to use the standard or non-standard InChiKey.
    """

    if mol1 is None or mol2 is None:
        return False

    if use_non_standard_inchikey:
        return to_inchikey_non_standard(mol1) == to_inchikey_non_standard(mol2)
    else:
        return to_inchikey(mol1) == to_inchikey(mol2)

sanitize_first(mols, charge_neutral=False, sanifix=True)

Sanitize a list of molecules and return the first valid molecule seen in the list.

Parameters:

Name	Type	Description	Default
mols	List[Mol]	a list of molecules.	required
charge_neutral	bool	whether charge neutralization should be applied.	False
sanifix	bool	whether to run the sanifix from James Davidson (sanifix4.py) that try to adjust aromatic nitrogens.	True

Returns:

Name	Type	Description
mol		a molecule.

Source code in datamol/mol.py

def sanitize_first(mols: List[Mol], charge_neutral: bool = False, sanifix: bool = True):
    """Sanitize a list of molecules and return the first valid molecule seen in the list.

    Args:
        mols: a list of molecules.
        charge_neutral: whether charge neutralization should be applied.
        sanifix: whether to run the sanifix from James Davidson
            (sanifix4.py) that try to adjust aromatic nitrogens.

    Returns:
        mol: a molecule.
    """
    for mol in mols:
        mol = sanitize_mol(mol, charge_neutral=charge_neutral, sanifix=sanifix)
        if mol:
            return mol
    return None

sanitize_mol(mol, charge_neutral=False, sanifix=True, verbose=True, add_hs=False)

An augmented version of RDKit sanitize=True. It uses a mol-SMILES-mol conversion to catch potential aromaticity errors and try to fix aromatic nitrogen (using the popular sanifix4 script). Optionally, it can neutralize the charge of the molecule.

Note #1: Only the first conformer (if present) will be preserved and a warning will be displayed if more than one conformer is detected.

Note #2: The molecule's properties will be preserved but the atom's properties will be lost.

Parameters:

Name	Type	Description	Default
mol	Mol	a molecule.	required
charge_neutral	bool	whether charge neutralization should be applied.	False
sanifix	bool	whether to run the sanifix from James Davidson (sanifix4.py) that try to adjust aromatic nitrogens.	True
verbose	bool	Whether displaying a warning about multiple conformers.	True
add_hs	bool	Add hydrogens to the returned molecule. Useful when the input molecule already contains hydrogens.	False

Returns:

Name	Type	Description
mol	Optional[Mol]	a molecule.

Source code in datamol/mol.py

def sanitize_mol(
    mol: Mol,
    charge_neutral: bool = False,
    sanifix: bool = True,
    verbose: bool = True,
    add_hs: bool = False,
) -> Optional[Mol]:
    """An augmented version of RDKit `sanitize=True`. It uses a
    mol-SMILES-mol conversion to catch potential aromaticity errors
    and try to fix aromatic nitrogen (using the popular sanifix4 script).
    Optionally, it can neutralize the charge of the molecule.

    Note #1: Only the first conformer (if present) will be preserved and
    a warning will be displayed if more than one conformer is detected.

    Note #2: The molecule's properties will be preserved but the atom's
    properties will be lost.

    Args:
        mol: a molecule.
        charge_neutral: whether charge neutralization should be applied.
        sanifix: whether to run the sanifix from James Davidson
            (sanifix4.py) that try to adjust aromatic nitrogens.
        verbose: Whether displaying a warning about multiple conformers.
        add_hs: Add hydrogens to the returned molecule. Useful when the input
            molecule already contains hydrogens.

    Returns:
        mol: a molecule.
    """
    if mol is None:
        return mol

    # Extract properties.
    original_mol = copy_mol(mol)
    properties = original_mol.GetPropsAsDict()

    if charge_neutral:
        mol = to_neutral(mol)

    if sanifix:
        mol = _sanifix4.sanifix(mol)

    if mol is not None:

        # Detect multiple conformers
        if verbose and mol.GetNumConformers() > 1:
            logger.warning(
                f"The molecule contains multiple conformers. Only the first one will be preserved."
            )

        # Try catch to avoid occasional aromaticity errors
        try:
            # `cxsmiles` is used here to preserve the first conformer.
            mol = to_mol(to_smiles(mol, cxsmiles=True), sanitize=True, add_hs=add_hs)
        except Exception:
            mol = None

    if mol is not None:
        # Insert back properties.
        mol = set_mol_props(mol, properties)

    return mol

sanitize_smiles(smiles, isomeric=True)

Takes SMILES string and returns its sanitized version.

Parameters:

Name	Type	Description	Default
smiles	Optional[str]	smiles to be sanitized.	required
isomeric	bool	Whether to include information about stereochemistry in the SMILES.	True

Returns:

Type	Description
Optional[str]	sanitized smiles.

Source code in datamol/mol.py

def sanitize_smiles(smiles: Optional[str], isomeric: bool = True) -> Optional[str]:
    """Takes SMILES string and returns its sanitized version.

    Args:
        smiles: smiles to be sanitized.
        isomeric: Whether to include information about stereochemistry in the SMILES.

    Returns:
        sanitized smiles.
    """

    mol = None

    try:
        mol = to_mol(smiles, sanitize=False)
        mol = sanitize_mol(mol, False)
    except Exception:
        return None

    if mol is None:
        return None

    try:
        smiles = to_smiles(mol, isomeric=isomeric)
    except:
        return None

    return smiles

set_dative_bonds(mol, from_atoms=(7, 8))

Replaces some single bonds between metals and atoms with atomic numbers in fromAtoms with dative bonds. The replacement is only done if the atom has "too many" bonds.

Parameters:

Name	Type	Description	Default
mol	Mol	molecule with bond to modify	required
from_atoms	Tuple[int, int]	List of atoms (symbol or atomic number) to consider for bond replacement. By default, only Nitrogen (7) and Oxygen (8) are considered.	(7, 8)

Returns:

Type	Description
Optional[Mol]	The modified molecule.

Source code in datamol/mol.py

def set_dative_bonds(mol: Mol, from_atoms: Tuple[int, int] = (7, 8)) -> Optional[Mol]:
    """Replaces some single bonds between metals and atoms with atomic numbers in fromAtoms
    with dative bonds. The replacement is only done if the atom has "too many" bonds.

    Arguments:
        mol: molecule with bond to modify
        from_atoms: List of atoms  (symbol or atomic number) to consider for bond replacement.
            By default, only Nitrogen (7) and Oxygen (8) are considered.

    Returns:
        The modified molecule.
    """
    rwmol = RWMol(mol)
    rwmol.UpdatePropertyCache(strict=False)

    metals = [at for at in rwmol.GetAtoms() if is_transition_metal(at)]
    for metal in metals:
        for nbr in metal.GetNeighbors():
            if (nbr.GetAtomicNum() in from_atoms or nbr.GetSymbol() in from_atoms) and (
                nbr.GetExplicitValence() > PERIODIC_TABLE.GetDefaultValence(nbr.GetAtomicNum())
                and rwmol.GetBondBetweenAtoms(nbr.GetIdx(), metal.GetIdx()).GetBondType()
                == SINGLE_BOND
            ):
                rwmol.RemoveBond(nbr.GetIdx(), metal.GetIdx())
                rwmol.AddBond(nbr.GetIdx(), metal.GetIdx(), DATIVE_BOND)
    return rwmol

set_mol_props(mol, props, copy=False)

Set properties to a mol from a dict.

Parameters:

Name	Type	Description	Default
mol	Mol	the mol where to copy the props.	required
props	Dict[str, Any]	the props to copy.	required
copy	bool	whether to copy the provided mol	False

Source code in datamol/mol.py

def set_mol_props(
    mol: Mol,
    props: Dict[str, Any],
    copy: bool = False,
) -> Mol:
    """Set properties to a mol from a dict.

    Args:
        mol: the mol where to copy the props.
        props: the props to copy.
        copy: whether to copy the provided mol

    """

    if copy is True:
        mol = copy_mol(mol)

    for k, v in props.items():
        if isinstance(v, bool):
            mol.SetBoolProp(k, v)
        elif isinstance(v, int):
            # NOTE(hadim): A Python integer is 32 bits and RDKit seems
            # to overflow before that. Here we catch the error
            # and instead uses silently `SetDoubleProp` instead.
            try:
                mol.SetIntProp(k, v)
            except OverflowError:
                mol.SetDoubleProp(k, v)
        elif isinstance(v, float):
            mol.SetDoubleProp(k, v)
        else:
            mol.SetProp(k, str(v))

    return mol

standardize_mol(mol, disconnect_metals=False, normalize=True, reionize=True, uncharge=False, stereo=True)

This function returns a standardized version the given molecule, with or without disconnect the metals. The process is apply in the order of the argument.

Parameters:

Name	Type	Description	Default
mol	Mol	The molecule to standardize.	required
disconnect_metals	bool	Whether to disconnect the metallic atoms from non-metals	False
normalize	bool	Whether to apply normalization (correct functional groups and recombine charges).	True
reionize	bool	Whether to apply molecule reionization	True
uncharge	bool	Whether to remove all charge from molecule	False
stereo	bool	Whether to attempt to assign stereochemistry	True

Returns:

Name	Type	Description
mol		The standardized molecule.

Source code in datamol/mol.py

def standardize_mol(
    mol: Mol,
    disconnect_metals: bool = False,
    normalize: bool = True,
    reionize: bool = True,
    uncharge: bool = False,
    stereo: bool = True,
):
    r"""
    This function returns a standardized version the given molecule, with or without disconnect the metals.
    The process is apply in the order of the argument.

    Arguments:
        mol: The molecule to standardize.
        disconnect_metals: Whether to disconnect the metallic atoms from non-metals
        normalize: Whether to apply normalization (correct functional groups and recombine charges).
        reionize: Whether to apply molecule reionization
        uncharge: Whether to remove all charge from molecule
        stereo: Whether to attempt to assign stereochemistry

    Returns:
        mol: The standardized molecule.
    """
    mol = copy_mol(mol)

    if disconnect_metals:
        md = rdMolStandardize.MetalDisconnector()
        mol = md.Disconnect(mol)

    if normalize:
        mol = rdMolStandardize.Normalize(mol)

    if reionize:
        reionizer = rdMolStandardize.Reionizer()
        mol = reionizer.reionize(mol)

    if uncharge:
        uncharger = rdMolStandardize.Uncharger()
        mol = uncharger.uncharge(mol)

    if stereo:
        AssignStereochemistry(mol, force=False, cleanIt=True)

    return mol

standardize_smiles(smiles, tautomer=False)

Apply smile standardization procedure. This is a convenient function wrapped arrounf RDKit smiles standardizer and tautomeric canonicalization.

Parameters:

Name	Type	Description	Default
smiles	str	Smiles to standardize	required
tautomer	bool	Whether to canonicalize tautomers	False

Returns:

Name	Type	Description
standard_smiles		the standardized smiles

Source code in datamol/mol.py

def standardize_smiles(smiles: str, tautomer: bool = False):
    r"""
    Apply smile standardization procedure. This is a convenient function wrapped arrounf RDKit
    smiles standardizer and tautomeric canonicalization.

    Args:
        smiles: Smiles to standardize
        tautomer: Whether to canonicalize tautomers

    Returns:
        standard_smiles: the standardized smiles
    """

    smiles = rdMolStandardize.StandardizeSmiles(smiles)
    if tautomer:
        smiles = canonicalize_tautomer_smiles(smiles)
    return smiles

strip_mol_to_core(mol, bond_cutter=None)

Strip a molecule to its core, i.e. remove all atoms not in the core. This method 'guess' the molecular core, by finding the ring system.

Parameters:

Name	Type	Description	Default
mol	Mol	A molecule.	required
bond_cutter	Mol	A molecule used to cut the bonds.	None

Source code in datamol/mol.py

def strip_mol_to_core(mol: Mol, bond_cutter: Mol = None):
    """Strip a molecule to its core, i.e. remove all atoms not in the core.
    This method 'guess' the molecular core, by finding the ring system.

    Args:
        mol: A molecule.
        bond_cutter: A molecule used to cut the bonds.
    """

    if bond_cutter is None:
        bond_cutter = from_smarts("[R;!$(*=,#[!#6])]!@!=!#[*;$([A;!R][A;!R])]")

    with without_rdkit_log():

        scaffold = MurckoScaffold.GetScaffoldForMol(mol)
        out = mol.GetSubstructMatches(bond_cutter)
        bond_inds = [mol.GetBondBetweenAtoms(i, j).GetIdx() for i, j in out]

        if len(bond_inds) > 0:
            fragmented = rdmolops.FragmentOnBonds(mol, bond_inds)
            fragmented = remove_dummies(fragmented)
            fragmented = to_scaffold_murcko(fragmented)
            scaffold = keep_largest_fragment(fragmented)

    return scaffold

substructure_matching_bonds(mol, query, **kwargs)

Perform a substructure match using GetSubstructMatches but instead of returning only the atom indices also return the bond indices.

Parameters:

Name	Type	Description	Default
mol	Mol	A molecule.	required
query	Mol	A molecule used as a query to match against.	required
kwargs		Any other arguments to pass to mol.GetSubstructMatches().	required

Returns:

Name	Type	Description
atom_matches		A list of lists of atom indices.
bond_matches		A list of lists of bond indices.

Source code in datamol/mol.py

def substructure_matching_bonds(mol: Mol, query: Mol, **kwargs):
    """Perform a substructure match using `GetSubstructMatches` but instead
    of returning only the atom indices also return the bond indices.

    Args:
        mol: A molecule.
        query: A molecule used as a query to match against.
        kwargs: Any other arguments to pass to `mol.GetSubstructMatches()`.

    Returns:
        atom_matches: A list of lists of atom indices.
        bond_matches: A list of lists of bond indices.
    """

    # NOTE(hadim): If more substructure functions are added here, consider moving it to
    # a dedicated `substructure` module.

    # Set default arguments
    kwargs.setdefault("uniquify", True)

    # Get the matching atom indices
    atom_matches = list(mol.GetSubstructMatches(query, **kwargs))

    # Get the bond to highligh from the query
    query_bond_indices = [
        (bond.GetBeginAtomIdx(), bond.GetEndAtomIdx()) for bond in query.GetBonds()
    ]

    # Retrieve the atom indices
    query_atom_indices = [atom.GetIdx() for i, atom in enumerate(query.GetAtoms())]

    bond_matches = []

    for match in atom_matches:

        # Map the atom of the query to the atom of the mol matching the query
        atom_map = dict(zip(query_atom_indices, match))

        # For this match atoms we now, we use the map to retrieve the matching bonds
        # in the mol.
        mol_bond_indices = [(atom_map[a1], atom_map[a2]) for a1, a2 in query_bond_indices]

        # Convert the bond atom indices to bond indices
        mol_bond_indices = [mol.GetBondBetweenAtoms(a1, a2).GetIdx() for a1, a2 in mol_bond_indices]

        bond_matches.append(mol_bond_indices)

    return atom_matches, bond_matches

to_mol(mol, add_hs=False, explicit_only=False, ordered=False, kekulize=False, sanitize=True)

Convert an input molecule (smiles representation) into a Mol.

Parameters:

Name	Type	Description	Default
mol	Union[str, Mol]	A SMILES or a molecule.	required
add_hs	bool	Whether hydrogens should be added the molecule.	False
explicit_only	bool	Whether to only add explicit hydrogen or both (implicit and explicit). when add_hs is set to True.	False
ordered	bool	Whether the atom should be ordered. This option is important if you want to ensure that the features returned will always maintain a single atom order for the same molecule, regardless of its original SMILES representation.	False
kekulize	bool	Whether to perform kekulization of the input molecules.	False
sanitize	bool	Whether to apply rdkit sanitization when input is a SMILES.	True

Returns:

Name	Type	Description
mol	Optional[Mol]	the molecule if some conversion have been made. If the conversion fails
	Optional[Mol]	None is returned so make sure that you handle this case on your own.

Source code in datamol/mol.py

def to_mol(
    mol: Union[str, Mol],
    add_hs: bool = False,
    explicit_only: bool = False,
    ordered: bool = False,
    kekulize: bool = False,
    sanitize: bool = True,
) -> Optional[Mol]:
    """Convert an input molecule (smiles representation) into a `Mol`.

    Args:
        mol: A SMILES or a molecule.
        add_hs: Whether hydrogens should be added the molecule.
        explicit_only: Whether to only add explicit hydrogen or both
            (implicit and explicit). when `add_hs` is set to True.
        ordered: Whether the atom should be ordered. This option is
            important if you want to ensure that the features returned will always maintain
            a single atom order for the same molecule, regardless of its original SMILES representation.
        kekulize: Whether to perform kekulization of the input molecules.
        sanitize: Whether to apply rdkit sanitization when input is a SMILES.

    Returns:
        mol: the molecule if some conversion have been made. If the conversion fails
        None is returned so make sure that you handle this case on your own.
    """

    if not isinstance(mol, (str, Mol)):
        raise ValueError(f"Input should be a Mol or a string instead of '{type(mol)}'")

    if isinstance(mol, str):
        _mol = MolFromSmiles(mol, sanitize=sanitize)

        if not sanitize and _mol is not None:
            _mol.UpdatePropertyCache(False)
    else:
        _mol = mol

    # Add hydrogens
    if _mol is not None and add_hs:
        _mol = AddHs(_mol, explicitOnly=explicit_only, addCoords=True)

    # Reorder atoms
    if _mol is not None and ordered:
        _mol = reorder_atoms(_mol)

    if _mol is not None and kekulize:
        Kekulize(_mol, clearAromaticFlags=False)
    return _mol

to_neutral(mol)

Neutralize the charge of a molecule.

Parameters:

Name	Type	Description	Default
mol	Optional[Mol]	a molecule.	required

Returns:

Name	Type	Description
mol	Optional[Mol]	a molecule.

Source code in datamol/mol.py

def to_neutral(mol: Optional[Mol]) -> Optional[Mol]:
    """Neutralize the charge of a molecule.

    Args:
        mol: a molecule.

    Returns:
        mol: a molecule.
    """
    if mol is None:
        return mol

    for a in mol.GetAtoms():
        if a.GetFormalCharge() < 0 or (
            a.GetExplicitValence() >= PERIODIC_TABLE.GetDefaultValence(a.GetSymbol())
            and a.GetFormalCharge() > 0
        ):
            a.SetFormalCharge(0)
            a.UpdatePropertyCache(False)
    return mol

to_scaffold_murcko(mol, make_generic=False)

Extract the Murcko scaffold from a molecule.

Parameters:

Name	Type	Description	Default
mol	Mol	A molecule.	required
make_generic	bool	Whether to make the scaffold generic.	False

Source code in datamol/mol.py

def to_scaffold_murcko(mol: Mol, make_generic: bool = False):
    """Extract the Murcko scaffold from a molecule.

    Args:
        mol: A molecule.
        make_generic: Whether to make the scaffold generic.
    """
    scf = MurckoScaffold.GetScaffoldForMol(mol)

    if make_generic:
        scf = make_scaffold_generic(scf)
        scf = to_mol(scf)

    return scf

unique_id(mol)

A datamol unique molecule ID.

The ID is an MD5 hash of the non-standard InChiKey provided by dm.to_inchikey_non_standard(). It guarantees uniqueness for different tautomeric forms of the same molecule.

Parameters:

Name	Type	Description	Default
mol	Mol	A molecule.	required

Source code in datamol/mol.py

def unique_id(mol: Mol) -> Optional[str]:
    """A datamol unique molecule ID.

    The ID is an MD5 hash of the non-standard InChiKey provided
    by `dm.to_inchikey_non_standard()`. It guarantees uniqueness for
    different tautomeric forms of the same molecule.

    Args:
        mol: A molecule.
    """
    ik = to_inchikey_non_standard(mol)

    if ik is None:
        return None

    return hashlib.md5(ik.encode("utf-8")).hexdigest()

Module io

io

read_csv(urlpath, smiles_column=None, mol_column='mol', **kwargs)

Read a CSV file.

Parameters:

Name	Type	Description	Default
urlpath	Union[str, os.PathLike, TextIO]	Path to a file or a file-like object. Path can be remote or local.	required
smiles_column	Optional[str]	Use this column to build a mol column.	None
mol_column	str	Name to give to the mol column. If not None a mol column will be build. Avoid when loading a very large file.	'mol'
kwargs		Arguments to pass to pd.read_csv().	required

Returns:

Name	Type	Description
df	pd.DataFrame	a pandas.DataFrame

Source code in datamol/io.py

def read_csv(
    urlpath: Union[str, os.PathLike, TextIO],
    smiles_column: Optional[str] = None,
    mol_column: str = "mol",
    **kwargs,
) -> pd.DataFrame:
    """Read a CSV file.

    Args:
        urlpath: Path to a file or a file-like object. Path can be remote or local.
        smiles_column: Use this column to build a mol column.
        mol_column: Name to give to the mol column. If not None a mol column will be build.
            Avoid when loading a very large file.
        kwargs: Arguments to pass to `pd.read_csv()`.

    Returns:
        df: a `pandas.DataFrame`
    """

    df: pd.DataFrame = pd.read_csv(urlpath, **kwargs)  # type: ignore

    if smiles_column is not None:
        PandasTools.AddMoleculeColumnToFrame(df, smiles_column, mol_column)

    return df

read_excel(urlpath, sheet_name=0, smiles_column=None, mol_column='mol', **kwargs)

Read an excel file.

Parameters:

Name	Type	Description	Default
urlpath	Union[str, os.PathLike, TextIO]	Path to a file or a file-like object. Path can be remote or local.	required
sheet_name	Optional[Union[str, int, list]]	see pandas.read_excel() doc.	0
mol_column	str	Name to give to the mol column. If not None a mol column will be build. Avoid when loading a very large file.	'mol'
mol_column	str	name to give to the mol column.	'mol'
kwargs		Arguments to pass to pd.read_excel().	required

Returns:

Name	Type	Description
df	pd.DataFrame	a pandas.DataFrame

Source code in datamol/io.py

def read_excel(
    urlpath: Union[str, os.PathLike, TextIO],
    sheet_name: Optional[Union[str, int, list]] = 0,
    smiles_column: Optional[str] = None,
    mol_column: str = "mol",
    **kwargs,
) -> pd.DataFrame:
    """Read an excel file.

    Args:
        urlpath: Path to a file or a file-like object. Path can be remote or local.
        sheet_name: see `pandas.read_excel()` doc.
        mol_column: Name to give to the mol column. If not None a mol column will be build.
            Avoid when loading a very large file.
        mol_column: name to give to the mol column.
        kwargs: Arguments to pass to `pd.read_excel()`.

    Returns:
        df: a `pandas.DataFrame`
    """

    df = pd.read_excel(urlpath, sheet_name=sheet_name, **kwargs)  # type: ignore

    if smiles_column is not None:
        PandasTools.AddMoleculeColumnToFrame(df, smiles_column, mol_column)

    return df

read_molblock(molblock, sanitize=True, strict_parsing=True, remove_hs=True, fail_if_invalid=False)

Read a Mol block.

Note that potential molecule properties are not read.

Parameters:

Name	Type	Description	Default
mol_block		String containing the Mol block.	required
sanitize	bool	Whether to sanitize the molecules.	True
strict_parsing	bool	If set to false, the parser is more lax about correctness of the contents.	True
remove_hs	bool	Whether to remove the existing hydrogens in the SDF files.	True
fail_if_invalid	bool	If set to true, the parser will raise an exception if the molecule is invalid instead of returning None.	False

Source code in datamol/io.py

def read_molblock(
    molblock: str,
    sanitize: bool = True,
    strict_parsing: bool = True,
    remove_hs: bool = True,
    fail_if_invalid: bool = False,
) -> Optional[dm.Mol]:
    """Read a Mol block.

    Note that potential molecule properties are **not** read.

    Args:
        mol_block: String containing the Mol block.
        sanitize: Whether to sanitize the molecules.
        strict_parsing: If set to false, the parser is more lax about correctness of the contents.
        remove_hs: Whether to remove the existing hydrogens in the SDF files.
        fail_if_invalid: If set to true, the parser will raise an exception if the molecule is invalid
            instead of returning None.
    """

    mol = rdmolfiles.MolFromMolBlock(
        molblock,
        sanitize=sanitize,
        removeHs=remove_hs,
        strictParsing=strict_parsing,
    )

    if mol is None and fail_if_invalid:
        raise ValueError(f"Invalid molecule: {molblock}")

    return mol

read_sdf(urlpath, sanitize=True, as_df=False, smiles_column='smiles', mol_column=None, include_private=False, include_computed=False, strict_parsing=True, remove_hs=True)

Read an SDF file.

Note: This function is meant to be used with dataset that fit in-memory. For a more advanced usage we suggest you to use directly Chem.ForwardSDMolSupplier.

Parameters:

Name	Type	Description	Default
urlpath	Union[str, os.PathLike, TextIO]	Path to a file or a file-like object. Path can be remote or local.	required
sanitize	bool	Whether to sanitize the molecules.	True
as_df	bool	Whether to return a list mol or a pandas DataFrame.	False
smiles_column	Optional[str]	Name of the SMILES column. Only relevant if as_df is True.	'smiles'
mol_column	Optional[str]	Name of the mol column. Only relevant if as_df is True.	None
include_private	bool	Include private properties in the columns. Only relevant if as_df is True.	False
include_computed	bool	Include computed properties in the columns. Only relevant if as_df is True.	False
strict_parsing	bool	If set to false, the parser is more lax about correctness of the contents.	True
remove_hs	bool	Whether to remove the existing hydrogens in the SDF files.	True

Source code in datamol/io.py

def read_sdf(
    urlpath: Union[str, os.PathLike, TextIO],
    sanitize: bool = True,
    as_df: bool = False,
    smiles_column: Optional[str] = "smiles",
    mol_column: Optional[str] = None,
    include_private: bool = False,
    include_computed: bool = False,
    strict_parsing: bool = True,
    remove_hs: bool = True,
) -> Union[List[Mol], pd.DataFrame]:
    """Read an SDF file.

    Note: This function is meant to be used with dataset that fit _in-memory_.
    For a more advanced usage we suggest you to use directly `Chem.ForwardSDMolSupplier`.

    Args:
        urlpath: Path to a file or a file-like object. Path can be remote or local.
        sanitize: Whether to sanitize the molecules.
        as_df: Whether to return a list mol or a pandas DataFrame.
        smiles_column: Name of the SMILES column. Only relevant if `as_df` is True.
        mol_column: Name of the mol column. Only relevant if `as_df` is True.
        include_private: Include private properties in the columns.  Only relevant if
            `as_df` is True.
        include_computed: Include computed properties in the columns.  Only relevant if
            `as_df` is True.
        strict_parsing: If set to false, the parser is more lax about correctness of the contents.
        remove_hs: Whether to remove the existing hydrogens in the SDF files.
    """

    # File-like object
    if isinstance(urlpath, io.IOBase):
        supplier = rdmolfiles.ForwardSDMolSupplier(
            urlpath,
            sanitize=sanitize,
            strictParsing=strict_parsing,
            removeHs=remove_hs,
        )
        mols = list(supplier)

    # Regular local or remote paths
    else:
        with fsspec.open(urlpath) as f:

            # Handle gzip file if needed
            if str(urlpath).endswith(".gz") or str(urlpath).endswith(".gzip"):
                f = gzip.open(f)  # type: ignore

            supplier = rdmolfiles.ForwardSDMolSupplier(
                f,
                sanitize=sanitize,
                strictParsing=strict_parsing,
                removeHs=remove_hs,
            )
            mols = list(supplier)

    # Discard None values
    mols = [mol for mol in mols if mol is not None]

    # Convert to dataframe
    if as_df:
        return dm.to_df(
            mols,
            smiles_column=smiles_column,
            mol_column=mol_column,
            include_private=include_private,
            include_computed=include_computed,
        )  # type: ignore

    return mols

read_smi(urlpath)

Read a list of smiles from am .smi file.

Parameters:

Name	Type	Description	Default
urlpath	Union[str, pathlib.Path, io.IOBase, fsspec.core.OpenFile]	Path to a file or a file-like object. Path can be remote or local. Note: file-like object are not supported yet.	required

Source code in datamol/io.py

def read_smi(
    urlpath: Union[str, pathlib.Path, io.IOBase, fsspec.core.OpenFile],
) -> Sequence[Mol]:
    """Read a list of smiles from am `.smi` file.

    Args:
        urlpath: Path to a file or a file-like object. Path can be remote or local.
            Note: file-like object are not supported yet.
    """

    active_path = urlpath

    # NOTE(hadim): the temporary local file copy
    # is because `SmilesMolSupplier` does not support
    # using file-like object, only path.

    # Copy to a local temporary path if the path is a remote one.
    if not fsspec.utils.can_be_local(str(urlpath)):
        active_path = pathlib.Path(tempfile.mkstemp()[1])
        dm.utils.fs.copy_file(urlpath, active_path)

    # Read the molecules
    supplier = rdmolfiles.SmilesMolSupplier(str(active_path), titleLine=0)
    mols = [mol for mol in supplier if mol is not None]

    # Delete the local temporary path
    if not fsspec.utils.can_be_local(str(urlpath)):
        pathlib.Path(str(active_path)).unlink()

    return mols

to_molblock(mol, include_stereo=True, conf_id=-1, kekulize=True, force_V3000=False)

Convert a molecule to a mol block string.

Note that any molecule properties are lost.

Parameters:

Name	Type	Description	Default
mol	Mol	A molecule.	required
include_stereo	bool	Toggles inclusion of stereochemical information in the output.	True
conf_id	int	Selects which conformation to output.	-1
kekulize	bool	Triggers kekulization of the molecule before it's written, as suggested by the MDL spec.	True
force_V3000	bool	Force generation a V3000 mol block (happens automatically with more than 999 atoms or bonds).	False

Source code in datamol/io.py

def to_molblock(
    mol: Mol,
    include_stereo: bool = True,
    conf_id: int = -1,
    kekulize: bool = True,
    force_V3000: bool = False,
):
    """Convert a molecule to a mol block string.

    Note that any molecule properties are lost.

    Args:
        mol: A molecule.
        include_stereo: Toggles inclusion of stereochemical information in the output.
        conf_id: Selects which conformation to output.
        kekulize: Triggers kekulization of the molecule before it's written,
            as suggested by the MDL spec.
        force_V3000: Force generation a V3000 mol block (happens automatically
            with more than 999 atoms or bonds).
    """

    molblock = rdmolfiles.MolToMolBlock(
        mol,
        includeStereo=include_stereo,
        confId=conf_id,
        kekulize=kekulize,
        forceV3000=force_V3000,
    )

    return molblock

to_sdf(mols, urlpath, smiles_column='smiles', mol_column=None)

Write molecules to a file.

Parameters:

Name	Type	Description	Default
mols	Union[Mol, Sequence[Mol], pd.DataFrame]	a dataframe, a molecule or a list of molecule.	required
urlpath	Union[str, os.PathLike, TextIO]	Path to a file or a file-like object. Path can be remote or local.	required
smiles_column	Optional[str]	Column name to extract the molecule.	'smiles'
mol_column	Optional[str]	Column name to extract the molecule. It takes precedence over smiles_column.	None

Source code in datamol/io.py

def to_sdf(
    mols: Union[Mol, Sequence[Mol], pd.DataFrame],
    urlpath: Union[str, os.PathLike, TextIO],
    smiles_column: Optional[str] = "smiles",
    mol_column: Optional[str] = None,
):
    """Write molecules to a file.

    Args:
        mols: a dataframe, a molecule or a list of molecule.
        urlpath: Path to a file or a file-like object. Path can be remote or local.
        smiles_column: Column name to extract the molecule.
        mol_column: Column name to extract the molecule. It takes
            precedence over `smiles_column`.
    """

    if isinstance(mols, pd.DataFrame):
        mols = dm.from_df(mols, smiles_column=smiles_column, mol_column=mol_column)

    elif isinstance(mols, Mol):
        mols = [mols]

    # Filter out None values
    mols = [mol for mol in mols if mol is not None]

    # File-like object
    if isinstance(urlpath, io.IOBase):
        writer = rdmolfiles.SDWriter(urlpath)
        for mol in mols:
            writer.write(mol)
        writer.close()

    # Regular local or remote paths
    else:
        with fsspec.open(urlpath, mode="w") as f:
            writer = rdmolfiles.SDWriter(f)
            for mol in mols:
                writer.write(mol)
            writer.close()

to_smi(mols, urlpath, error_if_empty=False)

Save a list of molecules in an .smi file.

Parameters:

Name	Type	Description	Default
mols	Sequence[Mol]	a list of molecules.	required
urlpath	Union[str, os.PathLike, TextIO]	Path to a file or a file-like object. Path can be remote or local.	required
error_if_empty	bool	whether to raise and error if the input list is empty.	False

Source code in datamol/io.py

def to_smi(
    mols: Sequence[Mol],
    urlpath: Union[str, os.PathLike, TextIO],
    error_if_empty: bool = False,
):
    """Save a list of molecules in an `.smi` file.

    Args:
        mols: a list of molecules.
        urlpath: Path to a file or a file-like object. Path can be remote or local.
        error_if_empty: whether to raise and error if the input list is empty.
    """

    if len(mols) == 0 and error_if_empty:
        raise ValueError("The list of mols/smiles provided is empty.")

    # Filter out None values
    mols = [mol for mol in mols if mol is not None]

    # File-like object
    if isinstance(urlpath, io.IOBase):
        writer = rdmolfiles.SmilesWriter(urlpath, includeHeader=False, nameHeader="")
        for mol in mols:
            writer.write(mol)
        writer.close()

    # Regular local or remote paths
    else:
        with fsspec.open(urlpath, "w") as f:
            writer = rdmolfiles.SmilesWriter(f, includeHeader=False, nameHeader="")
            for mol in mols:
                writer.write(mol)
            writer.close()

to_xlsx(mols, urlpath, smiles_column='smiles', mol_column='mol', mol_size=[300, 300])

Write molecules to an Excel file with a molecule column as an RDKit rendered image.

Parameters:

Name	Type	Description	Default
mols	Union[Mol, Sequence[Mol], pd.DataFrame]	a dataframe, a molecule or a list of molecule.	required
urlpath	Union[str, os.PathLike]	Path to a file or a file-like object. Path can be remote or local.	required
smiles_column	Optional[str]	Column name to extract the molecule.	'smiles'
mol_column	str	Column name to extract the molecule. It takes precedence over smiles_column. Column name to write the RDKit rendered image. If none, the molecule images are not written.	'mol'

Source code in datamol/io.py

def to_xlsx(
    mols: Union[Mol, Sequence[Mol], pd.DataFrame],
    urlpath: Union[str, os.PathLike],
    smiles_column: Optional[str] = "smiles",
    mol_column: str = "mol",
    mol_size: List[int] = [300, 300],
):
    """Write molecules to an Excel file with a molecule column as an RDKit rendered
    image.

    Args:
        mols: a dataframe, a molecule or a list of molecule.
        urlpath: Path to a file or a file-like object. Path can be remote or local.
        smiles_column: Column name to extract the molecule.
        mol_column: Column name to extract the molecule. It takes
            precedence over `smiles_column`.
            Column name to write the RDKit rendered image. If none,
            the molecule images are not written.
    """

    if isinstance(mols, Mol):
        mols = [mols]

    if isinstance(mols, Sequence):
        mols = [mol for mol in mols if mol is not None]
        mols = dm.to_df(mols, smiles_column=smiles_column, mol_column=mol_column)

    if mols is None or mols.empty:  # type: ignore
        raise ValueError("No molecules to write")

    with fsspec.open(urlpath, mode="wb") as f:
        PandasTools.SaveXlsxFromFrame(mols, f, molCol=mol_column, size=mol_size)

Module convert

convert

from_df(df, smiles_column='smiles', mol_column=None, conserve_smiles=False, sanitize=True)

Convert a dataframe to a list of mols.

For the reverse operation, you might to check dm.to_df().

Note

If smiles_column is used to build the molecules, this property is removed from the molecules' properties. You can decide to conserve the SMILES column by setting conserve_smiles to True.

Parameters:

Name	Type	Description	Default
df	pd.DataFrame	a dataframe.	required
smiles_column	Optional[str]	Column name to extract the molecule.	'smiles'
mol_column	Optional[str]	Column name to extract the molecule. It takes precedence over smiles_column.	None
conserve_smiles	bool	Whether to conserve the SMILES in the mols' props.	False
sanitize	bool	Whether to sanitize if smiles_column is not None.	True

Source code in datamol/convert.py

def from_df(
    df: pd.DataFrame,
    smiles_column: Optional[str] = "smiles",
    mol_column: Optional[str] = None,
    conserve_smiles: bool = False,
    sanitize: bool = True,
) -> List[Mol]:
    """Convert a dataframe to a list of mols.

    For the reverse operation, you might to check `dm.to_df()`.

    Note:
        If `smiles_column` is used to build the molecules, this property
        is removed from the molecules' properties. You can decide to conserve
        the SMILES column by setting `conserve_smiles` to True.

    Args:
        df: a dataframe.
        smiles_column: Column name to extract the molecule.
        mol_column: Column name to extract the molecule. It takes
            precedence over `smiles_column`.
        conserve_smiles: Whether to conserve the SMILES in the mols' props.
        sanitize: Whether to sanitize if `smiles_column` is not None.
    """

    if smiles_column is None and mol_column is None:
        raise ValueError("Either `smiles_column` or `mol_column` must be not None.")

    if len(df) == 0:
        return []

    # Try to detect the mol column if `mol_column` is None.
    if mol_column is None:
        for col in df.columns:
            if isinstance(df[col].iloc[0], Mol):
                mol_column = col

    def _row_to_mol(row):

        props = row.to_dict()

        if mol_column is not None:
            mol = props.pop(mol_column)
        else:

            if conserve_smiles:
                smiles = props[smiles_column]
            else:
                # If a SMILES column is used to create the molecule then it is removed from the
                # properties.
                smiles = props.pop(smiles_column)

            mol = dm.to_mol(smiles, sanitize=sanitize)

        if mol is None:
            return None

        dm.set_mol_props(mol, props)
        return mol

    return df.apply(_row_to_mol, axis=1).tolist()

from_inchi(inchi, sanitize=True, remove_hs=True)

Convert an InChi to a mol.

Parameters:

Name	Type	Description	Default
inchi	Optional[str]	an inchi string.	required
sanitize	bool	do sanitize.	True
remove_hs	bool	do remove hs.	True

Returns:

Type	Description
Optional[Mol]	mol

Source code in datamol/convert.py

def from_inchi(
    inchi: Optional[str],
    sanitize: bool = True,
    remove_hs: bool = True,
) -> Optional[Mol]:
    """Convert an InChi to a mol.

    Args:
        inchi: an inchi string.
        sanitize: do sanitize.
        remove_hs: do remove hs.

    Returns:
        mol
    """
    if inchi is None:
        return None

    return Chem.MolFromInchi(inchi, sanitize=sanitize, removeHs=remove_hs)

from_selfies(selfies, as_mol=False)

Convert a SEFLIES to a smiles or a mol.

Parameters:

Name	Type	Description	Default
selfies	str	a selfies.	required
as_mol	str	whether to return a mol or a smiles.	False

Returns:

Type	Description
Optional[Union[str, Mol]]	smiles or mol.

Source code in datamol/convert.py

def from_selfies(selfies: str, as_mol: bool = False) -> Optional[Union[str, Mol]]:
    """Convert a SEFLIES to a smiles or a mol.

    Args:
        selfies: a selfies.
        as_mol (str, optional): whether to return a mol or a smiles.

    Returns:
        smiles or mol.
    """
    if selfies is None:
        return None

    smiles = sf.decoder(selfies)

    if as_mol and smiles is not None:
        return dm.to_mol(smiles)

    return smiles

from_smarts(smarts)

Convert a SMARTS string to a molecule

Parameters:

Name	Type	Description	Default
smarts	Optional[str]	a smarts string	required

Source code in datamol/convert.py

def from_smarts(smarts: Optional[str]) -> Optional[Mol]:
    """Convert a SMARTS string to a molecule

    Args:
        smarts: a smarts string
    """

    if smarts is None:
        return None
    return Chem.MolFromSmarts(smarts)  # type: ignore

render_mol_df(df)

Render the molecules column in a dataframe. The rendering is performed in-place only. So nothing is returned.

Parameters:

Name	Type	Description	Default
df	pd.DataFrame	a dataframe.	required

Source code in datamol/convert.py

def render_mol_df(df: pd.DataFrame):
    """Render the molecules column in a dataframe. The rendering is performed
    in-place only. So nothing is returned.

    Args:
        df: a dataframe.
    """
    # NOTE(hadim): replace by `PandaTools.ChangeMoleculeRendering` once
    # https://github.com/rdkit/rdkit/issues/3563 is fixed.
    _ChangeMoleculeRendering(df)

smiles_as_smarts(mol, keep_hs=True)

Convert a smiles to a smarts if possible

Parameters:

Name	Type	Description	Default
mol	Union[str, Mol]	a molecule.	required
keep_hs	bool	Whether to keep hydrogen. This will increase the count of H atoms for atoms with attached hydrogens to create a valid smarts without further substitution allowed e.g. [H]-[CH]-[] -> [H]-[CH2]-[]	True

Returns:

Type	Description
Optional[str]	smarts of the molecule

Source code in datamol/convert.py

def smiles_as_smarts(mol: Union[str, Mol], keep_hs: bool = True) -> Optional[str]:
    """Convert a smiles to a smarts if possible

    Args:
        mol: a molecule.
        keep_hs: Whether to keep hydrogen. This will increase the count of H atoms
            for atoms with attached hydrogens to create a valid smarts without further substitution allowed
            e.g. [H]-[CH]-[*] -> [H]-[CH2]-[*]

    Returns:
        smarts of the molecule
    """

    if isinstance(mol, str):
        mol = dm.to_mol(mol)

    if mol is None:
        return None

    # Change the isotope to 99
    for atom in mol.GetAtoms():  # type: ignore
        if keep_hs:
            s = sum(na.GetAtomicNum() == 1 for na in atom.GetNeighbors())
            if s:
                atom.SetNumExplicitHs(atom.GetTotalNumHs() + s)
        atom.SetIsotope(99)

    # Print out the smiles, all the atom attributes will be fully specified
    smarts = to_smiles(mol, isomeric=True, explicit_bonds=True)

    if smarts is None:
        return None

    # Remove the 99 isotope labels
    smarts = re.sub(r"\[99", "[", smarts)
    return smarts

to_df(mols, smiles_column='smiles', mol_column=None, include_private=False, include_computed=False, render_df_mol=True, render_all_df_mol=False)

Convert a list of mols to a dataframe using each mol properties as a column.

For the reverse operation, you might to check dm.from_df().

Parameters:

Name	Type	Description	Default
mols	List[Mol]	a molecule.	required
smiles_column	Optional[str]	name of the SMILES column.	'smiles'
mol_column	Optional[str]	Name of the column. If not None, rdkit.Chem.PandaTools is used to add a molecule column.	None
include_private	bool	Include private properties in the columns.	False
include_computed	bool	Include computed properties in the columns.	False
render_df_mol	bool	whether to render the molecule in the dataframe to images. If called once, it will be applied for the newly created dataframe with mol in it.	True
render_all_df_mol	bool	Whether to render all pandas dataframe mol column as images.	False

Source code in datamol/convert.py

def to_df(
    mols: List[Mol],
    smiles_column: Optional[str] = "smiles",
    mol_column: Optional[str] = None,
    include_private: bool = False,
    include_computed: bool = False,
    render_df_mol: bool = True,
    render_all_df_mol: bool = False,
) -> Optional[pd.DataFrame]:
    """Convert a list of mols to a dataframe using each mol properties
    as a column.

    For the reverse operation, you might to check `dm.from_df()`.

    Args:
        mols: a molecule.
        smiles_column: name of the SMILES column.
        mol_column: Name of the column. If not None, rdkit.Chem.PandaTools
            is used to add a molecule column.
        include_private: Include private properties in the columns.
        include_computed: Include computed properties in the columns.
        render_df_mol: whether to render the molecule in the dataframe to images.
            If called once, it will be applied for the newly created dataframe with
            mol in it.
        render_all_df_mol: Whether to render all pandas dataframe mol column as images.
    """

    # Init a dataframe
    df = pd.DataFrame()

    # Feed it with smiles
    if smiles_column is not None:
        smiles = [to_smiles(mol) for mol in mols]
        df[smiles_column] = smiles

    # Add a mol column
    if mol_column is not None:
        df[mol_column] = mols

    # Add any other properties present in the molecule
    props = [
        mol.GetPropsAsDict(
            includePrivate=include_private,
            includeComputed=include_computed,
        )
        for mol in mols
    ]
    props_df = pd.DataFrame(props)

    if smiles_column is not None and smiles_column in props_df.columns:
        logger.warning(
            f"The SMILES column name provided ('{smiles_column}') is already present in the properties"
            " of the molecules. THe returned dataframe will two columns with the same name."
        )

    # Concat the df with the properties df
    df = pd.concat([df, props_df], axis=1)

    # Render mol column to images
    if render_df_mol is True and mol_column is not None:

        render_mol_df(df)

        if render_all_df_mol:
            PandasTools.RenderImagesInAllDataFrames()

    return df

to_inchi(mol)

Convert a mol to a standard Inchi.

Parameters:

Name	Type	Description	Default
mol	Union[str, Mol]	a molecule.	required

Source code in datamol/convert.py

def to_inchi(mol: Union[str, Mol]) -> Optional[str]:
    """Convert a mol to a standard Inchi.

    Args:
        mol: a molecule.
    """

    if isinstance(mol, str):
        mol = dm.to_mol(mol)

    if mol is None:
        return None

    inchi_val = Chem.MolToInchi(mol)
    if not inchi_val:
        return None
    return inchi_val

to_inchi_non_standard(mol, fixed_hydrogen_layer=True, undefined_stereocenter=True, reconnected_metal_layer=True, tautomerism_keto_enol=True, tautomerism_15=True, options=None)

Convert a mol to a non-standard Inchi.

Note that turning all the flags to False will result in the standard Inchi.

Warning: this function will return a non-standard Inchi. See https://www.inchi-trust.org/technical-faq-2 for details.

It's important to not mix standard and non-standard InChi. If you don't know much about non-standard InChi, we highly recommend you to use the standard InChi with dm.to_inchi().

Parameters:

Name	Type	Description	Default
mol	Union[str, Mol]	a molecule.	required
fixed_hydrogen_layer	bool	whether to include a fixed hydrogen layer (/FixedH).	True
undefined_stereocenter	bool	whether to include an undefined stereocenter layer (/SUU).	True
reconnected_metal_layer	bool	whether to include reconnected metals (/RecMet).	True
tautomerism_keto_enol	bool	whether to account tautomerism keto-enol (/KET).	True
tautomerism_15	bool	whether to account 1,5-tautomerism (/15T).	True
options	Optional[List[str]]	More InchI options in a form of a list of string. Example: ["/SRel", "/AuxNone"].	None

Source code in datamol/convert.py

def to_inchi_non_standard(
    mol: Union[str, Mol],
    fixed_hydrogen_layer: bool = True,
    undefined_stereocenter: bool = True,
    reconnected_metal_layer: bool = True,
    tautomerism_keto_enol: bool = True,
    tautomerism_15: bool = True,
    options: Optional[List[str]] = None,
) -> Optional[str]:
    """Convert a mol to a non-standard Inchi.

    Note that turning all the flags to `False` will result in the standard Inchi.

    **Warning**: this function will return a **non-standard** Inchi. See
    https://www.inchi-trust.org/technical-faq-2 for details.

    It's important to not mix standard and non-standard InChi. If you don't know
    much about non-standard InChi, we highly recommend you to use the
    standard InChi with `dm.to_inchi()`.

    Args:
        mol: a molecule.
        fixed_hydrogen_layer: whether to include a fixed hydrogen layer (`/FixedH`).
        undefined_stereocenter: whether to include an undefined stereocenter layer (`/SUU`).
        reconnected_metal_layer: whether to include reconnected metals (`/RecMet`).
        tautomerism_keto_enol: whether to account tautomerism keto-enol (`/KET`).
        tautomerism_15: whether to account 1,5-tautomerism (`/15T`).
        options: More InchI options in a form of a list of string. Example:
            `["/SRel", "/AuxNone"]`.
    """

    if isinstance(mol, str):
        mol = dm.to_mol(mol)

    if mol is None:
        return None

    inchi_options = _process_inchi_options(
        fixed_hydrogen_layer=fixed_hydrogen_layer,
        undefined_stereocenter=undefined_stereocenter,
        reconnected_metal_layer=reconnected_metal_layer,
        tautomerism_keto_enol=tautomerism_keto_enol,
        tautomerism_15=tautomerism_15,
        options=options,
    )

    inchi_val = Chem.MolToInchi(mol, options=inchi_options)
    if not inchi_val:
        return None
    return inchi_val

to_inchikey(mol)

Convert a mol to a standard InchiKey.

Parameters:

Name	Type	Description	Default
mol	Union[str, Mol]	a molecule	required

Source code in datamol/convert.py

def to_inchikey(mol: Union[str, Mol]) -> Optional[str]:
    """Convert a mol to a standard InchiKey.

    Args:
        mol: a molecule
    """
    if isinstance(mol, str):
        mol = dm.to_mol(mol)

    if mol is None:
        return None

    inchikey = Chem.MolToInchiKey(mol)
    if not inchikey:
        return None
    return inchikey

to_inchikey_non_standard(mol, fixed_hydrogen_layer=True, undefined_stereocenter=True, reconnected_metal_layer=True, tautomerism_keto_enol=True, tautomerism_15=True, options=None)

Convert a mol to a non-standard InchiKey.

Note that turning all the flags to False will result in the standard InchiKey.

Warning: this function will return a non-standard InchiKey. See https://www.inchi-trust.org/technical-faq-2 for details.

It's important to not mix standard and non-standard InChiKey. If you don't know much about non-standard InchiKey, we highly recommend you to use the standard InchiKey with dm.to_inchikey().

Parameters:

Name	Type	Description	Default
mol	Union[str, Mol]	a molecule	required
fixed_hydrogen_layer	bool	whether to include a fixed hydrogen layer (/FixedH).	True
undefined_stereocenter	bool	whether to include an undefined stereocenter layer (/SUU).	True
reconnected_metal_layer	bool	whether to include reconnected metals (/RecMet).	True
tautomerism_keto_enol	bool	whether to account tautomerism keto-enol (/KET).	True
tautomerism_15	bool	whether to account 1,5-tautomerism (/15T).	True
options	Optional[List[str]]	More InchI options in a form of a list of string. Example: ["/SRel", "/AuxNone"].	None

Source code in datamol/convert.py

def to_inchikey_non_standard(
    mol: Union[str, Mol],
    fixed_hydrogen_layer: bool = True,
    undefined_stereocenter: bool = True,
    reconnected_metal_layer: bool = True,
    tautomerism_keto_enol: bool = True,
    tautomerism_15: bool = True,
    options: Optional[List[str]] = None,
) -> Optional[str]:
    """Convert a mol to a non-standard InchiKey.

    Note that turning all the flags to `False` will result in the standard InchiKey.

    **Warning**: this function will return a **non-standard** InchiKey. See
    https://www.inchi-trust.org/technical-faq-2 for details.

    It's important to not mix standard and non-standard InChiKey. If you don't know
    much about non-standard InchiKey, we highly recommend you to use the
    standard InchiKey with `dm.to_inchikey()`.

    Args:
        mol: a molecule
        fixed_hydrogen_layer: whether to include a fixed hydrogen layer (`/FixedH`).
        undefined_stereocenter: whether to include an undefined stereocenter layer (`/SUU`).
        reconnected_metal_layer: whether to include reconnected metals (`/RecMet`).
        tautomerism_keto_enol: whether to account tautomerism keto-enol (`/KET`).
        tautomerism_15: whether to account 1,5-tautomerism (`/15T`).
        options: More InchI options in a form of a list of string. Example:
            `["/SRel", "/AuxNone"]`.
    """

    if isinstance(mol, str):
        mol = dm.to_mol(mol)

    if mol is None:
        return None

    inchi_options = _process_inchi_options(
        fixed_hydrogen_layer=fixed_hydrogen_layer,
        undefined_stereocenter=undefined_stereocenter,
        reconnected_metal_layer=reconnected_metal_layer,
        tautomerism_keto_enol=tautomerism_keto_enol,
        tautomerism_15=tautomerism_15,
        options=options,
    )

    inchikey = Chem.MolToInchiKey(mol, options=inchi_options)
    if not inchikey:
        return None
    return inchikey

to_selfies(mol)

Convert a mol to SELFIES.

Parameters:

Name	Type	Description	Default
mol	Union[str, Mol]	a molecule or a SMILES.	required

Returns:

Name	Type	Description
selfies	Optional[str]	SELFIES string.

Source code in datamol/convert.py

def to_selfies(mol: Union[str, Mol]) -> Optional[str]:
    """Convert a mol to SELFIES.

    Args:
        mol: a molecule or a SMILES.

    Returns:
        selfies: SELFIES string.
    """

    if isinstance(mol, Mol):
        mol = to_smiles(mol)

    if mol is None:
        return None
    selfies = sf.encoder(mol)

    if selfies == -1:
        return None

    return selfies

to_smarts(mol)

Convert a mol to SMARTS format

Parameters:

Name	Type	Description	Default
mol	Mol	a molecule.	required

Source code in datamol/convert.py

def to_smarts(mol: Mol) -> Optional[str]:
    """Convert a mol to SMARTS format

    Args:
        mol: a molecule.
    """

    if mol is None:
        return None

    return Chem.MolToSmarts(mol)  # type: ignore

to_smiles(mol, canonical=True, isomeric=True, kekulize=False, ordered=False, explicit_bonds=False, explicit_hs=False, randomize=False, cxsmiles=False, allow_to_fail=False)

Convert a mol to a SMILES.

Parameters:

Name	Type	Description	Default
mol	Mol	a molecule.	required
canonical	bool	if false no attempt will be made to canonicalize the molecule.	True
isomeric	bool	whether to include information about stereochemistry in the SMILES.	True
kekulize	bool	whether to return the kekule version of the SMILES.	False
ordered	bool	whether to force reordering of the atoms first.	False
explicit_bonds	bool	if true, all bond orders will be explicitly indicated in the output SMILES.	False
explicit_hs	bool	if true, all H counts will be explicitly indicated in the output SMILES.	False
randomize	bool	whether to randomize the generated smiles. Override canonical.	False
cxsmiles	bool	Whether to return a CXSMILES instead of a SMILES.	False
allow_to_fail	bool	Raise an error if the conversion to SMILES fails. Return None otherwise.	False

Source code in datamol/convert.py

def to_smiles(
    mol: Mol,
    canonical: bool = True,
    isomeric: bool = True,
    kekulize: bool = False,
    ordered: bool = False,
    explicit_bonds: bool = False,
    explicit_hs: bool = False,
    randomize: bool = False,
    cxsmiles: bool = False,
    allow_to_fail: bool = False,
) -> Optional[str]:
    """Convert a mol to a SMILES.

    Args:
        mol: a molecule.
        canonical: if false no attempt will be made to canonicalize the molecule.
        isomeric: whether to include information about stereochemistry in the SMILES.
        kekulize: whether to return the kekule version of the SMILES.
        ordered: whether to force reordering of the atoms first.
        explicit_bonds: if true, all bond orders will be explicitly indicated in the output SMILES.
        explicit_hs: if true, all H counts will be explicitly indicated in the output SMILES.
        randomize: whether to randomize the generated smiles. Override `canonical`.
        cxsmiles: Whether to return a CXSMILES instead of a SMILES.
        allow_to_fail: Raise an error if the conversion to SMILES fails. Return None otherwise.
    """

    if ordered and canonical is False:
        mol = dm.reorder_atoms(mol)

    if randomize:
        mol = dm.randomize_atoms(mol)
        canonical = False

    smiles = None
    try:

        if cxsmiles:
            smiles = rdmolfiles.MolToCXSmiles(
                mol,
                isomericSmiles=isomeric,
                canonical=canonical,
                allBondsExplicit=explicit_bonds,
                allHsExplicit=explicit_hs,
                kekuleSmiles=kekulize,
            )

        else:
            smiles = rdmolfiles.MolToSmiles(
                mol,
                isomericSmiles=isomeric,
                canonical=canonical,
                allBondsExplicit=explicit_bonds,
                allHsExplicit=explicit_hs,
                kekuleSmiles=kekulize,
            )

    except Exception as e:

        if allow_to_fail:
            raise e

        return None

    return smiles

Module cluster

cluster

assign_to_centroids(mols, centroids, feature_fn=None, dist_fn=None, n_jobs=1)

Assign molecules to centroids. Each molecule will be assigned to the closest centroid.

Parameters:

Name	Type	Description	Default
mols	List[Mol]	a list of molecules to assign to centroids	required
centroids	List[Mol]	list of molecules to use as centroid	required
feature_fn	Optional[Callable]	A feature function that takes a Mol object and return molecular features. By default, the dm.to_fp() is used. Default to None.	None
dist_fn	Optional[Callable]	A function that takes two indexes (i,j) and return the distance between them. You might use partial to set the fingerprints as input. By default, the Tanimoto similarity will be used. Default to None.	None
n_jobs	Optional[int]	Number of jobs for parallelization. Let to 1 for no parallelization. Set to None to use all available cores.	1

Returns:

Name	Type	Description
clusters_map		dict of index mapping each centroid index to the molecule index in the cluster
clusters_list		list of all molecules in each cluster. The cluster index follows the index of the centroid. Note that the centroid molecule is not added to the cluster.

Source code in datamol/cluster.py

def assign_to_centroids(
    mols: List[Mol],
    centroids: List[Mol],
    feature_fn: Optional[Callable] = None,
    dist_fn: Optional[Callable] = None,
    n_jobs: Optional[int] = 1,
):
    r"""Assign molecules to centroids. Each molecule will be assigned to the closest centroid.

    Args:
        mols: a list of molecules to assign to centroids
        centroids: list of molecules to use as centroid
        feature_fn: A feature function that takes a Mol object
            and return molecular features. By default, the `dm.to_fp()` is used.
            Default to None.
        dist_fn: A function that takes two indexes (i,j) and return the
            distance between them. You might use partial to set the fingerprints as input.
            By default, the Tanimoto similarity will be used. Default to None.
        n_jobs: Number of jobs for parallelization. Let to 1 for no
            parallelization. Set to None to use all available cores.

    Returns:
        clusters_map: dict of index mapping each centroid index to the molecule index in the cluster
        clusters_list: list of all molecules in each cluster. The cluster index follows the index of the centroid.
            Note that the centroid molecule is not added to the cluster.
    """

    if feature_fn is None:
        feature_fn = functools.partial(dm.to_fp, as_array=False)

    all_mols = [x for x in mols] + [c for c in centroids]
    features = dm.parallelized(feature_fn, all_mols, n_jobs=n_jobs)

    def distij(i, j, features=features):
        return 1.0 - DataStructs.cDataStructs.TanimotoSimilarity(features[int(i)], features[int(j)])

    if dist_fn is None:
        dist_fn = distij

    clusters_map = ddict(list)
    clusters_list = [[] for _ in centroids]
    query_inds = np.expand_dims(np.arange(len(mols), dtype=int), axis=1)
    centroid_inds = np.expand_dims(np.arange(len(centroids), dtype=int), axis=1) + len(mols)
    dist_mat = distance.cdist(query_inds, centroid_inds, metric=distij)
    closest = np.argmin(dist_mat, axis=1)
    for ind, cluster_ind in enumerate(closest):  # type: ignore
        clusters_map[cluster_ind].append(ind)
        clusters_list[cluster_ind].append(mols[ind])
    return clusters_map, clusters_list

cluster_mols(mols, cutoff=0.2, feature_fn=None, n_jobs=1)

Cluster a set of molecules using the butina clustering algorithm and a given threshold.

Parameters:

Name	Type	Description	Default
mols	Union[Sequence[Mol], pd.Series]	a list of molecules.	required
cutoff	float	Cuttoff for the clustering. Default to 0.2.	0.2
feature_fn	Optional[Callable]	A feature function that takes a Mol object and return molecular features. By default, the dm.to_fp() is used. Default to None.	None
n_jobs	Optional[int]	Number of jobs for parallelization. Let to 1 for no parallelization. Set to None to use all available cores.	1

Source code in datamol/cluster.py

def cluster_mols(
    mols: Union[Sequence[Mol], pd.Series],
    cutoff: float = 0.2,
    feature_fn: Optional[Callable] = None,
    n_jobs: Optional[int] = 1,
):
    """Cluster a set of molecules using the butina clustering algorithm and a given threshold.

    Args:
        mols: a list of molecules.
        cutoff: Cuttoff for the clustering. Default to 0.2.
        feature_fn: A feature function that takes a Mol object
            and return molecular features. By default, the `dm.to_fp()` is used.
            Default to None.
        n_jobs: Number of jobs for parallelization. Let to 1 for no
            parallelization. Set to None to use all available cores.
    """

    if feature_fn is None:
        feature_fn = functools.partial(dm.to_fp, as_array=False)

    features = dm.parallelized(feature_fn, mols, n_jobs=n_jobs)

    dists = []
    n_mols = len(mols)

    for i in range(1, n_mols):
        dist = DataStructs.cDataStructs.BulkTanimotoSimilarity(
            features[i], features[:i], returnDistance=True
        )
        dists.extend([x for x in dist])

    # now cluster the data
    cluster_indices = Butina.ClusterData(dists, n_mols, cutoff, isDistData=True)
    cluster_mols = [operator.itemgetter(*cluster)(mols) for cluster in cluster_indices]

    # Make single mol cluster a list
    cluster_mols = [[c] if isinstance(c, Mol) else c for c in cluster_mols]

    return cluster_indices, cluster_mols

pick_centroids(mols, npick=0, initial_picks=None, threshold=0.5, feature_fn=None, dist_fn=None, seed=42, method='sphere', n_jobs=1)

Pick a set of npick centroids from a list of molecules.

Parameters:

Name	Type	Description	Default
mols	List[Mol]	a list of molecules.	required
npick	int	Number of element to pick from mols, including the preselection.	0
threshold	float	Minimum distance between centroids for maxmin and sphere exclusion (sphere) methods.	0.5
initial_picks	Optional[List[int]]	Starting list of index for molecules that should be in the set of picked molecules. Default to None.	None
feature_fn	callable	A feature function that takes a Mol object and return molecular features. By default, the dm.to_fp() is used. Default to None.	None
dist_fn	Optional[Callable]	A function that takes two indexes (i,j) and return the distance between them. You might use partial to set the fingerprints as input. By default, the Tanimoto similarity will be used. Default to None.	None
seed	int	seed for reproducibility	42
method	str	Picking method to use. One of sphere, maxmin or any supported rdkit hierarchical clustering method such as centroid, clink, upgma	'sphere'
n_jobs	Optional[int]	Number of jobs for parallelization. Let to 1 for no parallelization. Set to None to use all available cores.	1

Returns:

Name	Type	Description
picked_inds		index of the molecule that have been selected as centroids
mols		molecules that have been picked

Source code in datamol/cluster.py

def pick_centroids(
    mols: List[Mol],
    npick: int = 0,
    initial_picks: Optional[List[int]] = None,
    threshold: float = 0.5,
    feature_fn: Optional[Callable] = None,
    dist_fn: Optional[Callable] = None,
    seed: int = 42,
    method: str = "sphere",
    n_jobs: Optional[int] = 1,
):
    r"""Pick a set of `npick` centroids from a list of molecules.

    Args:
        mols: a list of molecules.
        npick: Number of element to pick from mols, including the preselection.
        threshold: Minimum distance between centroids for `maxmin` and sphere exclusion (`sphere`) methods.
        initial_picks: Starting list of index for molecules that should be in the
            set of picked molecules. Default to None.
        feature_fn (callable, optional): A feature function that takes a Mol object
            and return molecular features. By default, the `dm.to_fp()` is used.
            Default to None.
        dist_fn: A function that takes two indexes (i,j) and return the
            distance between them. You might use partial to set the fingerprints as input.
            By default, the Tanimoto similarity will be used. Default to None.
        seed: seed for reproducibility
        method: Picking method to use. One of  `sphere`, `maxmin` or any
            supported rdkit hierarchical clustering method such as `centroid`, `clink`, `upgma`
        n_jobs: Number of jobs for parallelization. Let to 1 for no
            parallelization. Set to None to use all available cores.

    Returns:
        picked_inds: index of the molecule that have been selected as centroids
        mols: molecules that have been picked
    """

    n_mols = len(mols)
    if feature_fn is None:
        feature_fn = functools.partial(dm.to_fp, as_array=False)

    features = dm.parallelized(feature_fn, mols, n_jobs=n_jobs)

    def distij(i, j, features=features):
        return 1.0 - DataStructs.cDataStructs.TanimotoSimilarity(features[i], features[j])

    if dist_fn is None:
        dist_fn = distij

    initial_picks = [] if initial_picks is None else initial_picks

    if method == "maxmin":
        picker = MaxMinPicker()
        picked_inds, _ = picker.LazyPickWithThreshold(
            dist_fn,
            n_mols,
            pickSize=npick,
            threshold=threshold,
            firstPicks=initial_picks,
            seed=seed,
        )

    elif method == "sphere":
        picker = LeaderPicker()
        picked_inds = picker.LazyPick(
            dist_fn, n_mols, threshold=threshold, pickSize=npick, firstPicks=initial_picks
        )

    elif method.upper() in ClusterMethod.names.keys() and npick:
        if initial_picks:
            logger.warning(
                "Initial picks is not supported by hierarchical clustering. You pick has been discarded."
            )

        dist_mat = dm.parallelized(
            distij, list(zip(*np.tril_indices(len(mols), k=-1))), arg_type="args"
        )
        dist_mat = np.asarray(dist_mat)
        picker = HierarchicalClusterPicker(ClusterMethod.names[method.upper()])
        picked_inds = picker.Pick(dist_mat, n_mols, npick)
    else:
        raise ValueError(f"Picking method {method} with {npick} elements to pick is not supported.")
    picked_inds = np.array(picked_inds)
    picked_mols = [mols[x] for x in picked_inds]

    return picked_inds, picked_mols

pick_diverse(mols, npick, initial_picks=None, feature_fn=None, dist_fn=None, seed=42, n_jobs=1)

Pick a set of diverse molecules based on they fingerprint.

Parameters:

Name	Type	Description	Default
mols	List[Mol]	a list of molecules.	required
npick	int	Number of element to pick from mols, including the preselection.	required
initial_picks	Optional[List[int]]	Starting list of index for molecules that should be in the set of picked molecules. Default to None.	None
feature_fn	Optional[Callable]	A feature function that takes a Mol object and return molecular features. By default, the dm.to_fp() is used. Default to None.	None
dist_fn	Optional[Callable]	A function that takes two indexes (i,j) and return the distance between them. You might use partial to set the fingerprints as input. By default, the Tanimoto similarity will be used. Default to None.	None
seed	int	seed for reproducibility	42
n_jobs	Optional[int]	Number of jobs for parallelization. Let to 1 for no parallelization. Set to None to use all available cores.	1

Returns:

Name	Type	Description
picked_inds		index of the molecule that have been picked
mols		molecules that have been picked

Source code in datamol/cluster.py

def pick_diverse(
    mols: List[Mol],
    npick: int,
    initial_picks: Optional[List[int]] = None,
    feature_fn: Optional[Callable] = None,
    dist_fn: Optional[Callable] = None,
    seed: int = 42,
    n_jobs: Optional[int] = 1,
):
    r"""Pick a set of diverse molecules based on they fingerprint.

    Args:
        mols: a list of molecules.
        npick: Number of element to pick from mols, including the preselection.
        initial_picks: Starting list of index for molecules that should be in the
            set of picked molecules. Default to None.
        feature_fn: A feature function that takes a Mol object
            and return molecular features. By default, the `dm.to_fp()` is used.
            Default to None.
        dist_fn: A function that takes two indexes (i,j) and return the
            distance between them. You might use partial to set the fingerprints as input.
            By default, the Tanimoto similarity will be used. Default to None.
        seed: seed for reproducibility
        n_jobs: Number of jobs for parallelization. Let to 1 for no
            parallelization. Set to None to use all available cores.

    Returns:
        picked_inds: index of the molecule that have been picked
        mols: molecules that have been picked
    """

    if feature_fn is None:
        feature_fn = functools.partial(dm.to_fp, as_array=False)

    features = dm.parallelized(feature_fn, mols, n_jobs=n_jobs)

    def distij(i, j, features=features):
        return 1.0 - DataStructs.cDataStructs.TanimotoSimilarity(features[i], features[j])

    if dist_fn is None:
        dist_fn = distij

    picker = MaxMinPicker()
    initial_picks = [] if initial_picks is None else initial_picks
    picked_inds = picker.LazyPick(dist_fn, len(mols), npick, firstPicks=initial_picks, seed=seed)
    picked_inds = np.array(picked_inds)
    picked_mols = [mols[x] for x in picked_inds]

    return picked_inds, picked_mols

Module fp

fp

fold_count_fp(fp, dim=1024, binary=False)

Fast folding of a count fingerprint to the specified dimension.

Parameters:

Name	Type	Description	Default
fp	Union[np.ndarray, SparseBitVect, ExplicitBitVect]	A fingerprint.	required
dim	int	The dimension of the folded array.	1024
binary	bool	Whether to fold into a binary array or take use a count vector.	False

Returns:

Name	Type	Description
folded		returns folded array to the provided dimension.

Source code in datamol/fp.py

def fold_count_fp(
    fp: Union[np.ndarray, SparseBitVect, ExplicitBitVect],
    dim: int = 1024,
    binary: bool = False,
):
    """Fast folding of a count fingerprint to the specified dimension.

    Args:
        fp: A fingerprint.
        dim: The dimension of the folded array.
        binary: Whether to fold into a binary array or take use a count vector.

    Returns:
        folded: returns folded array to the provided dimension.
    """
    if isinstance(
        fp,
        (
            UIntSparseIntVect,
            IntSparseIntVect,
            LongSparseIntVect,
            ULongSparseIntVect,
        ),
    ):
        tmp = fp.GetNonzeroElements()

    elif isinstance(fp, SparseBitVect):
        on_bits = fp.GetOnBits()
        tmp = dict(zip(on_bits, np.ones(len(on_bits))))

    else:
        raise ValueError(f"The fingerprint is of wrong type: {type(fp)}")

    # ON bits dict to (i, v)
    i = np.array(list(tmp.keys())) % dim
    v = np.array(list(tmp.values()))

    # Fold indices
    i = i % dim

    # Create the folded fp
    folded = np.zeros(dim, dtype="int")
    np.add.at(folded, i, v)

    if binary:
        folded = np.clip(folded, a_min=0, a_max=1)

    return folded

fp_to_array(fp)

Convert rdkit fingerprint to numpy array.

Note

This implementation has shown to be faster than using DataStructs.ConvertToNumpyArray by a factor of ~4. See https://github.com/rdkit/rdkit/discussions/3863.

Parameters:

Name	Type	Description	Default
fp	Union[np.ndarray, SparseBitVect, ExplicitBitVect, UIntSparseIntVect]	The fingerprint.	required

Source code in datamol/fp.py

def fp_to_array(
    fp: Union[np.ndarray, SparseBitVect, ExplicitBitVect, UIntSparseIntVect]
) -> np.ndarray:
    """Convert rdkit fingerprint to numpy array.

    Note:
        This implementation has shown to be faster than using `DataStructs.ConvertToNumpyArray`
        by a factor of ~4. See https://github.com/rdkit/rdkit/discussions/3863.

    Args:
        fp: The fingerprint.
    """

    if isinstance(fp, np.ndarray):
        fp_out = fp

    elif isinstance(fp, SparseBitVect):
        tmp = np.zeros(fp.GetNumBits(), dtype=int)
        on_bits = np.array(fp.GetOnBits())
        tmp[on_bits] = 1
        fp_out = tmp

    elif isinstance(fp, ExplicitBitVect):
        fp_out = np.frombuffer(fp.ToBitString().encode(), "u1") - ord("0")

    elif isinstance(
        fp,
        (
            UIntSparseIntVect,
            IntSparseIntVect,
            LongSparseIntVect,
            ULongSparseIntVect,
        ),
    ):
        tmp = np.zeros(fp.GetLength(), dtype=int)
        bit_idx, values = np.array(list(fp.GetNonzeroElements().items())).T
        tmp[bit_idx] = values
        fp_out = tmp

    else:
        raise ValueError(
            f"The fingerprint of type '{type(fp)}' is not supported. "
            "Please open a ticket at https://github.com/datamol-org/datamol/issues."
        )

    return fp_out

list_supported_fingerprints()

Return the supported fingerprints in datamol.

Source code in datamol/fp.py

def list_supported_fingerprints():
    """Return the supported fingerprints in datamol."""

    return _FP_FUNCS

to_fp(mol, as_array=True, fp_type='ecfp', fold_size=None, **fp_args)

Compute the molecular fingerprint given a molecule or a SMILES.

Parameters:

Name	Type	Description	Default
mol	Union[str, Chem.rdchem.Mol]	a molecule or a SMILES.	required
as_array	bool	Whether to return a numpy array of an RDKit vec. Default to True.	True
fp_type	str	The type of the fingerprint. See dm.list_supported_fingerprints() for a complete list.	'ecfp'
fold_size	Optional[int]	If set, fold the fingerprint to the fold_size. If set, returned array is always a numpy array.	None
fp_args		Arguments to build the fingerprint. Refer to the official RDKit documentation.	required

Returns:

Type	Description
Optional[Union[np.ndarray, SparseBitVect, ExplicitBitVect]]	A fingerprint vector or None

Source code in datamol/fp.py

def to_fp(
    mol: Union[str, Chem.rdchem.Mol],
    as_array: bool = True,
    fp_type: str = "ecfp",
    fold_size: Optional[int] = None,
    **fp_args,
) -> Optional[Union[np.ndarray, SparseBitVect, ExplicitBitVect]]:
    """Compute the molecular fingerprint given a molecule or a SMILES.

    Args:
        mol: a molecule or a SMILES.
        as_array: Whether to return a numpy array of an RDKit vec. Default to True.
        fp_type: The type of the fingerprint. See `dm.list_supported_fingerprints()` for a
            complete list.
        fold_size: If set, fold the fingerprint to the `fold_size`. If set, returned array is
            always a numpy array.
        fp_args: Arguments to build the fingerprint. Refer to the official RDKit documentation.

    Returns:
        A fingerprint vector or None
    """

    # Get fp function
    fp_func = _FP_FUNCS.get(fp_type)

    if fp_func is None:
        raise ValueError(
            f"The fingerprint '{fp_type}' is not available. Use `dm.list_supported_fingerprints()` to "
            "get a complete list of the available fingerprints."
        )

    # Convert input to mol if needed
    if isinstance(mol, str):
        mol_obj = dm.to_mol(mol)
    else:
        mol_obj = mol

    if mol_obj is None:
        raise ValueError(f"It seems like the input molecule '{mol}' is invalid.")

    mol = mol_obj

    # Insert default values.
    for key, value in _FP_DEFAULT_ARGS[fp_type].items():
        fp_args.setdefault(key, value)

    # Compute the fingerprint
    fp = fp_func(mol, **fp_args)

    # Fold the fp if needed.
    if fold_size is not None:
        fp = fold_count_fp(fp, dim=fold_size)

    # Convert to a numpy array
    if not fold_size and as_array:
        fp = fp_to_array(fp)

    return fp

Module similarity

similarity

cdist(mols1, mols2, n_jobs=1, distances_chunk=False, distances_chunk_memory=1024, distances_n_jobs=-1, **fp_args)

Compute the tanimoto distance between the fingerprints of each pair of molecules of the two collections of inputs.

Parameters:

Name	Type	Description	Default
mols1	List[Union[str, dm.Mol]]	list of molecules.	required
mols2	List[Union[str, dm.Mol]]	list of molecules.	required
n_jobs	Optional[int]	Number of jobs for fingerprint computation. Let to 1 for no parallelization. Set to None or -1 to use all available cores.	1
distances_chunk	bool	Whether to use chunked computation.	False
distances_chunk_memory	int	Memory size in MB to use for chunked computation.	1024
distances_n_jobs	int	Number of jobs for parallelization.	-1
**fp_args		list of args to pass to to_fp().	{}

Returns:

Type	Description
np.ndarray	distmat

Source code in datamol/similarity.py

def cdist(
    mols1: List[Union[str, dm.Mol]],
    mols2: List[Union[str, dm.Mol]],
    n_jobs: Optional[int] = 1,
    distances_chunk: bool = False,
    distances_chunk_memory: int = 1024,
    distances_n_jobs: int = -1,
    **fp_args,
) -> np.ndarray:
    """Compute the tanimoto distance between the fingerprints of each pair of
    molecules of the two collections of inputs.

    Args:
        mols1: list of molecules.
        mols2: list of molecules.
        n_jobs: Number of jobs for fingerprint computation. Let to 1 for no
            parallelization. Set to None or -1 to use all available cores.
        distances_chunk: Whether to use chunked computation.
        distances_chunk_memory: Memory size in MB to use for chunked computation.
        distances_n_jobs: Number of jobs for parallelization.
        **fp_args: list of args to pass to `to_fp()`.

    Returns:
        distmat
    """

    fps1 = dm.parallelized(
        functools.partial(dm.to_fp, as_array=True, **fp_args),
        mols1,
        n_jobs=n_jobs,
    )

    fps2 = dm.parallelized(
        functools.partial(dm.to_fp, as_array=True, **fp_args),
        mols2,
        n_jobs=n_jobs,
    )

    fps1 = np.array(fps1).astype(bool)
    fps2 = np.array(fps2).astype(bool)

    if distances_chunk:
        distances = pairwise_distances_chunked(
            fps1,
            fps2,
            metric="jaccard",
            n_jobs=distances_n_jobs,
            working_memory=distances_chunk_memory,
        )
        distances = [i for i in distances]
        distances = np.vstack(distances)
    else:
        distances = distance.cdist(fps1, fps2, metric="jaccard")

    return distances

pdist(mols, n_jobs=1, squareform=True, **fp_args)

Compute the pairwise tanimoto distance between the fingerprints of all the molecules in the input set.

Parameters:

Name	Type	Description	Default
mols	List[Union[str, dm.Mol]]	list of molecules	required
n_jobs	Optional[int]	Number of jobs for parallelization. Let to 1 for no parallelization. Set to None to use all available cores.	1
squareform	bool	Whether to return in square form (matrix) or in a condensed form (1D vector).	True
**fp_args		list of args to pass to to_fp().	{}

Returns:

Type	Description
np.ndarray	dist_mat

Source code in datamol/similarity.py

def pdist(
    mols: List[Union[str, dm.Mol]],
    n_jobs: Optional[int] = 1,
    squareform: bool = True,
    **fp_args,
) -> np.ndarray:
    """Compute the pairwise tanimoto distance between the fingerprints of all the
    molecules in the input set.

    Args:
        mols: list of molecules
        n_jobs: Number of jobs for parallelization. Let to 1 for no
            parallelization. Set to None to use all available cores.
        squareform: Whether to return in square form (matrix) or in a condensed
            form (1D vector).
        **fp_args: list of args to pass to `to_fp()`.

    Returns:
        dist_mat
    """

    fps = dm.parallelized(
        functools.partial(dm.to_fp, as_array=True, **fp_args),
        mols,
        n_jobs=n_jobs,
    )

    fps = np.array(fps)

    dist_mat = distance.pdist(fps, metric="jaccard")

    if squareform:
        dist_mat = distance.squareform(dist_mat, force="tomatrix")

    return dist_mat

Module isomers

isomers

Module data

data

cdk2(as_df=True, mol_column='mol')

Return the RDKit CDK2 dataset from RDConfig.RDDocsDir, 'Book/data/cdk2.sdf'.

Parameters:

Name	Type	Description	Default
as_df	bool	Whether to return a list mol or a pandas DataFrame.	True
mol_column	Optional[str]	Name of the mol column. Only relevant if as_df is True.	'mol'

Source code in datamol/data.py

def cdk2(as_df: bool = True, mol_column: Optional[str] = "mol"):
    """Return the RDKit CDK2 dataset from `RDConfig.RDDocsDir, 'Book/data/cdk2.sdf'`.

    Args:
        as_df: Whether to return a list mol or a pandas DataFrame.
        mol_column: Name of the mol column. Only relevant if `as_df` is True.
    """

    return read_sdf(
        os.path.join(RDConfig.RDDocsDir, "Book/data/cdk2.sdf"),
        as_df=as_df,
        mol_column=mol_column,
    )

freesolv()

Return the FreeSolv dataset as a dataframe.

The dataset contains 642 molecules and the following columns: ['iupac', 'smiles', 'expt', 'calc'].

Warning

This dataset is only meant to be used as a toy dataset for pedagogic and testing purposes. It is not a dataset for benchmarking, analysis or model training.

Source code in datamol/data.py

def freesolv():
    """Return the FreeSolv dataset as a dataframe.

    The dataset contains 642 molecules and the following columns:
    `['iupac', 'smiles', 'expt', 'calc']`.

    Warning:
        This dataset is only meant to be used as a toy dataset for pedagogic and
        testing purposes. **It is not** a dataset for benchmarking, analysis or
        model training.
    """

    with pkg_resources.resource_stream("datamol", "data/freesolv.csv") as f:
        data = pd.read_csv(f)  # type: ignore
    return data

solubility(as_df=True, mol_column='mol')

Return the RDKit solubility dataset from RDConfig.RDDocsDir, 'Book/data/solubility.{train|test}.sdf'.

The dataframe or the list of molecules with contain a split column, either train or test.

Parameters:

Name	Type	Description	Default
as_df	bool	Whether to return a list mol or a pandas DataFrame.	True
mol_column	Optional[str]	Name of the mol column. Only relevant if as_df is True.	'mol'

Source code in datamol/data.py

def solubility(as_df: bool = True, mol_column: Optional[str] = "mol"):
    """Return the RDKit solubility dataset from `RDConfig.RDDocsDir, 'Book/data/solubility.{train|test}.sdf'`.

    The dataframe or the list of molecules with contain a `split` column, either `train` or `test`.

    Args:
        as_df: Whether to return a list mol or a pandas DataFrame.
        mol_column: Name of the mol column. Only relevant if `as_df` is True.
    """

    train: pd.DataFrame = read_sdf(
        os.path.join(RDConfig.RDDocsDir, "Book/data/solubility.train.sdf"),
        as_df=True,
        mol_column="mol",
        smiles_column=None,
    )  # type: ignore
    train["split"] = "train"

    test: pd.DataFrame = read_sdf(
        os.path.join(RDConfig.RDDocsDir, "Book/data/solubility.test.sdf"),
        as_df=True,
        mol_column="mol",
        smiles_column=None,
    )  # type: ignore
    test["split"] = "test"

    # NOTE(hadim): LMAO RDkit consistency xD
    test = test.rename(columns={"SMILES": "smiles"})

    data = pd.concat([train, test], ignore_index=True)

    if as_df:
        if mol_column is None:
            data = data.drop(columns=["mol"])

        render_mol_df(data)
        return data

    return from_df(data, mol_column=mol_column)

Module log

log

without_rdkit_log

Context manager to disable RDKit logs. By default all logs are disabled.

Example:

import datamol as dm

with dm.without_rdkit_log():
    mol = dm.to_mol("CCCCO")  # potential RDKit logs won't show

Source code in datamol/log.py

class without_rdkit_log:
    """Context manager to disable RDKit logs. By default all logs are disabled.

    Example:

    ```python
    import datamol as dm

    with dm.without_rdkit_log():
        mol = dm.to_mol("CCCCO")  # potential RDKit logs won't show
    ```
    """

    def __init__(
        self,
        mute_errors: bool = True,
        mute_warning: bool = True,
        mute_info: bool = True,
        mute_debug: bool = True,
        enable: bool = True,
    ):

        if enable is False:
            mute_errors = False
            mute_warning = False
            mute_info = False
            mute_debug = False

        # Get current log state
        self.previous_status = self._get_log_status()

        # Init the desired log state to apply during in the context
        self.desired_status = {}
        self.desired_status["rdApp.error"] = not mute_errors
        self.desired_status["rdApp.warning"] = not mute_warning
        self.desired_status["rdApp.debug"] = not mute_debug
        self.desired_status["rdApp.info"] = not mute_info

    def _get_log_status(self):
        """Get the current log status of RDKit logs."""
        log_status = rdBase.LogStatus()
        log_status = {st.split(":")[0]: st.split(":")[1] for st in log_status.split("\n")}
        log_status = {k: True if v == "enabled" else False for k, v in log_status.items()}
        return log_status

    def _apply_log_status(self, log_status):
        """Apply an RDKit log status."""
        for k, v in log_status.items():
            if v is True:
                rdBase.EnableLog(k)
            else:
                rdBase.DisableLog(k)

    def __enter__(self):
        self._apply_log_status(self.desired_status)

    def __exit__(self, *args, **kwargs):
        self._apply_log_status(self.previous_status)

disable_rdkit_log()

Disable all rdkit logs.

Source code in datamol/log.py

def disable_rdkit_log():
    """Disable all rdkit logs."""
    for log_level in RDLogger._levels:
        rdBase.DisableLog(log_level)

enable_rdkit_log()

Enable all rdkit logs.

Source code in datamol/log.py

def enable_rdkit_log():
    """Enable all rdkit logs."""
    for log_level in RDLogger._levels:
        rdBase.EnableLog(log_level)