alterlab-datamol

Datamol 化学信息学技能

概述

Datamol 是一个 Python 库，为分子化学信息学提供轻量、符合 Python 风格的 RDKit 抽象层。借助合理的默认设置、高效的并行处理和现代化的 I/O 功能，简化复杂的分子操作。所有分子对象都是原生的 rdkit.Chem.Mol 实例，确保与 RDKit 生态系统完全兼容。

主要功能：

• 分子格式转换（SMILES、SELFIES、InChI）
• 结构标准化与清理
• 分子描述符和指纹
• 3D 构象生成与分析
• 聚类与多样性选择
• 骨架与片段分析
• 化学反应应用
• 可视化与对齐
• 并行批处理
• 通过 fsspec 支持云存储

何时使用此技能

当用户希望执行以下操作时，使用此技能：

• 加载、标准化并去重分子表格（CSV/SDF/Excel/Parquet，本地或云端），且尽量减少样板代码
• 计算化合物集的 datamol 描述符集合、指纹和 Tanimoto 距离矩阵
• 对化合物库进行聚类、挑选多样化子集、提取 Murcko 骨架，或进行片段化（BRICS/RECAP）
• 生成并聚类 3D 构象，或渲染对齐的分子网格以供 SAR 审查

不适用的情况

场景	改用
低级控制：自定义清理标志、原子映射反应详情、专用指纹/描述符算法	alterlab-rdkit
面向 ML 的特征矩阵、预训练嵌入或特征化器基准测试	alterlab-molfeat
药物相似性规则集、PAINS / 结构警示及复杂性筛选	alterlab-medchem
下载经过整理、带有骨架或冷启动划分的 ADMET/DTI 基准数据集	alterlab-pytdc

安装与设置

指导用户安装 datamol：

uv pip install datamol

此处的示例已通过 datamol 0.13.0 验证（截至 2026-09 为当前版本；需要 Python ≥ 3.11，且会安装 RDKit）。0.13 修正了拼写错误的杂环描述符：compute_many_descriptors 的键现在为 n_aromatic_heterocycles / n_aliphatic_heterocycles / n_saturated_heterocycles（之前为 ..._heterocyles；旧函数名仅作为已弃用别名保留）。如果依赖这些键，请固定 'datamol>=0.13'。

导入约定：

import datamol as dm

核心工作流

以下各小节展示了主要调用模式。完整的 API 签名、参数和其他示例见各小节所引模块参考文件；完整的多步骤流水线见 references/workflow_recipes.md。

1. 基本分子处理

import datamol as dm

# Parse SMILES (returns None on failure)
mol = dm.to_mol("CCO")                        # Ethanol
mols = [dm.to_mol(smi) for smi in ["CCO", "c1ccccc1", "CC(=O)O"]]
if dm.to_mol("invalid_smiles") is None:
    print("Failed to parse SMILES")

# Export to common formats (canonical + isomeric by default)
smiles   = dm.to_smiles(mol)                  # keeps stereochemistry
flat     = dm.to_smiles(mol, isomeric=False)  # drops stereochemistry
inchi    = dm.to_inchi(mol)
inchikey = dm.to_inchikey(mol)
selfies  = dm.to_selfies(mol)

# Standardize user-provided molecules (recommended for datasets)
mol = dm.sanitize_mol(mol)
mol = dm.standardize_mol(mol, disconnect_metals=True, normalize=True, reionize=True)
clean_smiles = dm.standardize_smiles(smiles)

完整的转换、清理和标准化 API：参见 references/core_api.md。

2. 分子文件读写

# Read (open_df auto-detects .sdf/.csv/.xlsx/.parquet/.json)
mols = dm.read_sdf("compounds.sdf")                              # default: list of Mols
df = dm.read_sdf("compounds.sdf", as_df=True, mol_column="mol")  # DataFrame instead
df = dm.read_csv("data.csv", smiles_column="SMILES", mol_column="mol")
df = dm.open_df("file.sdf")

# Write
dm.to_sdf(mols, "output.sdf")               # or dm.to_sdf(df, "output.sdf", mol_column="mol")
dm.to_smi(mols, "output.smi")
dm.to_xlsx(df, "output.xlsx", mol_column="mol")   # renders molecule images in cells

# Remote paths work everywhere via fsspec (S3, GCS, HTTP)
mols = dm.read_sdf("s3://bucket/compounds.sdf")
dm.to_sdf(mols, "s3://bucket/output.sdf")

完整的读写器签名（read_smi、read_excel、read_mol2file、read_pdbfile、save_df、共享参数）：参见 references/io_module.md。

3. 分子描述符与属性

# Single molecule -> ~22 keys. Note datamol's naming (NOT rdkit's):
desc = dm.descriptors.compute_many_descriptors(mol)
#   {'mw': 46.04, 'clogp': -0.0, 'n_lipinski_hbd': 1, 'n_lipinski_hba': 1,
#    'tpsa': 20.23, 'n_rotatable_bonds': 0, 'qed': ..., 'fsp3': ..., 'sas': ..., ...}
# Gotcha: logP is 'clogp'; donors/acceptors are 'n_lipinski_hbd'/'n_lipinski_hba'.
# There is no 'logp', 'hbd', 'hba', or 'n_aromatic_atoms' key in this dict.

# Batch (parallel) -> DataFrame with the same keys. Pass an explicit batch_size
# when n_jobs != 1: the default batch_size=None is rejected by joblib >= 1.6
# ("batch_size must be 'auto' or a positive integer").
desc_df = dm.descriptors.batch_compute_many_descriptors(mols, n_jobs=-1, batch_size=256,
                                                        progress=True)

# Standalone descriptors not in the dict above
dm.descriptors.n_aromatic_atoms(mol)
dm.descriptors.n_stereo_centers(mol)
dm.descriptors.n_rigid_bonds(mol)

# Drug-likeness filter (Lipinski's Rule of Five) with datamol's exact key names
def is_druglike(mol):
    d = dm.descriptors.compute_many_descriptors(mol)
    return (d['mw'] <= 500 and d['clogp'] <= 5 and
            d['n_lipinski_hbd'] <= 5 and d['n_lipinski_hba'] <= 10)

druglike_mols = [m for m in mols if is_druglike(m)]

完整的描述符目录、RDKit 描述符访问方式和 ADME 示例：参见 references/descriptors_viz.md。

4. 分子指纹与相似度

# Fingerprints (ECFP/Morgan is the default; datamol's ecfp default is radius=3, i.e. ECFP6)
# Extra kwargs go straight to RDKit's rdFingerprintGenerator: use fpSize, not n_bits/nBits.
fp       = dm.to_fp(mol, fp_type='ecfp', radius=2, fpSize=2048)
fp_maccs = dm.to_fp(mol, fp_type='maccs')
# Also available: 'topological', 'atompair', 'fcfp', 'rdkit', '*-count' variants
# (full list: dm.list_supported_fingerprints())

# Similarity as Tanimoto distance (distance = 1 - similarity; lower = more similar)
dist_matrix = dm.pdist(mols, n_jobs=-1)          # square N x N matrix (squareform=True default)
condensed   = dm.pdist(mols, squareform=False)   # condensed vector, SciPy-style
distances   = dm.cdist(query_mols, library_mols, n_jobs=-1)  # between two sets

指纹类型以及 pdist / cdist 详情：参见 references/core_api.md。

5. 聚类与多样性选择

# Butina clustering (cutoff = Tanimoto distance). Returns a TUPLE:
# (cluster_indices, cluster_mols) — one tuple of indices / list of Mols per cluster.
cluster_idx, cluster_mols = dm.cluster_mols(mols, cutoff=0.2, n_jobs=-1)
for i, members in enumerate(cluster_idx):
    print(i, len(members))

# Diversity / representative selection — both return (indices, mols)
diverse_idx, diverse = dm.pick_diverse(mols, npick=100)
centroid_idx, centroids = dm.pick_centroids(mols, npick=50)

规模提示：Butina 会构建完整的距离矩阵——处理约 1,000 个分子没问题，但不适用于 10,000 个以上。聚类参数：参见 references/core_api.md。

6. 骨架分析

# Bemis-Murcko scaffold (core ring systems + linkers)
scaffold = dm.to_scaffold_murcko(mol)
scaffold_smiles = dm.to_smiles(scaffold)

骨架频次统计、骨架到分子的分组，以及用于 ML 的基于骨架的训练/测试集划分：参见 references/workflow_recipes.md。关于 fuzzy_scaffolding 等内容：参见 references/fragments_scaffolds.md。

7. 分子片段化

# BRICS (16 bond types) and RECAP (11 bond types) return lists of RDKit Mol
# fragments, parent molecule first unless remove_parent=True. The default
# fix=True caps the dummy atoms; pass fix=False to keep attachment points
# such as '[1*]C(C)=O' in the SMILES.
frags_brics = dm.fragment.brics(mol, remove_parent=True, fix=False)
frag_smiles = {dm.to_smiles(f) for f in frags_brics}
frags_recap = dm.fragment.recap(mol, remove_parent=True)

跨化合物库的片段频次分析和片段重叠评分方案：参见 references/workflow_recipes.md。MMPA 片段化和方法对比表：参见 references/fragments_scaffolds.md。

8. 3D 构象生成

# Generate 3D conformers (ETKDGv3 is the default method; minimize_energy defaults
# to False — pass True for UFF minimization)
mol_3d = dm.conformers.generate(mol, n_confs=50, rms_cutoff=0.5,
                                minimize_energy=True, method='ETKDGv3')
mol_3d.GetNumConformers()
conf = mol_3d.GetConformer(0)
positions = conf.GetPositions()          # Nx3 array of atom coordinates

# Cluster conformers by RMSD (Butina on symmetry-aware pairwise RMS)
centroid_mol = dm.conformers.cluster(mol_3d, rms_cutoff=1.0)       # one Mol holding the centroid conformers
per_cluster  = dm.conformers.cluster(mol_3d, rms_cutoff=1.0, centroids=False)  # list of Mols, one per cluster

# Solvent accessible surface area
sasa_values = dm.conformers.sasa(mol_3d, n_jobs=-1)
sasa = mol_3d.GetConformer(0).GetDoubleProp('rdkit_free_sasa')

嵌入方法、RMSD 矩阵和底层坐标操作：请参阅 references/conformers_module.md。

9. 可视化

# Grid image (SVG by default: use_svg=True). For a PNG file pass use_svg=False —
# otherwise SVG markup is written into the .png file.
dm.viz.to_image(mols[:20], legends=[dm.to_smiles(m) for m in mols[:20]],
                n_cols=5, mol_size=(300, 300))
dm.viz.to_image(mols, outfile="molecules.png", use_svg=False)
dm.viz.to_image(mols, outfile="molecules.svg")

# Align by MCS for SAR series; highlight atoms/bonds; render conformers
dm.viz.to_image(similar_mols, align=True, legends=activity_labels, n_cols=4)
dm.viz.to_image(mol, highlight_atom=[0, 1, 2, 3], highlight_bond=[0, 1, 2])
dm.viz.conformers(mol_3d, n_confs=10, align_conf=True, n_cols=3)

完整的 to_image / conformers / circle_grid 参数和最佳实践：请参阅 references/descriptors_viz.md。

10. 化学反应

from rdkit.Chem import rdChemReactions

# Build a reaction from SMARTS, then apply it to a reactant tuple. By default
# apply_reaction returns every product set (list of lists); ask for one Mol:
rxn = rdChemReactions.ReactionFromSmarts('[C:1](=[O:2])[OH:3]>>[C:1](=[O:2])[Cl:3]')
product = dm.reactions.apply_reaction(rxn, (dm.to_mol("CC(=O)O"),),
                                      single_product_group=True, product_index=0,
                                      sanitize=True)
product_smiles = dm.to_smiles(product)   # 'CC(=O)Cl' (or pass as_smiles=True)

批量应用反应、常见反应模板（酰胺化、Suzuki、酯化）和玩具数据集 datamol.data：请参阅 references/reactions_data.md。

并行化

Datamol 为许多操作提供了内置并行化功能。使用 n_jobs 参数：

• n_jobs=1：顺序执行（不并行）
• n_jobs=-1：使用所有可用 CPU 核心
• n_jobs=4：使用 4 个核心

支持并行化的函数：

• dm.read_sdf(..., n_jobs=-1)
• dm.descriptors.batch_compute_many_descriptors(..., n_jobs=-1, batch_size=256)（joblib ≥ 1.6 时需要显式指定 batch_size）
• dm.cluster_mols(..., n_jobs=-1)
• dm.pdist(..., n_jobs=-1)
• dm.conformers.sasa(..., n_jobs=-1)

进度条：许多批量操作支持 progress=True 参数。

常见工作流和模式

完整且可直接复制的示例流程——数据加载 → 筛选 → 分析、构效关系（SAR）分析和虚拟筛选——以及机器学习特征生成和健壮的错误处理封装，已从此文件移出，以保持文件精简。请参阅 references/workflow_recipes.md。

参考文档

如需详细的 API 文档，请查阅以下参考文件：

• references/core_api.md：核心命名空间函数（转换、标准化、指纹、聚类）
• references/io_module.md：文件输入/输出操作（读取/写入 SDF、CSV、Excel、远程文件）
• references/conformers_module.md：3D 构象生成、聚类、SASA 计算
• references/descriptors_viz.md：分子描述符和可视化函数
• references/fragments_scaffolds.md：骨架提取、BRICS/RECAP 片段化
• references/reactions_data.md：化学反应和玩具数据集
• references/workflow_recipes.md：端到端流程、SAR/筛选配方、ML 集成、错误处理

最佳实践

1. 始终标准化来自外部来源的分子：

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

2. 解析分子后检查 None 值：

   mol = dm.to_mol(smiles)
   if mol is None:
       ...  # log and skip the invalid SMILES
   

3. 对大型数据集使用并行处理：

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

4. 利用 fsspec 访问云存储：

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

5. 根据相似性需求选择合适的指纹：

   • ECFP（Morgan）：通用，适用于结构相似性
   • MACCS：速度快，特征空间较小
   • 原子对：考虑原子对及其距离

6. 考虑规模限制：

   • Butina 聚类：约 1,000 个分子（完整距离矩阵）
   • 对于更大的数据集：使用多样性选择或层次方法

7. 用于 ML 的骨架划分：确保按骨架正确划分训练集和测试集

8. 可视化 SAR 系列时对齐分子

故障排除

问题：分子解析失败

• 解决方案：先使用 dm.standardize_smiles()，或尝试 dm.fix_mol()

问题：聚类时出现内存错误

• 解决方案：对大型集合使用 dm.pick_diverse()，而不是完整聚类

问题：构象生成缓慢

• 解决方案：减少 n_confs，或增大 rms_cutoff 以生成更少的构象

问题：远程文件访问失败

• 解决方案：确保已安装 fsspec 和相应的云服务提供商库（s3fs、gcsfs 等）

其他资源

• Datamol 文档：https://docs.datamol.io/
• RDKit 文档：https://www.rdkit.org/docs/
• GitHub 仓库：https://github.com/datamol-io/datamol

AlterLab Academic Skills 套件的一部分。