datamol

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

版本说明：示例针对 datamol 0.12.x（PyPI 稳定版 0.12.5，2024 年 6 月）。自 0.10.0 起，模块默认惰性加载（可设置 DATAMOL_DISABLE_LAZY_LOADING=1 禁用）。自 0.12.2 起，RDKit 成为 datamol 的直接 PyPI 依赖。指纹使用 RDKit 的 rdFingerprintGenerator API（0.12.5+）。

主要能力：

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

安装与设置： 安装 datamol： uv pip install datamol RDKit 会随 datamol 自动安装。对于远程文件路径（S3、GCS、HTTP），安装匹配的 fsspec 后端： uv pip install s3fs # AWS S3 uv pip install gcsfs # Google Cloud Storage 导入约定： import datamol as dm

核心工作流： references/core_workflows.md 记录了十个工作流领域，每个都有示例代码：

1. 基础分子处理：to_mol、批量转换、错误处理、规范与非异构 SMILES、净化与完整标准化
2. 文件读写：SDF、SMILES、CSV、带渲染结构的 Excel、通用读写器，以及云或 HTTPS 路径
3. 描述符与属性：标准描述符集、并行计算、芳香性、立体化学、柔性及过滤
4. 指纹与相似性：ECFP4 及其他类型、成对与跨集距离、最近邻查找（Tanimoto 距离 = 1 − 相似度）
5. 聚类与多样性：相似性聚类、多样性子集挑选、聚类中心
6. 骨架分析：Bemis-Murcko 骨架、分组与计数、骨架不相交的训练/测试划分
7. 片段化：分子片段化、在库中查找常见片段、基于片段的评分
8. 3D 构象：生成、访问、RMSD 聚类、代表选择、SASA
9. 可视化：网格、文件、出版级 SVG、子结构对齐、原子与键高亮、构象显示
10. 化学反应：反应 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) dm.cluster_mols(..., n_jobs=-1) dm.pdist(..., n_jobs=-1) dm.conformers.sasa(..., n_jobs=-1) 进度条：许多批量操作支持 progress=True 参数。

参考文档： 详细 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：化学反应与玩具数据集

最佳实践： 始终标准化来自外部来源的分子： mol = dm.standardize_mol(mol, disconnect_metals=True, normalize=True, reionize=True) 分子解析后检查 None 值： mol = dm.to_mol(smiles) if mol is None: # 处理无效 SMILES 对大型数据集使用并行处理： result = dm.operation(..., n_jobs=-1, progress=True) 仅在需要时使用云 I/O——确认远程写入路径；按需安装 s3fs/gcsfs： df = dm.read_sdf("s3://bucket/compounds.sdf") 为相似性使用合适的指纹： ECFP（Morgan）：通用，结构相似性 MACCS：快速，特征空间较小 Atom pairs：考虑原子对与距离 考虑规模限制： Butina 聚类：约 1,000 个分子（完整距离矩阵） 对于更大数据集：使用多样性选择或层次方法 用于 ML 的骨架划分：确保按骨架正确分离训练/测试 可视化 SAR 系列时对齐分子

错误处理：

安全创建分子

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)

与机器学习集成： datamol 自带 scipy 和 scikit-learn 作为依赖。像普通 PyPI 包一样导入它们——它们不是本技能捆绑的脚本。 import numpy as np

特征生成

X = np.array([dm.to_fp(mol) for mol in mols])

或描述符

desc_df = dm.descriptors.batch_compute_many_descriptors(mols, n_jobs=-1) X = desc_df.values

训练模型（scikit-learn PyPI 包）

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

预测

predictions = model.predict(X_test)

故障排除： 问题：分子解析失败 解决方案：先使用 dm.standardize_smiles() 或尝试 dm.fix_mol() 问题：聚类时内存错误 解决方案：对大型集合使用 dm.pick_diverse() 而非完整聚类 问题：构象生成缓慢 解决方案：减少 n_confs 或增大 rms_cutoff 以生成更少构象 问题：远程文件访问失败 解决方案：安装匹配的 fsspec 后端（uv pip install s3fs 或 gcsfs），并确认仅设置了该后端所需的提供方凭据（见上文远程文件支持）

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

相关技能： rdkit：指导使用 RDKit（Python）读写 SMILES、MOL/SDF 和 InChI，计算描述符（MW、LogP、TPSA），生成 Morgan/… molfeat：使用 molfeat（0.11.0）将 SMILES 字符串或 RDKit/datamol 分子转换为数值特征，提供计算器、scikit-learn… medchem：使用 Python medchem 库（datamol-io，v2.0.5）在 RDKit 和 datamol 之上过滤和筛选小分子库。