Datamol I/O 模块完全指南:用 datamol.io 读写 SDF、SMILES、CSV 与远程分子文件 Datamol I/O 模块完全指南用 datamol.io 读写 SDF、SMILES、CSV 与远程分子文件【免费下载链接】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-skillsdatamol.io是 Datamol 的分子文件读写核心模块为药物发现中最常见的数据格式SDF、SMILES、CSV、Excel、Mol2、PDB 等提供了统一、Pythonic 的文件处理接口。本文以本仓库 skills/datamol/references/io_module.md 为主体结合 SKILL.md 与 core_workflows.md 中的实操模式系统讲解各类读取/写入函数、通用 DataFrame 读写器、fsspec 远程文件支持与跨函数关键参数帮助你快速搭建可复制的分子数据 I/O 流水线。环境准备与导入约定在深入 I/O 函数之前先确认运行环境。根据 SKILL.md 的说明本 Skill 面向datamol 0.12.xPyPI 稳定版 0.12.5要求 Python 3.8。安装与导入方式如下uv pip install datamolRDKit 会作为 datamol 的直接依赖自动安装0.12.2 起。若需要读写远程文件S3、GCS、HTTP再按需安装对应的 fsspec 后端uv pip install s3fs # AWS S3 uv pip install gcsfs # Google Cloud Storage导入约定统一为import datamol as dm值得注意的是datamol 0.10.0 起模块默认懒加载只有真正访问dm.io等子模块时才会导入其实现如需禁用该行为可设置环境变量DATAMOL_DISABLE_LAZY_LOADING1。这一点对 I/O 场景的启动性能有实际影响——首次调用读写函数时才加载对应后端。仓库 tests/skill-requirements.toml 中[skills.datamol]段也明确列出了该 Skill 的依赖集合datamol、rdkit、s3fs、gcsfs可作为搭建 CI 或 Agent 环境时的安装清单参考。读取分子文件dm.read_sdf()读取 SDF 结构数据文件SDFStructure-Data File是化学信息学中最常见的分子存储格式每个条目包含 2D/3D 原子坐标与可选的属性字段。函数签名如下df dm.read_sdf(filename, sanitizeTrue, remove_hsTrue, as_dfTrue, mol_columnmol, ...)关键参数说明参数默认值作用filename必填SDF 文件路径支持本地路径与 fsspec 远程路径如s3://...sanitizeTrue是否对分子做 sanitization结构合法性校验与标准化remove_hsTrue是否移除显式氢原子as_dfTrue返回pandas.DataFrameTrue还是分子列表Falsemol_columnmolDataFrame 中存放rdkit.Chem.Mol对象的列名n_jobs—启用并行解析-1用满所有核1为串行返回值as_dfTrue时返回 DataFrame每行一个分子附带 SDF 属性字段否则返回分子列表。典型用法df dm.read_sdf(compounds.sdf)结合并行解析与进度条可显著加速大文件读取df dm.read_sdf(large_library.sdf, n_jobs-1, progressTrue)dm.read_smi()读取 SMILES 文件SMILES 文件默认以空格分隔常见格式为「SMILES 后跟分子 ID/名称」。函数签名df dm.read_smi(filename, smiles_columnsmiles, mol_columnmol, as_dfTrue, ...)示例df dm.read_smi(molecules.smi, smiles_columnsmiles, mol_columnmol)dm.read_csv()读取 CSV 并自动转换 SMILESCSV 是外部数据集如筛选结果、活性表的常见载体。该函数支持从指定列自动创建分子对象df dm.read_csv(filename, smiles_columnsmiles, mol_columnNone, ...)smiles_column存放 SMILES 字符串的列名mol_column若指定则根据smiles_column生成对应的分子对象列若为None则只读回 DataFrame 而不做分子转换。示例df dm.read_csv(data.csv, smiles_columnSMILES, mol_columnmol)dm.read_excel()读取 Excel 文件df dm.read_excel(filename, sheet_name0, smiles_columnsmiles, mol_columnNone, ...)sheet_name工作表可为索引0或工作表名称其余参数与read_csv类似。示例df dm.read_excel(compounds.xlsx, sheet_nameSheet1, smiles_columnSMILES, mol_columnmol)MOL block 与 PDB 字符串/文件解析除整文件读取外I/O 模块还提供结构块block解析与更多格式支持dm.read_molblock(molblock, sanitizeTrue, remove_hsTrue)解析 MOL block 字符串分子结构的文本表示适用于从数据库、API 响应或论文补充材料中直接获取结构块的情况dm.read_mol2file(filename, sanitizeTrue, remove_hsTrue, cleanupSubstructuresTrue)读取 Tripos Mol2 格式文件常用于对接软件与力场文件dm.read_pdbfile(filename, sanitizeTrue, remove_hsTrue, proximityBondingTrue)读取 PDBProtein Data Bank格式文件用于蛋白-配体体系dm.read_pdbblock(pdbblock, sanitizeTrue, remove_hsTrue, proximityBondingTrue)解析 PDB block 字符串。这些函数都继承了sanitize与remove_hs两个核心开关保证读入的结构与后续 RDKit 操作无缝衔接。dm.open_df()通用 DataFrame 读取器open_df是 I/O 模块的「万能入口」自动根据文件扩展名检测格式支持的格式CSV、Excel、Parquet、JSON、SDF以及压缩文件如.gz。df dm.open_df(data.csv) df dm.open_df(molecules.sdf.gz) # 压缩的 SDF 同样自动识别这意味着你无需关心数据集是表格还是结构文件、是否压缩open_df都能统一读成 DataFrame——这在处理来源混杂的化合物库时尤为实用。写入分子文件dm.to_sdf()写入 SDF 文件支持多种输入类型分子列表list ofrdkit.Chem.Mol含分子列的 DataFrame分子序列任意可迭代对象。# 从分子列表写入 dm.to_sdf(mols, output.sdf) # 从 DataFrame 写入指定分子列 dm.to_sdf(df, output.sdf, mol_columnmol)dm.to_smi()写入 SMILES 文件dm.to_smi(mols, filename, mol_columnNone, ...)输出格式为「SMILES 字符串 可选分子名/ID」可配合dm.to_smiles()的isomericTrue参数保留立体化学信息。dm.to_xlsx()导出带分子结构图的 Excel这是 datamol 的特色能力不仅写入分子数据还能把分子自动渲染成图片并嵌入 Excel 单元格直接生成可视化的结构清单dm.to_xlsx(df, molecules.xlsx, mol_columns[mol])mol_columns需要渲染为图片的分子列名列表。该功能在向合作方交付化合物清单、快速人工审阅结构时非常实用是纯表格导出无法替代的体验。dm.to_molblock()与dm.to_pdbblock()与读取方向对应写入侧也支持结构块输出dm.to_molblock(mol, ...)将分子转换为 MOL block 字符串dm.to_pdbblock(mol, ...)将分子转换为 PDB block 字符串。这两个函数适合与外部工具交换结构数据或保存到数据库字段中。dm.save_df()通用 DataFrame 写入器与open_df对应的通用写入器支持 CSV、Excel、Parquet、JSON 等多种格式根据文件扩展名自动判断格式且支持压缩datamol 0.10.0 起新增dm.save_df(df, output.csv) dm.save_df(df, output.parquet) dm.save_df(df, output.csv.gz) # 支持压缩输出配合open_df一个「读任意格式 → 处理 → 写任意格式」的通用流水线只需要两个函数即可闭环。远程文件支持fsspec 集成datamol 的全部 I/O 函数通过 fsspec 集成支持远程路径覆盖主流对象存储与 Web 协议S3AWSGCSGoogle CloudAzureHTTP/HTTPS可选后端安装方式uv pip install s3fs # S3 uv pip install gcsfs # GCS凭证处理远程后端只读取对应云厂商的标准环境变量如AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_DEFAULT_REGION、GOOGLE_APPLICATION_CREDENTIALS等。datamol 在本地将路径交给 fsspec 处理不会收集或向第三方端点传输环境变量如 core_workflows.md 强调的应只向命名的厂商变量授予凭证作用域。在写远程路径之前务必先与用户确认目标位置。示例df dm.read_sdf(s3://bucket/compounds.sdf) df dm.read_csv(https://example.com/data.csv) dm.save_df(df, s3://bucket/output.parquet) # 先确认目标路径再执行远程 I/O 的实操纪律core_workflows.md 给出了两条重要约定仅在用户明确要求时使用云路径读取使用用户提供的 URL写入前先确认目标若远程访问失败优先检查是否安装了匹配的 fsspec 后端s3fs/gcsfs并确认当前环境中只设置了该后端所需的厂商凭证。这两条纪律与 SKILL.md 的 Troubleshooting 指引一致可避免在 Agent 场景中误写云端、误用凭证。跨函数关键参数速查以下参数在多个 I/O 函数中反复出现理解它们的默认语义有助于写出行为可预测的代码参数默认值含义sanitizeTrue是否对分子执行 sanitization结构校验、芳香性判断等remove_hsTrue是否移除显式氢原子as_df多数函数为True返回 DataFrame 还是分子列表n_jobs—并行度None/-1 用满所有核1 串行正整数 指定核数mol_columnmolDataFrame 中分子对象的列名smiles_columnsmilesDataFrame 中 SMILES 字符串的列名关于并行度的约定与 SKILL.md 中全局的并行策略一致n_jobs1串行n_jobs-1用满所有 CPU 核n_jobs4使用 4 核许多批量操作还支持progressTrue显示进度条。端到端实战读取 → 标准化 → 分析 → 输出将上述 I/O 能力串成一条完整流水线改编自 workflow_patterns.mdimport datamol as dm import pandas as pd # 1. 读取 SDF可换成 open_df 自动识别任意格式 df dm.read_sdf(compounds.sdf) # 2. 标准化并丢弃解析失败的分子 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. 按类药性规则过滤 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. 输出SDF 带结构图的 Excel Parquet压缩 dm.to_sdf(diverse_mols, diverse.sdf) dm.to_xlsx(filtered_df, compounds_review.xlsx, mol_columns[mol]) dm.save_df(filtered_df, compounds_filtered.parquet.gz)这条流水线展示了read_sdf/open_df读、to_sdf/to_xlsx/save_df写如何与 core_workflows.md 中的标准化、描述符与筛选逻辑协同覆盖从原始数据到交付物结构文件、可视化 Excel、压缩列式存储的完整闭环。常见问题排查分子解析失败读入的 SMILES 或结构无法解析时先尝试dm.standardize_smiles()或dm.fix_mol()见 core_api.md并在调用dm.to_mol()后检查返回值是否为None大文件读取慢为read_sdf开启n_jobs-1并行解析并配合progressTrue观察进度Excel 中分子不显示确认使用to_xlsx的mol_columns参数指定了正确的分子列名远程文件访问失败安装匹配的 fsspec 后端s3fs/gcsfs并核实只设置了该后端所需的标准厂商凭证。小结datamol.io 提供了一套覆盖「读、写、远程、通用」四个维度的完整分子文件处理方案read_sdf/read_smi/read_csv/read_excel处理主流格式read_molblock/read_pdbblock等处理结构块open_df/save_df构成自动识别格式的通用读写闭环而 fsspec 集成让 S3、GCS、HTTP 路径与本地路径无缝统一。配合 SKILL.md 中的并行约定n_jobs-1、progressTrue与标准化最佳实践即可高效搭建面向真实药物发现数据集的分子 I/O 流水线。更完整的工作流示例见 core_workflows.md 与 workflow_patterns.md。【免费下载链接】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),仅供参考