alterlab-rdkit

RDKit 化学信息学工具包

概述

RDKit 是一个全面的化学信息学库，提供用于分子分析和操作的 Python API。本技能介绍如何读取/写入分子结构、计算描述符、生成指纹、进行子结构搜索和化学反应、生成 2D/3D 坐标以及可视化分子。可将本技能用于药物发现、计算化学和化学信息学研究任务。

**版本：**使用 uv pip install rdkit 安装（截至 2026-09，当前版本为 2026.03.6；示例假设版本 ≥ 2024.09）。在 2026.03 中，旧版指纹辅助函数（AllChem.GetMorganFingerprintAsBitVect、rdkit.Chem.AtomPairs.Pairs.*、Torsions.*）以及 Atom.GetImplicitValence() / GetExplicitValence() 仍可运行，但会记录 DEPRECATION WARNING；新代码请使用 rdFingerprintGenerator API 和 atom.GetValence(Chem.ValenceType.IMPLICIT | EXPLICIT)。

何时使用本技能

当你需要对分子进行精细控制时，可使用本技能：自定义标准化、专用指纹或描述符、反应枚举、构象生成或程序化绘图。对于使用更简单接口的标准高级工作流，优先选择 datamol（RDKit 的封装库）。

不适用的场景

场景	改用
代码量尽可能少的标准 pandas 友好型流水线（加载 → 标准化 → 描述符 → 聚类）	alterlab-datamol
将一组分子转换为 ML 特征矩阵或预训练嵌入	alterlab-molfeat
对化合物库进行类药性规则筛选及 PAINS / 结构警示筛查	alterlab-medchem
按名称或 ID 查询化合物的结构、属性或生物活性	alterlab-pubchem 或 alterlab-chembl
蛋白质–配体对接 / 结合姿势预测	alterlab-diffdock

核心功能

RDKit 提供十二个功能领域。下文为每个领域概述了最常用的一种调用方式；每个领域的完整可运行示例都在 references/code_recipes.md 中。

1. 分子 I/O 与创建

使用 SMILES、MOL/SDF、MOL2、PDB 和 InChI 读取和写入分子。使用 Supplier/Writer 对象批量处理，包括用于大型文件或 gzip 压缩文件的 ForwardSDMolSupplier 和 MultithreadedSDMolSupplier。

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

所有 MolFrom* 函数在失败时都会返回 None——使用前务必检查。导入时会自动对分子进行标准化。

2. 分子标准化与验证

解析时会执行 13 步标准化（价态检查、芳香性判定、手性赋值）。可通过 sanitize=False、SanitizeMol 和部分 sanitizeOps 控制，并使用 DetectChemistryProblems 诊断失败原因。

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

常见失败情况：价态溢出、无效芳香环导致的 Kekulé 化错误，以及未赋值的自由基。

3. 分子分析与属性

遍历原子/键，查询环成员关系（GetRingInfo、GetSymmSSSR），检查立体化学（FindMolChiralCenters、AssignStereochemistryFrom3D、bond.GetStereo），并拆解结构（GetMolFrags、FragmentOnBonds、Murcko 骨架）。

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

4. 分子描述符与属性

计算单个描述符（MolWt、MolLogP、TPSA、NumHDonors、NumHAcceptors、NumRotatableBonds），或使用 CalcMolDescriptors 一次性计算全部描述符。支持 Lipinski 五规则类药性检查。

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

可用描述符的完整目录见 references/descriptors_reference.md。

5. 指纹与分子相似性

通过 rdFingerprintGenerator 生成 RDKit 拓扑指纹、Morgan（类似 ECFP）指纹、MACCS 指纹、原子对指纹、拓扑扭转指纹和 Avalon 指纹。使用 Tanimoto/Dice/Cosine（及批量变体）进行比较，并使用 Butina 进行聚类。

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. 子结构搜索与 SMARTS

使用 HasSubstructMatch、GetSubstructMatch 和 GetSubstructMatches 匹配 SMARTS 查询。请记住，未指定的查询属性可以匹配任何内容，而芳香性或带电的查询原子无法匹配脂肪族或不带电的目标原子。

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

references/smarts_patterns.md 中提供了经过整理的功能团、环、药效团和 PAINS SMARTS 模式库。

7. 化学反应

将转化定义为反应 SMARTS（reactants >> products），使用 RunReactants 应用转化，并通过差异指纹计算反应相似度。原子映射可在转化过程中保留原子身份。

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

8. 2D 和 3D 坐标生成

生成 2D 结构绘制坐标（Compute2DCoords、模板对齐）和基于 ETKDG 的 3D 构象（EmbedMolecule、EmbedMultipleConfs），使用 UFF/MMFF 优化，并通过 RMSD 对齐和比较构象。

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

9. 分子可视化

将分子渲染为 PIL 图像、文件或网格（MolToImage、MolToFile、MolsToGridImage），高亮子结构，使用 MolDraw2DCairo 自定义绘图，与 Jupyter 集成，并可视化指纹位。

from rdkit.Chem import Draw
img = Draw.MolsToGridImage([mol1, mol2], molsPerRow=2, subImgSize=(200, 200))

10. 分子修改

添加/移除氢原子（AddHs/RemoveHs）、进行 kekulize 或重置芳香性、替换子结构（ReplaceSubstructs），并使用 rdMolStandardize.Uncharger 中和电荷。

mol_h = Chem.AddHs(mol)   # explicit hydrogens for 3D work or H-dependent properties

11. 分子哈希与标准化

使用 rdMolHash.MolHash 生成规范、骨架和区域异构体哈希，并生成随机 SMILES 以扩增 ML 数据。

from rdkit.Chem import rdMolHash
scaffold_hash = rdMolHash.MolHash(mol, rdMolHash.HashFunction.MurckoScaffold)

12. 药效团与 3D 特征

从 BaseFeatures.fdef 构建特征工厂，并使用 GetFeaturesForMol 提取药效团特征（供体、受体、芳香性、疏水性）。

from rdkit.Chem import ChemicalFeatures
features = factory.GetFeaturesForMol(mol)   # each has GetFamily/GetType/GetAtomIds

常见工作流

可重复使用的端到端方案。scripts/ 中也提供了用于相同任务、可直接运行的脚本（见下文）。

药物相似性分析

from rdkit import Chem
from rdkit.Chem import Descriptors

def analyze_druglikeness(smiles):
    mol = Chem.MolFromSmiles(smiles)
    if mol is None:
        return None

    # Calculate Lipinski descriptors
    results = {
        'MW': Descriptors.MolWt(mol),
        'LogP': Descriptors.MolLogP(mol),
        'HBD': Descriptors.NumHDonors(mol),
        'HBA': Descriptors.NumHAcceptors(mol),
        'TPSA': Descriptors.TPSA(mol),
        'RotBonds': Descriptors.NumRotatableBonds(mol)
    }

    # Check Lipinski's Rule of Five
    results['Lipinski'] = (
        results['MW'] <= 500 and
        results['LogP'] <= 5 and
        results['HBD'] <= 5 and
        results['HBA'] <= 10
    )

    return results

相似性筛选

from rdkit import Chem
from rdkit.Chem import rdFingerprintGenerator
from rdkit import DataStructs

def similarity_screen(query_smiles, database_smiles, threshold=0.7):
    mfpgen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
    query_mol = Chem.MolFromSmiles(query_smiles)
    query_fp = mfpgen.GetFingerprint(query_mol)

    hits = []
    for idx, smiles in enumerate(database_smiles):
        mol = Chem.MolFromSmiles(smiles)
        if mol:
            fp = mfpgen.GetFingerprint(mol)
            sim = DataStructs.TanimotoSimilarity(query_fp, fp)
            if sim >= threshold:
                hits.append((idx, smiles, sim))

    return sorted(hits, key=lambda x: x[2], reverse=True)

子结构筛选

from rdkit import Chem

def filter_by_substructure(smiles_list, pattern_smarts):
    query = Chem.MolFromSmarts(pattern_smarts)

    hits = []
    for smiles in smiles_list:
        mol = Chem.MolFromSmiles(smiles)
        if mol and mol.HasSubstructMatch(query):
            hits.append(smiles)

    return hits

最佳实践

错误处理

解析分子时，始终检查是否为 None：

mol = Chem.MolFromSmiles(smiles)
if mol is None:
    print(f"Failed to parse: {smiles}")
    continue

性能优化

使用 pickle 保存分子以便快速重新加载，而不是重新解析；对指纹和相似度计算使用批量操作：

import pickle
with open('molecules.pkl', 'wb') as f:
    pickle.dump(mols, f)   # load side is much faster than reparsing SMILES/SDF

mfpgen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
fps = mfpgen.GetFingerprints(mols, numThreads=4)   # batched, multithreaded
similarities = DataStructs.BulkTanimotoSimilarity(fps[0], fps[1:])

线程安全

RDKit 的分子 I/O、坐标生成、指纹计算和描述符计算、子结构搜索、反应及绘图操作通常是线程安全的。**非线程安全：**并发访问时的 MolSuppliers——不要在线程之间共享同一个 supplier 对象。

内存管理

对于大型数据集，采用流式处理，而不是一次性加载所有数据：

# Avoid loading the entire file into memory
with open('large.sdf') as f:
    suppl = Chem.ForwardSDMolSupplier(f)
    for mol in suppl:
        # Process one molecule at a time
        pass

# Parallel processing
suppl = Chem.MultithreadedSDMolSupplier('large.sdf', numWriterThreads=4)

常见陷阱

1. **忘记检查是否为 None：**解析后始终验证分子
2. **清理失败：**使用 DetectChemistryProblems() 进行调试
3. **缺少氢原子：**计算依赖氢原子的属性时使用 AddHs()
4. **2D 与 3D：**在可视化或进行 3D 分析之前生成合适的坐标
5. **SMARTS 匹配规则：**请记住，未指定的属性可以匹配任何内容
6. **MolSuppliers 的线程安全：**不要在线程之间共享 supplier 对象

资源

references/

• code_recipes.md — 上述十二个功能领域的完整可运行代码
• api_reference.md — 按功能整理的 RDKit 模块、函数和类的全面列表
• descriptors_reference.md — 可用分子描述符的完整列表及其说明
• smarts_patterns.md — 用于功能团和结构特征的常见 SMARTS 模式

需要具体 API 细节、参数信息或模式示例时，请加载这些参考资料。

scripts/

常见 RDKit 工作流示例脚本：

• molecular_properties.py — 计算全面的分子属性和描述符
• similarity_search.py — 执行基于指纹的相似性筛选
• substructure_filter.py — 根据子结构模式筛选分子

这些脚本可以直接执行，也可以用作自定义工作流的模板。

属于 AlterLab Academic Skills 套件的一部分。