Alterlab Datamol

Datamol Cheminformatics Skill

Overview

Datamol is a Python library that provides a lightweight, Pythonic abstraction layer over RDKit for molecular cheminformatics. Simplify complex molecular operations with sensible defaults, efficient parallelization, and modern I/O capabilities. All molecular objects are native rdkit.Chem.Mol instances, ensuring full compatibility with the RDKit ecosystem.

Key capabilities:

• Molecular format conversion (SMILES, SELFIES, InChI)
• Structure standardization and sanitization
• Molecular descriptors and fingerprints
• 3D conformer generation and analysis
• Clustering and diversity selection
• Scaffold and fragment analysis
• Chemical reaction application
• Visualization and alignment
• Batch processing with parallelization
• Cloud storage support via fsspec

Installation and Setup

Guide users to install datamol:

uv pip install datamol

Examples here are verified against datamol 0.12.x (pulls in RDKit automatically). The descriptor key names below are stable in this line; pin if you depend on them: `uv pip install 'datamol>=0.12,>[C:1](=[O:2])[Cl:3]' rxn = rdChemReactions.ReactionFromSmarts(rxn_smarts)

Apply to molecule

reactant = dm.tomol("CC(=O)O") # Acetic acid product = dm.reactions.applyreaction( rxn, (reactant,), sanitize=True )

Convert to SMILES

productsmiles = dm.tosmiles(product)

**Batch reaction application**:
```python
# Apply reaction to library
products = []
for mol in reactant_mols:
    try:
        prod = dm.reactions.apply_reaction(rxn, (mol,))
        if prod is not None:
            products.append(prod)
    except Exception as e:
        print(f"Reaction failed: {e}")

Parallelization

Datamol includes built-in parallelization for many operations. Use n_jobs parameter:

• n_jobs=1: Sequential (no parallelization)
• n_jobs=-1: Use all available CPU cores
• n_jobs=4: Use 4 cores

Functions supporting parallelization:

• dm.read_sdf(..., n_jobs=-1)
• dm.descriptors.batch_compute_many_descriptors(..., n_jobs=-1)
• dm.cluster_mols(..., n_jobs=-1)
• dm.pdist(..., n_jobs=-1)
• dm.conformers.sasa(..., n_jobs=-1)

Progress bars: Many batch operations support progress=True parameter.

Common Workflows and Patterns

Complete Pipeline: Data Loading → Filtering → Analysis

import datamol as dm
import pandas as pd

# 1. Load molecules
df = dm.read_sdf("compounds.sdf")

# 2. Standardize
df['mol'] = df['mol'].apply(lambda m: dm.standardize_mol(m) if m else None)
df = df[df['mol'].notna()]  # Remove failed molecules

# 3. Compute descriptors
desc_df = dm.descriptors.batch_compute_many_descriptors(
    df['mol'].tolist(),
    n_jobs=-1,
    progress=True
)

# 4. Filter by drug-likeness (batch_compute_many_descriptors uses the same keys
#    as compute_many_descriptors: clogp, n_lipinski_hbd, n_lipinski_hba)
druglike = (
    (desc_df['mw'] = 3:  # Need multiple examples
        print(f"\nScaffold: {scaffold}")
        print(f"Count: {len(group)}")
        print(f"Activity range: {group['activity'].min():.2f} - {group['activity'].max():.2f}")

        # Visualize with activities as legends
        dm.viz.to_image(
            group['mol'].tolist(),
            legends=[f"Activity: {act:.2f}" for act in group['activity']],
            align=True  # Align by common substructure
        )

Virtual Screening Pipeline

# 1. Calculate Tanimoto distances between query actives and the library.
#    dm.cdist takes the molecules directly (it fingerprints internally),
#    returning an (n_query, n_library) distance matrix.
import numpy as np

distances = dm.cdist(query_actives, library_mols, n_jobs=-1)

# 3. Find closest matches (min distance to any query)
min_distances = distances.min(axis=0)
similarities = 1 - min_distances  # Convert distance to similarity

# 4. Rank and select top hits
top_indices = np.argsort(similarities)[::-1][:100]  # Top 100
top_hits = [library_mols[i] for i in top_indices]
top_scores = [similarities[i] for i in top_indices]

# 5. Visualize hits
dm.viz.to_image(
    top_hits[:20],
    legends=[f"Sim: {score:.3f}" for score in top_scores[:20]],
    outfile="screening_hits.png"
)

Reference Documentation

For detailed API documentation, consult these reference files:

• references/core_api.md: Core namespace functions (conversions, standardization, fingerprints, clustering)
• references/io_module.md: File I/O operations (read/write SDF, CSV, Excel, remote files)
• references/conformers_module.md: 3D conformer generation, clustering, SASA calculations
• references/descriptors_viz.md: Molecular descriptors and visualization functions
• references/fragments_scaffolds.md: Scaffold extraction, BRICS/RECAP fragmentation
• references/reactions_data.md: Chemical reactions and toy datasets

Best Practices

1. Always standardize molecules from external sources:

``python mol = dm.standardize_mol(mol, disconnect_metals=True, normalize=True, reionize=True) ``

1. Check for None values after molecule parsing:

``python mol = dm.to_mol(smiles) if mol is None: # Handle invalid SMILES ``

1. Use parallel processing for large datasets:

``python result = dm.operation(..., n_jobs=-1, progress=True) ``

1. Leverage fsspec for cloud storage:

``python df = dm.read_sdf("s3://bucket/compounds.sdf") ``

1. Use appropriate fingerprints for similarity:

• ECFP (Morgan): General purpose, structural similarity
• MACCS: Fast, smaller feature space
• Atom pairs: Considers atom pairs and distances

1. Consider scale limitations:

• Butina clustering: ~1,000 molecules (full distance matrix)
• For larger datasets: Use diversity selection or hierarchical methods

1. Scaffold splitting for ML: Ensure proper train/test separation by scaffold

1. Align molecules when visualizing SAR series

Error Handling

# Safe molecule creation
def safe_to_mol(smiles):
    try:
        mol = dm.to_mol(smiles)
        if mol is not None:
            mol = dm.standardize_mol(mol)
        return mol
    except Exception as e:
        print(f"Failed to process {smiles}: {e}")
        return None

# Safe batch processing
valid_mols = []
for smiles in smiles_list:
    mol = safe_to_mol(smiles)
    if mol is not None:
        valid_mols.append(mol)

Integration with Machine Learning

# Feature generation
X = np.array([dm.to_fp(mol) for mol in mols])

# Or descriptors
desc_df = dm.descriptors.batch_compute_many_descriptors(mols, n_jobs=-1)
X = desc_df.values

# Train model
from sklearn.ensemble import RandomForestRegressor
model = RandomForestRegressor()
model.fit(X, y_target)

# Predict
predictions = model.predict(X_test)

Troubleshooting

Issue: Molecule parsing fails

• Solution: Use dm.standardize_smiles() first or try dm.fix_mol()

Issue: Memory errors with clustering

• Solution: Use dm.pick_diverse() instead of full clustering for large sets

Issue: Slow conformer generation

• Solution: Reduce n_confs or increase rms_cutoff to generate fewer conformers

Issue: Remote file access fails

• Solution: Ensure fsspec and appropriate cloud provider libraries are installed (s3fs, gcsfs, etc.)

Additional Resources

• Datamol Documentation: https://docs.datamol.io/
• RDKit Documentation: https://www.rdkit.org/docs/
• GitHub Repository: https://github.com/datamol-io/datamol

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AlterLab-IEU
• Source: AlterLab-IEU/AlterLab-Academic-Skills
• License: MIT
• Homepage: https://alterlab-ieu.github.io/AlterLab-Academic-Skills/

Install and usage instructions live in the source repository linked above.