---

name: datamol description: A Pythonic wrapper around RDKit with simplified interfaces and sensible defaults. Preferred for standard drug discovery workflows including SMILES parsing, standardization, descriptors, fingerprints, clustering, 3D conformer generation, and parallel processing. Returns native rdkit.Chem.Mol objects. For advanced control or custom parameters, use rdkit directly. license: MIT author: AIPOCH

Source: https://github.com/aipoch/medical-research-skills

When to Use

• Use this skill when the request matches its documented task boundary.
• Use it when the user can provide the required inputs and expects a structured deliverable.
• Prefer this skill for repeatable, checklist-driven execution rather than open-ended brainstorming.

Key Features

• Scope-focused workflow aligned to: A Pythonic wrapper around RDKit with simplified interfaces and sensible defaults. Preferred for standard drug discovery workflows including SMILES parsing, standardization, descriptors, fingerprints, clustering, 3D conformer generation, and parallel processing. Returns native rdkit.Chem.Mol objects. For advanced control or custom parameters, use rdkit directly.
• Packaged executable path(s): scripts/validate_skill.py.
• Reference material available in references/ for task-specific guidance.
• Structured execution path designed to keep outputs consistent and reviewable.

Dependencies

• Python: 3.10+. Repository baseline for current packaged skills.
• Third-party packages: not explicitly version-pinned in this skill package. Add pinned versions if this skill needs stricter environment control.

Example Usage

cd "20260316/scientific-skills/Others/datamol"
python -m py_compile scripts/validate_skill.py
python scripts/validate_skill.py --help

Example run plan:

1. Confirm the user input, output path, and any required config values.
2. Edit the in-file CONFIG block or documented parameters if the script uses fixed settings.
3. Run python scripts/validate_skill.py with the validated inputs.
4. Review the generated output and return the final artifact with any assumptions called out.

Implementation Details

See ## Overview above for related details.

• Execution model: validate the request, choose the packaged workflow, and produce a bounded deliverable.
• Input controls: confirm the source files, scope limits, output format, and acceptance criteria before running any script.
• Primary implementation surface: scripts/validate_skill.py.
• Reference guidance: references/ contains supporting rules, prompts, or checklists.
• Parameters to clarify first: input path, output path, scope filters, thresholds, and any domain-specific constraints.
• Output discipline: keep results reproducible, identify assumptions explicitly, and avoid undocumented side effects.

Validation Shortcut

Run this minimal command first to verify the supported execution path:

python scripts/validate_skill.py --help

Datamol Cheminformatics Skill

Overview

Datamol is a Python library that provides a lightweight, Pythonic abstraction layer over RDKit for molecular cheminformatics. It simplifies complex molecular operations through 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.

Core 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
• Parallelized batch processing
• Cloud storage support via fsspec

Installation and Setup

Guide users to install datamol:

uv pip install datamol

Import Convention:

import datamol as dm
Core Workflows
1. Basic Molecular Operations

Create a molecule from SMILES:

import datamol as dm

# Single molecule
mol = dm.to_mol("CCO")  # Ethanol

# From a list of SMILES
smiles_list = ["CCO", "c1ccccc1", "CC(=O)O"]
mols = [dm.to_mol(smi) for smi in smiles_list]

# Error handling
mol = dm.to_mol("invalid_smiles")  # Returns None
if mol is None:
    print("Failed to parse SMILES")

Convert molecule to SMILES:

# Standard SMILES
smiles = dm.to_smiles(mol)

# Isomeric SMILES (includes stereochemistry)
smiles = dm.to_smiles(mol, isomeric=True)

# Other formats
inchi = dm.to_inchi(mol)
inchikey = dm.to_inchikey(mol)
selfies = dm.to_selfies(mol)

Standardization and sanitization (always recommended for user-provided molecules):

# Sanitize molecule
mol = dm.sanitize_mol(mol)

# Full standardization (recommended for datasets)
mol = dm.standardize_mol(
    mol,
    disconnect_metals=True,
    normalize=True,
    reionize=True
)

# Directly on SMILES string
clean_smiles = dm.standardize_smiles(smiles)
2. Reading and Writing Molecular Files

Refer to references/io_module.md for full I/O documentation.

Read files:

# SDF file (most common in chemistry)
df = dm.read_sdf("compounds.sdf", mol_column='mol')

# SMILES file
df = dm.read_smi("molecules.smi", smiles_column='smiles', mol_column='mol')

# CSV with SMILES column
df = dm.read_csv("data.csv", smiles_column="SMILES", mol_column="mol")

# Excel file
df = dm.read_excel("compounds.xlsx", sheet_name=0, mol_column="mol")

# Universal reader (auto-detect format)
df = dm.open_df("file.sdf")  # Supports .sdf, .csv, .xlsx, .parquet, .json

Write files:

# Save as SDF
dm.to_sdf(mols, "output.sdf")

# Or from DataFrame
dm.to_sdf(df, "output.sdf", mol_column="mol")

# Save as SMILES file
dm.to_smi(mols, "output.smi")

# Excel with molecule renderings
dm.to_xlsx(df, "output.xlsx", mol_columns=["mol"])

Remote file support (S3, GCS, HTTP):

# Read from cloud storage
df = dm.read_sdf("s3://bucket/compounds.sdf")
df = dm.read_csv("https://example.com/data.csv")

# Write to cloud storage
dm.to_sdf(mols, "s3://bucket/output.sdf")
3. Molecular Descriptors and Properties

Refer to references/descriptors_viz.md for detailed descriptor documentation.

Compute descriptors for a single molecule:

# Get standard descriptor set
descriptors = dm.descriptors.compute_many_descriptors(mol)

# Returns: {'mw': 46.07, 'logp': -0.03, 'hbd': 1, 'hba': 1,

#           'tpsa': 20.23, 'n_aromatic_atoms': 0, ...}

Batch descriptor computation (recommended for datasets):

# Parallel computation for all molecules
desc_df = dm.descriptors.batch_compute_many_descriptors(
    mols,
    n_jobs=-1,      # Use all CPU cores
    progress=True   # Show progress bar
)

Specific descriptors:

# Aromaticity
n_aromatic = dm.descriptors.n_aromatic_atoms(mol)
aromatic_ratio = dm.descriptors.n_aromatic_atoms_proportion(mol)

# Stereochemistry
n_stereo = dm.descriptors.n_stereo_centers(mol)
n_unspec = dm.descriptors.n_stereo_centers_unspecified(mol)

# Rigidity
n_rigid = dm.descriptors.n_rigid_bonds(mol)

Drug-likeness filtering (Lipinski's Rule of Five):

# Filter compounds
def is_druglike(mol):
    desc = dm.descriptors.compute_many_descriptors(mol)
    return (
        desc['mw'] <= 500 and
        desc['logp'] <= 5 and
        desc['hbd'] <= 5 and
        desc['hba'] <= 10
    )

druglike_mols = [mol for mol in mols if is_druglike(mol)]
4. Molecular Fingerprints and Similarity

Generate fingerprints:

# ECFP (Extended Connectivity Fingerprint, default)
fp = dm.to_fp(mol, fp_type='ecfp', radius=2, n_bits=2048)

# Other fingerprint types
fp_maccs = dm.to_fp(mol, fp_type='maccs')
fp_topological = dm.to_fp(mol, fp_type='topological')
fp_atompair = dm.to_fp(mol, fp_type='atompair')

Similarity calculation:

# Pairwise distances within a set
distance_matrix = dm.pdist(mols, n_jobs=-1)

# Distances between two sets
distances = dm.cdist(query_mols, library_mols, n_jobs=-1)

# Find most similar molecules
from scipy.spatial.distance import squareform
dist_matrix = squareform(dm.pdist(mols))

# Lower distance = higher similarity (Tanimoto distance = 1 - Tanimoto similarity)
5. Clustering and Diversity Selection

Refer to references/core_api.md for clustering details.

Butina clustering:

# Cluster molecules based on structural similarity
clusters = dm.cluster_mols(
    mols,
    cutoff=0.2,    # Tanimoto distance threshold (0=identical, 1=completely different)
    n_jobs=-1      # Parallel processing
)

# Each cluster is a list of molecule indices
for i, cluster in enumerate(clusters):
    print(f"Cluster {i}: {len(cluster)} molecules")
    cluster_mols = [mols[idx] for idx in cluster]

Important Note: Butina clustering builds a full distance matrix — suitable for ~1,000 molecules, not recommended for >10,000 molecules.

Diversity selection:

# Pick diverse subset
diverse_mols = dm.pick_diverse(
    mols,
    npick=100  # Select 100 diverse molecules
)

# Pick cluster centroids (representative molecules)
centroids = dm.pick_centroids(
    mols,
    npick=50   # Select 50 representative molecules
)
6. Scaffold Analysis

Refer to references/fragments_scaffolds.md for full scaffold documentation.

Extract Murcko scaffold:

# Get Bemis-Murcko scaffold (core structure)
scaffold = dm.to_scaffold_murcko(mol)
scaffold_smiles = dm.to_smiles(scaffold)

Scaffold-based analysis:

# Group compounds by scaffold
from collections import Counter

scaffolds = [dm.to_scaffold_murcko(mol) for mol in mols]
scaffold_smiles = [dm.to_smiles(s) for s in scaffolds]

# Count scaffold frequency
scaffold_counts = Counter(scaffold_smiles)
most_common = scaffold_counts.most_common(10)

# Create scaffold-to-molecule mapping
scaffold_groups = {}
for mol, scaf_smi in zip(mols, scaffold_smiles):
    if scaf_smi not in scaffold_groups:
        scaffold_groups[scaf_smi] = []
    scaffold_groups[scaf_smi].append(mol)

Scaffold-based train/test split (for machine learning):

# Ensure train and test sets have different scaffolds
scaffold_to_mols = {}
for mol, scaf in zip(mols, scaffold_smiles):
    if scaf not in scaffold_to_mols:
        scaffold_to_mols[scaf] = []
    scaffold_to_mols[scaf].append(mol)

# Split scaffolds into train/test
import random
scaffolds = list(scaffold_to_mols.keys())
random.shuffle(scaffolds)
split_idx = int(0.8 * len(scaffolds))
train_scaffolds = scaffolds[:split_idx]
test_scaffolds = scaffolds[split_idx:]

# Get molecules for each split
train_mols = [mol for scaf in train_scaffolds for mol in scaffold_to_mols[scaf]]
test_mols = [mol for scaf in test_scaffolds for mol in scaffold_to_mols[scaf]]
7. Molecular Fragmentation

Refer to references/fragments_scaffolds.md for fragmentation details.

BRICS fragmentation (16 bond types):

# Decompose molecule
fragments = dm.fragment.brics(mol)

# Returns: set of fragment SMILES with connection points, e.g. '[1*]CCN'

RECAP fragmentation (11 bond types):

fragments = dm.fragment.recap(mol)

Fragment analysis:

# Find common fragments in a compound library
from collections import Counter

all_fragments = []
for mol in mols:
    frags = dm.fragment.brics(mol)
    all_fragments.extend(frags)

fragment_counts = Counter(all_fragments)
common_frags = fragment_counts.most_common(20)

# Fragment-based scoring
def fragment_score(mol, reference_fragments):
    mol_frags = dm.fragment.brics(mol)
    overlap = mol_frags.intersection(reference_fragments)
    return len(overlap) / len(mol_frags) if mol_frags else 0
8. 3D Conformer Generation

Refer to references/conformers_module.md for detailed conformer documentation.

Generate conformers:

# Generate 3D conformers
mol_3d = dm.conformers.generate(
    mol,
    n_confs=50,            # Number to generate (auto if None)
    rms_cutoff=0.5,        # Filter similar conformers (Å)
    minimize_energy=True,  # Energy minimization with UFF force field
    method='ETKDGv3'       # Embedding method (recommended)
)

# Access conformers
n_conformers = mol_3d.GetNumConformers()
conf = mol_3d.GetConfor