Datamol 核心 API 实战指南分子转换、标准化、指纹与聚类的完整工具箱【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本文基于本仓库中 datamol 技能 的核心 API 参考文档 core_api.md系统梳理 datamol 命名空间下最常用、最高频的函数从 SMILES/InChI/SMILES/SELFIES 的分子创建与导出、结构与标准化、指纹与相似度计算、聚类与多样性筛选到图操作与 DataFrame 集成。读完本文你将掌握用 datamol 一行代码完成 RDKit 中繁琐的分子操作并能直接在本仓库的 core_workflows.md 与 workflow_patterns.md 基础上组合出可运行的药物发现流水线。一、Datamol 是什么Datamol 是一个轻量级、Pythonic 的 RDKit 封装层面向分子信息学cheminformatics场景提供简洁接口与合理默认值。所有分子对象都是原生rdkit.Chem.Mol实例与 RDKit 生态完全兼容。其核心能力覆盖分子格式转换SMILES、SELFIES、InChI、SMARTS结构标准化standardization与消毒sanitization分子描述符与指纹3D 构象生成与分析聚类与多样性筛选骨架scaffold与碎片fragment分析化学反应应用可视化与对齐批处理并行化基于 fsspec 的云存储支持版本说明本仓库示例面向datamol 0.12.xPyPI 稳定版 0.12.52024 年 6 月。自 0.10.0 起模块默认懒加载可用环境变量DATAMOL_DISABLE_LAZY_LOADING1关闭自 0.12.2 起 RDKit 是 datamol 的直接 PyPI 依赖0.12.5 起指纹使用 RDKit 的rdFingerprintGeneratorAPI。以上细节均可在 SKILL.md 中核对。二、安装与导入uv pip install datamolRDKit 会随 datamol 自动安装。若需读取远程路径S3、GCS、HTTP安装对应 fsspec 后端uv pip install s3fs # AWS S3 uv pip install gcsfs # Google Cloud Storage导入约定import datamol as dm三、分子创建与转换Molecule Creation and Conversion3.1to_mol(mol, ...)—— 统一入口将 SMILES 字符串或其他分子表示转换为 RDKit 分子对象。参数接受 SMILES 字符串、InChI 或其他分子格式返回rdkit.Chem.Mol对象解析失败时返回None常见用法mol dm.to_mol(CCO)乙醇import datamol as dm # 单个分子 mol dm.to_mol(CCO) # 乙醇 # 批量转换 smiles_list [CCO, c1ccccc1, CC(O)O] mols [dm.to_mol(smi) for smi in smiles_list] # 错误处理无效 SMILES 返回 None mol dm.to_mol(invalid_smiles) if mol is None: print(Failed to parse SMILES)实践要点to_mol返回None而非抛异常是 datamol 的设计取舍。结合 SKILL.md 中检查 None 值的最佳实践建议所有外部输入的解析都必须判空。3.2 其他格式入口函数说明示例from_inchi(inchi)将 InChI 字符串转换为分子对象dm.from_inchi(InChI1S/C2H6O/c1-2-3/h3H,2H2,1H3)from_smarts(smarts)将 SMARTS 模式转换为分子对象dm.from_smarts(CCO)from_selfies(selfies)将 SELFIES 字符串转换为分子对象dm.from_selfies([C][C][O])copy_mol(mol)复制分子对象避免修改原对象mol_copy dm.copy_mol(mol)实践要点RDKit 中许多操作如加氢、构象生成会就地修改分子对象。copy_mol用于在管道中保留中间体快照是长流程中防止原分子被污染的关键工具。四、分子导出Molecule Export4.1 导出函数总览函数说明常用参数to_smiles(mol, ...)分子 → SMILES 字符串canonicalTrue规范 SMILES、isomericTrue含立体化学to_inchi(mol, ...)分子 → InChI 字符串—to_inchikey(mol)分子 → InChI Key定长哈希—to_smarts(mol)分子 → SMARTS 模式—to_selfies(mol)分子 → SELFIES自引用嵌入字符串—4.2 实战示例# 规范 SMILES推荐用于去重与比较 smiles dm.to_smiles(mol) # 含立体化学的异构 SMILES smiles dm.to_smiles(mol, isomericTrue) # 其他导出格式 inchi dm.to_inchi(mol) inchikey dm.to_inchikey(mol) selfies dm.to_selfies(mol)实践要点to_inchikey生成定长哈希常用于跨数据库匹配如 PubChem、ChEMBL 联查。to_smiles(mol, canonicalTrue)是标准化的第一道关卡能将同一分子的不同写法归一到同一种表示。五、消毒与标准化Sanitization and Standardization这是 datamol 最核心的价值所在也是 SKILL.md 反复强调的外部来源分子必须标准化原则的落点。5.1sanitize_mol(mol, ...)RDKit 消毒操作的增强版实现方式为 mol→SMILES→mol 转换并修正芳香性氮原子问题。目的修复常见的分子结构问题如未正确的芳香环、价态异常返回消毒后的分子失败时返回Nonemol dm.sanitize_mol(mol)5.2standardize_mol(mol, disconnect_metalsFalse, normalizeTrue, reionizeTrue, ...)执行完整的标准化流程包含四类操作金属断键disconnect metalsdisconnect_metalsTrue时切断金属配位键归一化normalize电荷修正如硝基、羧酸盐的共振形式统一再离子化reionizepH 相关的质子化状态校正碎片处理保留最大碎片移除盐与溶剂分子# 全量标准化数据集推荐 mol dm.standardize_mol( mol, disconnect_metalsTrue, normalizeTrue, reionizeTrue )5.3standardize_smiles(smiles, ...)直接对 SMILES 字符串应用标准化流程免去先转分子再转回的往返clean_smiles dm.standardize_smiles(smiles)5.4 自动修复系列函数说明fix_mol(mol)自动尝试修复分子结构问题fix_valence(mol)修正分子结构中的价态错误fix_valence_charge(mol, inplaceFalse)价态错误的电荷感知变体inplaceFalse时不修改原对象5.5hash_mol(mol, hash_schemeall)生成化学感知的哈希值用于去重要求 RDKit ≥ 2022.09。hash_scheme取值all默认综合所有特征no_stereo忽略立体化学差异no_tautomers忽略互变异构差异实践要点当同一个分子以多种 SMILES 形式出现在数据集中时普通字符串哈希无法识别重复而hash_mol能从化学层面识别同一实体或同一非立体实体 / 同一非互变异构实体是数据清洗去重环节的首选工具。六、分子性质操作Molecular Properties6.1reorder_atoms(mol, ...)确保同一分子在不同 SMILES 表示下具有一致的原子排序。目的保证特征生成的可复现性。同一分子CCO与OCC原子编号可能不同导致指纹或描述符向量错位重排后输出稳定一致的原子索引。6.2 氢原子管理函数说明remove_hs(mol, ...)移除分子中的氢原子默认行为I/O 读取时常用add_hs(mol, ...)添加显式氢原子3D 构象生成前必须执行见 conformers_module.md实践要点RDKit 默认处理隐式氢。文件读取如 SDF后显式氢会造成分子比较与指纹计算的干扰故 I/O 层默认remove_hsTrue而 3D 嵌入embedding则需要显式氢才能得到准确几何构象模块默认add_hsTrue。这一对对称操作的取舍贯穿整个 datamol 设计。七、指纹与相似度Fingerprints and Similarity7.1to_fp(mol, fp_typeecfp, ...)生成分子指纹用于相似度计算。指纹类型fp_type说明ecfp/fcfpMorgan 指纹默认 radius 3 即 ECFP6传radius2得到 ECFP4maccsMACCS 键指纹166 位topological拓扑指纹atompair原子对指纹考虑原子对及其距离rdkitRDKit 拓扑指纹计数变体ecfp-count、fcfp-count、atompair-count等保留计数信息的稠密向量实现细节datamol ≥ 0.12.5 使用 RDKitrdFingerprintGeneratorAPISKILL.md 版本说明。常用参数n_bits默认 2048、radius。返回Numpy 数组或 RDKit 指纹对象。# ECFP4相似性筛选中常用 fp dm.to_fp(mol, fp_typeecfp, radius2, n_bits2048) # 其他指纹类型 fp_maccs dm.to_fp(mol, fp_typemaccs) fp_topological dm.to_fp(mol, fp_typetopological) fp_atompair dm.to_fp(mol, fp_typeatompair) fp_rdkit dm.to_fp(mol, fp_typerdkit)选型建议源自 SKILL.md 最佳实践ECFPMorgan通用目的捕捉结构相似性MACCS速度快、特征空间小原子对Atom pairs考虑原子对与距离适合关注分子大小与连接性的场景7.2 距离计算函数说明pdist(mols, ...)计算列表内所有分子两两之间的 Tanimoto 距离cdist(mols1, mols2, ...)计算两组分子之间的 Tanimoto 距离两者均支持n_jobs并行。# 组内两两距离 distance_matrix dm.pdist(mols, n_jobs-1) # 两组之间距离查询集 vs 库 distances dm.cdist(query_mols, library_mols, n_jobs-1)实践要点Tanimoto 距离 1 − Tanimoto 相似度core_workflows.md 明确给出该换算关系。在虚拟筛选中距离最小即相似度最高# 找到与查询集最接近的库分子完整流程见 workflow_patterns.md min_distances distances.min(axis0) similarities 1 - min_distances八、聚类与多样性Clustering and Diversity8.1cluster_mols(mols, cutoff0.2, feature_fnNone, n_jobs1)使用Butina 算法进行相似性聚类。cutoffTanimoto 距离阈值默认 0.20完全相同1完全不同feature_fn自定义分子特征函数n_jobs并行化-1 使用全部 CPU 核心返回聚类列表每个聚类是分子索引的列表clusters dm.cluster_mols( mols, cutoff0.2, n_jobs-1 ) for i, cluster in enumerate(clusters): print(fCluster {i}: {len(cluster)} molecules) cluster_mols [mols[idx] for idx in cluster]重要规模限制Butina 聚类需构建完整距离矩阵适合约1000 个分子不适合 10,000 规模。core_api.md 与 SKILL.md 均明确提示此限制。8.2pick_diverse(mols, npick, ...)基于指纹多样性挑选分子的多样子集无需全距离矩阵适合大库的快速抽稀。diverse_mols dm.pick_diverse(mols, npick100)8.3pick_centroids(mols, npick, ...)挑选代表聚类的质心分子适合生成代表性子集如后续 SAR 可视化。centroids dm.pick_centroids(mols, npick50)实践要点当数据集规模超过 Butina 聚类上限时SKILL.md 故障排查章节建议改用pick_diverse替代全量聚类若仍需层次化结果可先聚类再取质心。九、图操作Graph Operations函数说明to_graph(mol)将分子转换为图表示用于基于图的分析如网络分析、图神经网络特征get_all_path_between(mol, start, end)查找分子结构中两个原子之间的所有路径graph dm.to_graph(mol) # 分子 → 图 # 查找原子索引 0 到 5 之间的所有路径 paths dm.get_all_path_between(mol, 0, 5)实践要点get_all_path_between常用于构效关系分析中双原子间距统计、环系遍历与片段关联研究与 fragments_scaffolds.md 中 BRICS/RECAP 碎片分析可形成互补。十、DataFrame 集成DataFrame Integration10.1 双向转换函数签名说明to_df(mols, smiles_columnsmiles, mol_columnmol)分子列表 → pandas DataFrame自动生成 SMILES 列与分子列from_df(df, smiles_columnsmiles, mol_columnmol)DataFrame → 分子列表从指定分子列提取# 分子列表 → DataFrame df dm.to_df(mols) # DataFrame → 分子列表 mols dm.from_df(df, mol_columnmol)10.2 与文件 I/O 衔接DataFrame 是 datamol 与 pandas 生态的桥梁。文件读写层io_module.md大量返回/接受 DataFrame# 读取 SDF → DataFrame含分子列 mol df dm.read_sdf(compounds.sdf, mol_columnmol) # CSV 自动将 SMILES 列转为分子列 df dm.read_csv(data.csv, smiles_columnSMILES, mol_columnmol) # 通用读写器自动探测格式支持压缩 df dm.open_df(file.sdf) # .sdf/.csv/.xlsx/.parquet/.json/.gz 等 dm.save_df(df, output.parquet) # Excel 导出时自动渲染分子图像 dm.to_xlsx(df, output.xlsx, mol_columns[mol])十一、并行化与性能源自 SKILL.mddatamol 内置大量操作的并行化统一使用n_jobs参数n_jobs1串行不并行n_jobs-1使用全部可用 CPU 核心n_jobs4使用 4 个核心支持并行的代表性函数见 SKILL.mddm.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)许多批量操作还支持progressTrue显示进度条result dm.operation(..., n_jobs-1, progressTrue)十二、完整实战从加载到分析的一条龙流水线综合 workflow_patterns.md 的端到端模式将本文核心 API 串联为可运行流水线import datamol as dm import pandas as pd # 1. 加载分子I/O 层自动消毒、去氢 df dm.read_sdf(compounds.sdf) # 2. 标准化核心 API 环节外部数据必做 df[mol] df[mol].apply(lambda m: dm.standardize_mol(m) if m else None) df df[df[mol].notna()] # 剔除解析失败的分子 # 3. 批量描述符并行计算 desc_df dm.descriptors.batch_compute_many_descriptors( df[mol].tolist(), n_jobs-1, progressTrue ) # 4. 类药性过滤Lipinski 五规则 druglike ( (desc_df[mw] 500) (desc_df[logp] 5) (desc_df[hbd] 5) (desc_df[hba] 10) ) filtered_df df[druglike] # 5. 多样性挑选避开全距离矩阵的规模限制 diverse_mols dm.pick_diverse(filtered_df[mol].tolist(), npick100) # 6. 指纹特征化 机器学习scipy/scikit-learn 为 datamol 依赖 import numpy as np X np.array([dm.to_fp(mol) for mol in diverse_mols]) # 7. 可视化结果 dm.viz.to_image( diverse_mols, legends[dm.to_smiles(m) for m in diverse_mols], outfilediverse_compounds.png, n_cols10 )说明datamol 自带scipy与scikit-learn依赖可直接以正常 PyPI 包导入SKILL.md 明确它们不是本技能捆绑脚本。十三、错误处理与故障排查13.1 安全的分子创建模式SKILL.mddef 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(fFailed to process {smiles}: {e}) return None13.2 常见问题速查问题解决方案分子解析失败先dm.standardize_smiles()或尝试dm.fix_mol()聚类内存错误大集合改用dm.pick_diverse()而非全量聚类构象生成缓慢减少n_confs或增大rms_cutoff详见 conformers_module.md远程文件访问失败安装匹配的 fsspec 后端uv pip install s3fs/gcsfs并仅设置该后端所需凭证十四、参考文档导航本仓库的 datamol 技能共包含 8 份参考文档与本文核心 API配套使用core_api.md核心命名空间函数本文主体来源core_workflows.md十大工作流的完整可运行代码io_module.md文件读写SDF/CSV/Excel/远程文件conformers_module.md3D 构象生成、聚类、SASAdescriptors_viz.md描述符与可视化fragments_scaffolds.md骨架提取、BRICS/RECAP 碎片reactions_data.md化学反应与玩具数据集workflow_patterns.md三条端到端流水线加载-过滤-分析、SAR 分析、虚拟筛选最佳实践总结源自 SKILL.md外部来源分子一律标准化dm.standardize_mol(mol, disconnect_metalsTrue, normalizeTrue, reionizeTrue)解析后检查 None大数据集使用n_jobs-1并行 progressTrue云 I/O 仅在用户明确要求时使用写入远程路径前先确认按场景选择指纹ECFP/MACCS/原子对注意规模限制Butina 聚类约 1000 分子以内ML 任务按骨架划分 train/test防数据泄漏见 fragments_scaffolds.mdSAR 系列可视化时开启对齐alignTrue【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Datamol 核心 API 实战指南：分子转换、标准化、指纹与聚类的完整工具箱
Datamol 核心 API 实战指南分子转换、标准化、指纹与聚类的完整工具箱【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本文基于本仓库中 datamol 技能 的核心 API 参考文档 core_api.md系统梳理 datamol 命名空间下最常用、最高频的函数从 SMILES/InChI/SMILES/SELFIES 的分子创建与导出、结构与标准化、指纹与相似度计算、聚类与多样性筛选到图操作与 DataFrame 集成。读完本文你将掌握用 datamol 一行代码完成 RDKit 中繁琐的分子操作并能直接在本仓库的 core_workflows.md 与 workflow_patterns.md 基础上组合出可运行的药物发现流水线。一、Datamol 是什么Datamol 是一个轻量级、Pythonic 的 RDKit 封装层面向分子信息学cheminformatics场景提供简洁接口与合理默认值。所有分子对象都是原生rdkit.Chem.Mol实例与 RDKit 生态完全兼容。其核心能力覆盖分子格式转换SMILES、SELFIES、InChI、SMARTS结构标准化standardization与消毒sanitization分子描述符与指纹3D 构象生成与分析聚类与多样性筛选骨架scaffold与碎片fragment分析化学反应应用可视化与对齐批处理并行化基于 fsspec 的云存储支持版本说明本仓库示例面向datamol 0.12.xPyPI 稳定版 0.12.52024 年 6 月。自 0.10.0 起模块默认懒加载可用环境变量DATAMOL_DISABLE_LAZY_LOADING1关闭自 0.12.2 起 RDKit 是 datamol 的直接 PyPI 依赖0.12.5 起指纹使用 RDKit 的rdFingerprintGeneratorAPI。以上细节均可在 SKILL.md 中核对。二、安装与导入uv pip install datamolRDKit 会随 datamol 自动安装。若需读取远程路径S3、GCS、HTTP安装对应 fsspec 后端uv pip install s3fs # AWS S3 uv pip install gcsfs # Google Cloud Storage导入约定import datamol as dm三、分子创建与转换Molecule Creation and Conversion3.1to_mol(mol, ...)—— 统一入口将 SMILES 字符串或其他分子表示转换为 RDKit 分子对象。参数接受 SMILES 字符串、InChI 或其他分子格式返回rdkit.Chem.Mol对象解析失败时返回None常见用法mol dm.to_mol(CCO)乙醇import datamol as dm # 单个分子 mol dm.to_mol(CCO) # 乙醇 # 批量转换 smiles_list [CCO, c1ccccc1, CC(O)O] mols [dm.to_mol(smi) for smi in smiles_list] # 错误处理无效 SMILES 返回 None mol dm.to_mol(invalid_smiles) if mol is None: print(Failed to parse SMILES)实践要点to_mol返回None而非抛异常是 datamol 的设计取舍。结合 SKILL.md 中检查 None 值的最佳实践建议所有外部输入的解析都必须判空。3.2 其他格式入口函数说明示例from_inchi(inchi)将 InChI 字符串转换为分子对象dm.from_inchi(InChI1S/C2H6O/c1-2-3/h3H,2H2,1H3)from_smarts(smarts)将 SMARTS 模式转换为分子对象dm.from_smarts(CCO)from_selfies(selfies)将 SELFIES 字符串转换为分子对象dm.from_selfies([C][C][O])copy_mol(mol)复制分子对象避免修改原对象mol_copy dm.copy_mol(mol)实践要点RDKit 中许多操作如加氢、构象生成会就地修改分子对象。copy_mol用于在管道中保留中间体快照是长流程中防止原分子被污染的关键工具。四、分子导出Molecule Export4.1 导出函数总览函数说明常用参数to_smiles(mol, ...)分子 → SMILES 字符串canonicalTrue规范 SMILES、isomericTrue含立体化学to_inchi(mol, ...)分子 → InChI 字符串—to_inchikey(mol)分子 → InChI Key定长哈希—to_smarts(mol)分子 → SMARTS 模式—to_selfies(mol)分子 → SELFIES自引用嵌入字符串—4.2 实战示例# 规范 SMILES推荐用于去重与比较 smiles dm.to_smiles(mol) # 含立体化学的异构 SMILES smiles dm.to_smiles(mol, isomericTrue) # 其他导出格式 inchi dm.to_inchi(mol) inchikey dm.to_inchikey(mol) selfies dm.to_selfies(mol)实践要点to_inchikey生成定长哈希常用于跨数据库匹配如 PubChem、ChEMBL 联查。to_smiles(mol, canonicalTrue)是标准化的第一道关卡能将同一分子的不同写法归一到同一种表示。五、消毒与标准化Sanitization and Standardization这是 datamol 最核心的价值所在也是 SKILL.md 反复强调的外部来源分子必须标准化原则的落点。5.1sanitize_mol(mol, ...)RDKit 消毒操作的增强版实现方式为 mol→SMILES→mol 转换并修正芳香性氮原子问题。目的修复常见的分子结构问题如未正确的芳香环、价态异常返回消毒后的分子失败时返回Nonemol dm.sanitize_mol(mol)5.2standardize_mol(mol, disconnect_metalsFalse, normalizeTrue, reionizeTrue, ...)执行完整的标准化流程包含四类操作金属断键disconnect metalsdisconnect_metalsTrue时切断金属配位键归一化normalize电荷修正如硝基、羧酸盐的共振形式统一再离子化reionizepH 相关的质子化状态校正碎片处理保留最大碎片移除盐与溶剂分子# 全量标准化数据集推荐 mol dm.standardize_mol( mol, disconnect_metalsTrue, normalizeTrue, reionizeTrue )5.3standardize_smiles(smiles, ...)直接对 SMILES 字符串应用标准化流程免去先转分子再转回的往返clean_smiles dm.standardize_smiles(smiles)5.4 自动修复系列函数说明fix_mol(mol)自动尝试修复分子结构问题fix_valence(mol)修正分子结构中的价态错误fix_valence_charge(mol, inplaceFalse)价态错误的电荷感知变体inplaceFalse时不修改原对象5.5hash_mol(mol, hash_schemeall)生成化学感知的哈希值用于去重要求 RDKit ≥ 2022.09。hash_scheme取值all默认综合所有特征no_stereo忽略立体化学差异no_tautomers忽略互变异构差异实践要点当同一个分子以多种 SMILES 形式出现在数据集中时普通字符串哈希无法识别重复而hash_mol能从化学层面识别同一实体或同一非立体实体 / 同一非互变异构实体是数据清洗去重环节的首选工具。六、分子性质操作Molecular Properties6.1reorder_atoms(mol, ...)确保同一分子在不同 SMILES 表示下具有一致的原子排序。目的保证特征生成的可复现性。同一分子CCO与OCC原子编号可能不同导致指纹或描述符向量错位重排后输出稳定一致的原子索引。6.2 氢原子管理函数说明remove_hs(mol, ...)移除分子中的氢原子默认行为I/O 读取时常用add_hs(mol, ...)添加显式氢原子3D 构象生成前必须执行见 conformers_module.md实践要点RDKit 默认处理隐式氢。文件读取如 SDF后显式氢会造成分子比较与指纹计算的干扰故 I/O 层默认remove_hsTrue而 3D 嵌入embedding则需要显式氢才能得到准确几何构象模块默认add_hsTrue。这一对对称操作的取舍贯穿整个 datamol 设计。七、指纹与相似度Fingerprints and Similarity7.1to_fp(mol, fp_typeecfp, ...)生成分子指纹用于相似度计算。指纹类型fp_type说明ecfp/fcfpMorgan 指纹默认 radius 3 即 ECFP6传radius2得到 ECFP4maccsMACCS 键指纹166 位topological拓扑指纹atompair原子对指纹考虑原子对及其距离rdkitRDKit 拓扑指纹计数变体ecfp-count、fcfp-count、atompair-count等保留计数信息的稠密向量实现细节datamol ≥ 0.12.5 使用 RDKitrdFingerprintGeneratorAPISKILL.md 版本说明。常用参数n_bits默认 2048、radius。返回Numpy 数组或 RDKit 指纹对象。# ECFP4相似性筛选中常用 fp dm.to_fp(mol, fp_typeecfp, radius2, n_bits2048) # 其他指纹类型 fp_maccs dm.to_fp(mol, fp_typemaccs) fp_topological dm.to_fp(mol, fp_typetopological) fp_atompair dm.to_fp(mol, fp_typeatompair) fp_rdkit dm.to_fp(mol, fp_typerdkit)选型建议源自 SKILL.md 最佳实践ECFPMorgan通用目的捕捉结构相似性MACCS速度快、特征空间小原子对Atom pairs考虑原子对与距离适合关注分子大小与连接性的场景7.2 距离计算函数说明pdist(mols, ...)计算列表内所有分子两两之间的 Tanimoto 距离cdist(mols1, mols2, ...)计算两组分子之间的 Tanimoto 距离两者均支持n_jobs并行。# 组内两两距离 distance_matrix dm.pdist(mols, n_jobs-1) # 两组之间距离查询集 vs 库 distances dm.cdist(query_mols, library_mols, n_jobs-1)实践要点Tanimoto 距离 1 − Tanimoto 相似度core_workflows.md 明确给出该换算关系。在虚拟筛选中距离最小即相似度最高# 找到与查询集最接近的库分子完整流程见 workflow_patterns.md min_distances distances.min(axis0) similarities 1 - min_distances八、聚类与多样性Clustering and Diversity8.1cluster_mols(mols, cutoff0.2, feature_fnNone, n_jobs1)使用Butina 算法进行相似性聚类。cutoffTanimoto 距离阈值默认 0.20完全相同1完全不同feature_fn自定义分子特征函数n_jobs并行化-1 使用全部 CPU 核心返回聚类列表每个聚类是分子索引的列表clusters dm.cluster_mols( mols, cutoff0.2, n_jobs-1 ) for i, cluster in enumerate(clusters): print(fCluster {i}: {len(cluster)} molecules) cluster_mols [mols[idx] for idx in cluster]重要规模限制Butina 聚类需构建完整距离矩阵适合约1000 个分子不适合 10,000 规模。core_api.md 与 SKILL.md 均明确提示此限制。8.2pick_diverse(mols, npick, ...)基于指纹多样性挑选分子的多样子集无需全距离矩阵适合大库的快速抽稀。diverse_mols dm.pick_diverse(mols, npick100)8.3pick_centroids(mols, npick, ...)挑选代表聚类的质心分子适合生成代表性子集如后续 SAR 可视化。centroids dm.pick_centroids(mols, npick50)实践要点当数据集规模超过 Butina 聚类上限时SKILL.md 故障排查章节建议改用pick_diverse替代全量聚类若仍需层次化结果可先聚类再取质心。九、图操作Graph Operations函数说明to_graph(mol)将分子转换为图表示用于基于图的分析如网络分析、图神经网络特征get_all_path_between(mol, start, end)查找分子结构中两个原子之间的所有路径graph dm.to_graph(mol) # 分子 → 图 # 查找原子索引 0 到 5 之间的所有路径 paths dm.get_all_path_between(mol, 0, 5)实践要点get_all_path_between常用于构效关系分析中双原子间距统计、环系遍历与片段关联研究与 fragments_scaffolds.md 中 BRICS/RECAP 碎片分析可形成互补。十、DataFrame 集成DataFrame Integration10.1 双向转换函数签名说明to_df(mols, smiles_columnsmiles, mol_columnmol)分子列表 → pandas DataFrame自动生成 SMILES 列与分子列from_df(df, smiles_columnsmiles, mol_columnmol)DataFrame → 分子列表从指定分子列提取# 分子列表 → DataFrame df dm.to_df(mols) # DataFrame → 分子列表 mols dm.from_df(df, mol_columnmol)10.2 与文件 I/O 衔接DataFrame 是 datamol 与 pandas 生态的桥梁。文件读写层io_module.md大量返回/接受 DataFrame# 读取 SDF → DataFrame含分子列 mol df dm.read_sdf(compounds.sdf, mol_columnmol) # CSV 自动将 SMILES 列转为分子列 df dm.read_csv(data.csv, smiles_columnSMILES, mol_columnmol) # 通用读写器自动探测格式支持压缩 df dm.open_df(file.sdf) # .sdf/.csv/.xlsx/.parquet/.json/.gz 等 dm.save_df(df, output.parquet) # Excel 导出时自动渲染分子图像 dm.to_xlsx(df, output.xlsx, mol_columns[mol])十一、并行化与性能源自 SKILL.mddatamol 内置大量操作的并行化统一使用n_jobs参数n_jobs1串行不并行n_jobs-1使用全部可用 CPU 核心n_jobs4使用 4 个核心支持并行的代表性函数见 SKILL.mddm.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)许多批量操作还支持progressTrue显示进度条result dm.operation(..., n_jobs-1, progressTrue)十二、完整实战从加载到分析的一条龙流水线综合 workflow_patterns.md 的端到端模式将本文核心 API 串联为可运行流水线import datamol as dm import pandas as pd # 1. 加载分子I/O 层自动消毒、去氢 df dm.read_sdf(compounds.sdf) # 2. 标准化核心 API 环节外部数据必做 df[mol] df[mol].apply(lambda m: dm.standardize_mol(m) if m else None) df df[df[mol].notna()] # 剔除解析失败的分子 # 3. 批量描述符并行计算 desc_df dm.descriptors.batch_compute_many_descriptors( df[mol].tolist(), n_jobs-1, progressTrue ) # 4. 类药性过滤Lipinski 五规则 druglike ( (desc_df[mw] 500) (desc_df[logp] 5) (desc_df[hbd] 5) (desc_df[hba] 10) ) filtered_df df[druglike] # 5. 多样性挑选避开全距离矩阵的规模限制 diverse_mols dm.pick_diverse(filtered_df[mol].tolist(), npick100) # 6. 指纹特征化 机器学习scipy/scikit-learn 为 datamol 依赖 import numpy as np X np.array([dm.to_fp(mol) for mol in diverse_mols]) # 7. 可视化结果 dm.viz.to_image( diverse_mols, legends[dm.to_smiles(m) for m in diverse_mols], outfilediverse_compounds.png, n_cols10 )说明datamol 自带scipy与scikit-learn依赖可直接以正常 PyPI 包导入SKILL.md 明确它们不是本技能捆绑脚本。十三、错误处理与故障排查13.1 安全的分子创建模式SKILL.mddef 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(fFailed to process {smiles}: {e}) return None13.2 常见问题速查问题解决方案分子解析失败先dm.standardize_smiles()或尝试dm.fix_mol()聚类内存错误大集合改用dm.pick_diverse()而非全量聚类构象生成缓慢减少n_confs或增大rms_cutoff详见 conformers_module.md远程文件访问失败安装匹配的 fsspec 后端uv pip install s3fs/gcsfs并仅设置该后端所需凭证十四、参考文档导航本仓库的 datamol 技能共包含 8 份参考文档与本文核心 API配套使用core_api.md核心命名空间函数本文主体来源core_workflows.md十大工作流的完整可运行代码io_module.md文件读写SDF/CSV/Excel/远程文件conformers_module.md3D 构象生成、聚类、SASAdescriptors_viz.md描述符与可视化fragments_scaffolds.md骨架提取、BRICS/RECAP 碎片reactions_data.md化学反应与玩具数据集workflow_patterns.md三条端到端流水线加载-过滤-分析、SAR 分析、虚拟筛选最佳实践总结源自 SKILL.md外部来源分子一律标准化dm.standardize_mol(mol, disconnect_metalsTrue, normalizeTrue, reionizeTrue)解析后检查 None大数据集使用n_jobs-1并行 progressTrue云 I/O 仅在用户明确要求时使用写入远程路径前先确认按场景选择指纹ECFP/MACCS/原子对注意规模限制Butina 聚类约 1000 分子以内ML 任务按骨架划分 train/test防数据泄漏见 fragments_scaffolds.mdSAR 系列可视化时开启对齐alignTrue【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
` 中间件与 `run()` 运行时搭建客户端渲染的 Remix 应用)
