DOCSEARCHbyAlgolia
Submit Docs

datamol

repository·main·Indexed 19 days ago

https://github.com/datamol-io/datamol

A lightweight Python library for molecular processing and cheminformatics, built as a high-level wrapper around RDKit. It provides tools for molecule manipulation, conversion between SMILES/InChI/SELFIES, standardization, fingerprinting, and clustering using the Butina algorithm. The library includes features for 2D/3D visualization, conformer generation, and efficient I/O support for remote paths via fsspec.

Tokens
22.7K
Snippets
92
Records
102
Agent score
68%

What's inside datamol

  1. Use `datamol.fragment` to manage molecular fragments

    main
    The datamol.fragment module provides tools for working with molecular fragments. It includes functionality for creating and assembling fragments, which is useful for tasks like fragment-based drug discovery or decomposing larger molecules into smaller, manageable pieces.

  5. Quick API Tour

    main

    Datamol provides a high-level, pythonic API for common molecular tasks. It works directly with rdkit.Chem.Mol objects. Key functional areas include:

    • Conversion: Convert between SMILES, InChI, SELFIES, and fingerprints.
    • Standardization: Fix and sanitize molecules.
    • Dataframe Integration: Convert between pandas DataFrames and molecule lists.
    • Visualization: Generate 2D images and 3D conformer views.
    • Conformers: Generate conformers and compute SASA (Solvent Accessible Surface Area).
    • IO: Read and write molecular formats (like SDF) using remote paths (e.g., S3, Google Storage) via fsspec support.
    import datamol as dm

# Common functions
mol = dm.to_mol("O=C(C)Oc1ccccc1C(=O)O", sanitize=True)
fp = dm.to_fp(mol)
selfies = dm.to_selfies(mol)
inchi = dm.to_inchi(mol)

# Standardize and sanitize
mol = dm.to_mol("O=C(C)Oc1ccccc1C(=O)O")
mol = dm.fix_mol(mol)
mol = dm.sanitize_mol(mol)
mol = dm.standardize_mol(mol)

# Dataframe manipulation
df = dm.data.freesolv()
mols = dm.from_df(df)

# 2D viz
legends = [dm.to_smiles(mol) for mol in mols[:10]]
dm.viz.to_image(mols[:10], legends=legends)

# Generate conformers
smiles = "O=C(C)Oc1ccccc1C(=O)O"
mol = dm.to_mol(smiles)
mol_with_conformers = dm.conformers.generate(mol)

# 3D viz (using nglview)
dm.viz.conformers(mol, n_confs=10)

# Compute SASA from conformers
sasa = dm.conformers.sasa(mol_with_conformers)

# Easy IO
mols = dm.read_sdf("s3://my-awesome-data-lake/smiles.sdf", as_df=False)
dm.to_sdf(mols, "gs://data-bucket/smiles.sdf")

  6. Explore the Datamol API surface

    main

    Datamol provides a high-level API for cheminformatics tasks, including molecule manipulation, conversion, clustering, fingerprinting, and I/O. The package uses lazy loading to keep the initial import fast. Most core functionality is accessible directly from the datamol namespace.

    Key functional areas include:

    • Molecule Manipulation (datamol.mol): Sanitization, standardization, atom/bond manipulation, and scaffold operations.
    • Conversion (datamol.convert): Converting between SMILES, InChI, SELFIES, SMARTS, and DataFrames.
    • Fingerprints (datamol.fp): Generating and manipulating molecular fingerprints.
    • I/O (datamol.io): Reading and writing SDF, SMILES, PDB, Mol2, and Excel/CSV files.
    • Isomers (datamol.isomers): Enumerating stereoisomers and tautomers.
    • Clustering (datamol.cluster): Clustering molecules and picking diverse sets or centroids.
    • Visualization (datamol.viz): Generating molecular images.
    • Graph Operations (datamol.graph): Converting molecules to graphs and matching molecular graphs.

  7. Render molecules in a Pandas DataFrame

    main

    To visualize molecules stored within a Pandas DataFrame, first convert your SMILES strings into molecule objects using dm.to_mol(). You can then use dm.render_mol_df(df) to enable rich rendering of the molecule column within your notebook environment.

    import datamol as dm

# Convert SMILES to mol objects
data["mol"] = data["smiles"].apply(dm.to_mol)

# Enable rendering in the dataframe
dm.render_mol_df(data)

  8. Load molecules from an SDF file into a DataFrame

    main

    Use dm.read_sdf with the as_df=True flag to load an SDF file directly into a pandas DataFrame. When using this flag, Datamol automatically creates a smiles column from the SDF file. You can then convert these SMILES strings into molecule objects using dm.to_mol.

    import datamol as dm

# Load SDF as a DataFrame
data = dm.read_sdf("./data/Enamine_DNA_Libary_5530cmpds_20200831_SMALL.sdf", as_df=True)

# Convert SMILES column to molecule objects
data["mol"] = data["smiles"].apply(dm.to_mol)

mols = data["mol"].tolist()

  9. Filter molecules using Lipinski's Rule of Five (Ro5)

    main

    Lipinski's Rule of Five (Ro5) is used to estimate drug-likeness. You can filter a DataFrame of computed descriptors to find molecules that comply with these criteria:

    • Molecular Weight (mw) $\le$ 500 Da
    • Hydrogen Bond Acceptors (n_lipinski_hba) $\le$ 10
    • Hydrogen Bond Donors (n_lipinski_hbd) $\le$ 5
    • Calculated LogP (clogp) $\le$ 5
    # Filtering a DataFrame based on Ro5 criteria
df = df[df["mw"] <= 500]
df = df[df["n_lipinski_hba"] <= 10]
df = df[df["n_lipinski_hbd"] <= 5]
df = df[df["clogp"] <= 5]

  10. Disable Datamol lazy loading

    main

    By default, Datamol uses lazy loading for its submodules and objects to improve startup performance. If you need to disable this behavior (e.g., for certain debugging scenarios or specific runtime requirements), set the DATAMOL_DISABLE_LAZY_LOADING environment variable to "1".

    export DATAMOL_DISABLE_LAZY_LOADING=1
    export DATAMOL_DISABLE_LAZY_LOADING=1

  11. Perform destructive filesystem operations with `datamol.fs`

    main

    The datamol.fs module provides high-level functions for manipulating files and directories. While the examples below use local paths, all functions support remote protocols such as S3, GCS, HTTP, FTP, and Git because the module is built on top of fsspec.

    Key destructive operations include:

    • mkdir(path, exist_ok=True): Creates a directory.
    • copy_file(source, destination, progress=True, force=True): Copies a single file. Use force=True to overwrite existing files.
    • copy_dir(source, destination, progress=True): Copies an entire directory tree.
    import datamol as dm

# Create a directory
subdir_path = dm.fs.join(temp_dir, "subdir1", "subsubdir293")
dm.fs.mkdir(subdir_path, exist_ok=True)

# Copy a single file from a URL to a local path
destination_path = dm.fs.join(subdir_path, "cdk2.sdf")
dm.fs.copy_file(
    source="https://raw.githubusercontent.com/rdkit/rdkit/master/Docs/Book/data/cdk2.sdf",
    destination=destination_path,
    progress=True,
    force=True,
)

# Copy a full directory tree
subdir2_path = dm.fs.join(temp_dir, "subdir2")
dm.fs.copy_dir(
    source="https://ftp.ncbi.nlm.nih.gov/pubchem/specifications/",
    destination=subdir2_path,
    progress=True,
)

  12. Disable lazy loading in datamol

    main

    Datamol uses lazy loading to expose its API dynamically and minimize import times. If you encounter issues related to the dynamic API exposure, you can disable this behavior by setting the DATAMOL_DISABLE_LAZY_LOADING environment variable to 1.

    export DATAMOL_DISABLE_LAZY_LOADING=1