datamol

概述

datamol 是一个 Python 库，在 RDKit 之上提供一个轻量、Pythonic 的抽象层，用于分子化学信息学。它通过合理的默认值、高效的并行化和现代 I/O 能力简化复杂的分子操作。所有分子对象都是原生 rdkit.Chem.Mol 实例，确保与 RDKit 生态完全兼容。

已验证目标版本为 datamol 0.13.0（发布日期 2026 年 9 月 9 日）。本地检查使用 Python 3.13 与 RDKit 2026.03.6。最低要求为 Python 3.11+ 和 RDKit 2024.09+。0.13 发行版包含 SELFIES、可视化、云、Excel 和 Parquet 运行时依赖。当前 API 示例与验证限制记录在 references/review.md 中。建议固定环境：RDKit 升级可能改变规范表示和保留的构象。应比较化学不变量，而不是固定的构象数量或依赖精确版本的规范字符串。

主要能力

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

安装与设置

指导用户安装 datamol：

uv pip install "datamol==0.13.0"

RDKit 以及 S3/GCS、Excel/Parquet、可视化和 SELFIES 依赖由当前发行版一并安装，无需单独的功能 extras。建议使用隔离环境，避免与科学计算包产生依赖冲突。

导入约定：

import datamol as dm

核心工作流

references/core_workflows.md 记录了十个工作流领域，每个都附有可运行代码：

基础分子处理：to_mol、批量转换、错误处理、规范与非异构 SMILES、sanitization 与完整标准化
文件读写：SDF、SMILES、带渲染结构的 CSV/Excel、通用读写器，以及云或 HTTPS 路径
描述符与属性：标准描述符集、并行计算、芳香性、立体化学、柔性与过滤
指纹与相似性：ECFP4 及其他类型、成对与跨集合距离、最近邻查找（Tanimoto 距离 = 1 − 相似度）
聚类与多样性：相似性聚类、多样性子集挑选、聚类质心
骨架分析：Bemis-Murcko 骨架、分组与计数、按骨架不重叠的训练/测试集划分
片段化：分子片段化、在库中查找共有片段、基于片段的打分
3D 构象：生成、访问、RMSD 聚类、代表性选择与 SASA
可视化：网格、文件、出版级 SVG、子结构对齐、原子与键高亮、构象显示
化学反应：反应 SMARTS、作用于单个分子或整个库

references/workflow_patterns.md 中提供三条端到端流程：加载/过滤/分析、按骨架系列做 SAR、虚拟筛选。

并行化

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=128) dm.cluster_mols(..., n_jobs=-1) dm.pdist(..., n_jobs=-1) dm.conformers.sasa(..., n_jobs=-1)

进度条：许多批处理操作支持 progress=True 参数。并行描述符批次应提供正的 batch_size（例如 128）。在测试的 0.13.0 技术栈中，默认值 None 会传到 joblib，并在启用并行时抛出错误。

参考文档

详细 API 文档请查阅以下参考文件：

references/core_api.md：核心命名空间函数（转换、标准化、指纹、聚类）
references/io_module.md：文件 I/O 操作（读写 SDF、CSV、Excel、远程文件）
references/conformers_module.md：3D 构象生成、聚类、SASA 计算
references/descriptors_viz.md：分子描述符与可视化函数
references/fragments_scaffolds.md：骨架提取、BRICS/RECAP 片段化
references/reactions_data.md：化学反应与玩具数据集

最佳实践

为外部分子选择并记录任务特定的标准化策略。保留原始结构与 ID，并与转换后的版本一起保存；金属断开、中和、去盐和立体化学变化都可能改变被测实体。不要对有机金属或制剂任务自动应用这些转换。以下是一个示例策略，适用于金属断开为预期操作的输入：

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

在分子解析后检查 None 值：

mol = dm.to_mol(smiles) if mol is None: raise ValueError("Invalid SMILES; retain the source row in the rejection log")

大数据集使用并行处理：

result = dm.parallelized(dm.to_mol, smiles_list, n_jobs=-1, progress=True)

对请求的远程路径使用选定提供商凭据进行云 I/O：

df = dm.read_sdf("s3://bucket/compounds.sdf", as_df=True, mol_column="mol")

为相似性选择合适的指纹：

ECFP (Morgan)：通用，结构相似性
MACCS：快速，特征空间较小
Atom pairs：考虑原子对与距离

考虑规模限制：

Butina 聚类存储 O(N²) 成对距离；应根据内存预算选择规模上限。
对更大数据集：使用带有限 npick 的 pick_diverse；层次聚类也可能需要二次方内存。
用于 ML 的骨架划分：确保按骨架正确分离训练/测试集
可视化 SAR 系列时对齐分子

错误处理

示例输入策略：提供 smiles_list，并将源 ID 和失败项与被接受的分子一起保留。标准化是任务特定的，并非修复保证。

安全创建分子：

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

安全批处理：

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

与机器学习集成

示例模型模板：提供对齐的 train_mols、y_target 和留出的 test_mols。在拟合任何学习式预处理之前，按任务合适的骨架/分组划分化合物。

Datamol 依赖 scipy 和 scikit-learn。像普通 PyPI 包一样导入它们——它们不是本技能捆绑的脚本。

import numpy as np

训练与留出分子使用相同的指纹模式。

fp_options = dict(fp_type="ecfp", radius=2, fpSize=2048, includeChirality=True) X = np.stack([dm.to_fp(mol, **fp_options) for mol in train_mols]) X_test = np.stack([dm.to_fp(mol, **fp_options) for mol in test_mols])

训练模型（scikit-learn PyPI 包）

from sklearn.ensemble import RandomForestRegressor # 第三方库 model = RandomForestRegressor(random_state=42) model.fit(X, y_target)

预测

predictions = model.predict(X_test)

故障排除

问题：分子解析失败解决：保留失败的源记录，首先诊断语法/价态问题。标准化不保证修复无效化学；检查任何 fix_mol() 结果并记录转换，然后再将其视为原始化合物。

问题：聚类时内存错误解决：对大数据集使用 dm.pick_diverse() 替代完整聚类

问题：构象生成缓慢解决：减少 n_confs 以降低嵌入工作量。RMS 剪枝发生在嵌入/最小化之后，因此更大的 rms_cutoff 可减少保留的构象，但不能避免初始工作。

问题：远程文件访问失败解决：验证所选 fsspec 协议和提供商凭据。0.13.0 已包含 S3/GCS 依赖；其他后端可能需要安装。此处未测试远程授权与写入。

附加资源

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