alterlab-rdkit

Files (9)

• SKILL.md
• evals.json · evals/
• api_reference.md · references/
• code_recipes.md · references/
• descriptors_reference.md · references/
• smarts_patterns.md · references/
• molecular_properties.py · scripts/
• similarity_search.py · scripts/
• substructure_filter.py · scripts/

SKILL.md (first lines)

# RDKit Cheminformatics Toolkit

## Overview

RDKit is a comprehensive cheminformatics library providing Python APIs for molecular analysis and manipulation. This skill provides guidance for reading/writing molecular structures, calculating descriptors, fingerprinting, substructure searching, chemical reactions, 2D/3D coordinate generation, and molecular visualization. Use this skill for drug discovery, computational chemistry, and cheminformatics research tasks.

**Version:** run install-free with `uv run --python ">=3.11" --with rdkit python your_script.py` (uv's default Python here is 3.9, so pin the interpreter; a persistent `uv pip install rdkit` works too). Current release 2026.09.1 as of 2026-10; examples assume ≥ 2024.09. In 2026.03 the legacy fingerprint helpers (`AllChem.GetMorganFingerprintAsBitVect`, `rdkit.Chem.AtomPairs.Pairs.*`, `Torsions.*`) and `Atom.GetImplicitValence()` / `GetExplicitValence()` still run but log `DEPRECATION WARNING`s — use the `rdFingerprintGenerator` API and `atom.GetValence(Chem.ValenceType.IMPLICIT | EXPLICIT)` in new code.

## When to Use This Skill

Reach for this skill when you need fine-grained molecular control: custom sanitization, specialized fingerprints or descriptors, reaction enumeration, conformer generation, or programmatic drawing. For standard, high-level workflows with a simpler interface, prefer **datamol** (a wrapper around RDKit).

### Does NOT Trigger

| Scenario | Use Instead |
|----------|-------------|
| Standard pandas-friendly pipelines (load → standardize → descriptors → cluster) with minimal code | `alterlab-datamol` |
| Turning a molecule set into ML feature matrices or pretrained embeddings | `alterlab-molfeat` |
| Drug-likeness rule sets and PAINS / structural-alert triage of a library | `alterlab-medchem` |
| Looking up a compound's structure, properties, or bioactivity by name or ID | `alterlab-pubchem` or `alterlab-chembl` |
| Protein–ligand docking / binding-pose prediction | `alterlab-diffdock` |

**Hand-off rule.** When the request matches a row above, open your answer by naming that skill by its exact id (for example `alterlab-datamol`) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.

## Core Capabilities

RDKit exposes twelve capability areas. Each is summarized below with the single most common call; **complete, runnable recipes for every area live in `references/code_recipes.md`.**

### 1. Molecular I/O and Creation

Read and write molecules across SMILES, MOL/SDF, MOL2, PDB, and InChI. Batch-process with Supplier/Writer objects, including `ForwardSDMolSupplier` and `MultithreadedSDMolSupplier` for large or gzipped files.

```python
from rdkit import Chem
mol = Chem.MolFromSmiles('Cc1ccccc1')   # returns Mol or None
smiles = Chem.MolToSmiles(mol)          # canonical SMILES
```

Every `MolFrom*` function returns `None` on failure — always check before use. Molecules are auto-sanitized on import.

### 2. Molecular Sanitization and Validation

Parsing runs a 13-step sanitization (valence checks, aromaticity perception, chirality assignment). Control it with `sanitize=False`, `SanitizeMol`, partial `sanitizeOps`, and diagnose failures with `DetectChemistryProblems`.

```python
mol = Chem.MolFromSmiles('C1=CC=CC=C1', sanitize=False)
problems = Chem.DetectChemistryProblems(mol)
```

Common failure modes: valence overflow, kekulization errors on invalid aromatic rings, and unassigned radicals.

### 3. Molecular Analysis and Properties

Iterate atoms/bonds, query ring membership (`GetRingInfo`, `GetSymmSSSR`), inspect stereochemistry (`FindMolChiralCenters`, `AssignStereochemistryFrom3D`, `bond.GetStereo`), and decompose structures (`GetMolFrags`, `FragmentOnBonds`, Murcko scaffolds).

```python
for atom in mol.GetAtoms():
    print(atom.GetSymbol(), atom.GetIdx(), atom.GetDegree())
```

### 4. Molecular Descriptors and Properties

Compute individual descriptors (`MolWt`, `MolLogP`, `TPSA`, `NumHDonors`, `NumHAcceptors`, `NumRotatableBonds`) or all at once with `CalcMolDescriptors`. Supports Lipinski Rule-of-Five drug-likeness checks.

```python
from rdkit.Chem import Descriptors
all_descriptors = Descriptors.CalcMolDescriptors(mol)   # dict of every descriptor
```

The full catalog of available descriptors is documented in `references/descriptors_reference.md`.

### 5. Fingerprints and Molecular Similarity

Generate RDKit topological, Morgan (ECFP-like), MACCS, atom-pair, topological-torsion, and Avalon fingerprints via `rdFingerprintGenerator`. Compare with Tanimoto/Dice/Cosine (and bulk variants), and cluster with Butina.

```python
from rdkit.Chem import rdFingerprintGenerator
from rdkit import DataStructs
gen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
sim = DataStructs.TanimotoSimilarity(gen.GetFingerprint(mol1), gen.GetFingerprint(mol2))
```

### 6. Substructure Searching and SMARTS

Match SMARTS queries with `HasSubstructMatch`, `GetSubstructMatch`, and `GetSubstructMatches`. Remember that unspecified query properties match anything, and aromatic/charged query atoms won't match aliphatic/uncharged targets.

```python
query = Chem.MolFromSmarts('C(=O)[OH]')   # carboxylic acid
matches = mol.GetSubstructMatches(query)
```

A curated library of functional-group, ring, pharmacophore, and PAINS SMARTS patterns is in `references/smarts_patterns.md`.

### 7. Chemical Reactions

Define transformations as reaction SMARTS (`reactants >> products`), apply with `RunReactants`, and compute reaction similarity via difference fingerprints. Atom mapping preserves atom identity across the transform.

```python
from rdkit.Chem import AllChem
rxn = AllChem.ReactionFromSmarts('[C:1]=[O:2]>>[C:1][O:2]')
products = rxn.RunReactants((mol,))
```

### 8. 2D and 3D Coordinate Generation

Generate 2D depiction coordinates (`Compute2DCoords`, template alignment) and 3D conformers via ETKDG (`EmbedMolecule`, `EmbedMultipleConfs`), optimize with UFF/MMFF, and align/compare conformers by RMSD.

```python
from rdkit.Chem import AllChem
AllChem.EmbedMolecule(mol, randomSeed=42)
AllChem.MMFFOptimizeMolecule(mol)
```

### 9. Molecular Visualization

Render molecules to PIL images, files, or grids (`MolToImage`, `MolToFile`, `MolsToGridImage`), highlight substructures, customize drawings via `MolDraw2DCairo`, integrate with Jupyter, and visualize fingerprint bits.

```python
from rdkit.Chem import Draw

From AlterLab-IEU/AlterLab-Academic-Skills, MIT.

More from AlterLab-IEU/AlterLab-Academic-Skills