volcengine 化学结构标准化与质量检查
把本地结构数据转换为可审计的标准化结果。始终保留原始结构，显式展示失败、派生 parent、重复关系和人工复核点。
执行流程
- 确认用户目标、输入文件/结构和期望 profile。未指定时使用
chembl-pipeline。 - 检查本地依赖：
python -c "import rdkit, chembl_structure_pipeline; print(rdkit.__version__, chembl_structure_pipeline.__version__)"
- 运行确定性脚本。文件输入示例：
python scripts/standardize_structures.py \
--input compounds.csv \
--input-format csv \
--structure-column structure \
--id-column id \
--profile chembl-pipeline \
--output structures-qc.json \
--csv-summary structures-qc.csv
直接输入示例：
python scripts/standardize_structures.py \
--smiles 'CCO' --record-id ethanol \
--smiles 'CO(C)C' --record-id invalid \
--profile rdkit-basic \
--output structures-qc.json
- 校验 JSON：
python scripts/validate_output.py structures-qc.json
- 读取输入输出与标准化边界，解释
disposition、QC、重复分组和 parent 边界。 - 向用户总结总数、ready/review/rejected、关键失败、重复组和人工确认项，并提供输出路径。
Profile 选择
rdkit-basic：处理步骤仅使用 RDKit Cleanup 与 ChargeParent，适合轻量本地清洗；当前发布环境仍按requirements.txt同时安装两个固定依赖，以便显式切换 profile。chembl-pipeline：使用 ChEMBL Checker、Standardizer、GetParent；该 Pipeline 本身基于 RDKit，不得称为独立引擎交叉验证。- 一次运行只选择一个 profile。不得无条件串联并覆盖结果。
强制规则
- 原始
id、来源和original_structure必须逐条保留。 - 空文件或零条记录必须失败关闭；不得生成“0 条成功”的结果。
- 无法解析的记录必须输出并标为
rejected；不得生成伪 canonical SMILES。 - 对混合物/复杂多组分和聚合物不生成单一 parent。
- parent 是派生表示；同一 parent 不代表盐型、游离形式或实物样品相同。
- 未知立体化学、金属、同位素、混合物、聚合物/V3000 必须显式进入人工复核。
- ChEMBL GetParent 返回排除标记时必须进入人工复核，不得标为
ready_for_downstream。 ready_for_downstream只表示通过当前数据规则，不表示身份、活性、安全性或科学结论已确认。- 不查询公共数据库，不抓取 ChEMBL 活性；需要身份补充时单独使用
resolve-chemical-identities。 - 不输出 API Key、Authorization、Cookie、Token 或其他凭证。
- 不自动判断药效、毒性、活性、可合成性、实验安全或结构确证。
退出码
0：完成且没有 rejected 记录；2：已写出完整结果，但至少一条记录 rejected；3：依赖或输入加载失败。
退出码不是科学结论；始终查看 JSON 记录和人工复核项。