standardize-chemical-structures

name	standardize-chemical-structures
description	离线批量解析、标准化、去盐、提取 parent、检查异常并按原始/标准化/parent 结构分组。用于清洗 SMILES、CSV、SDF、MolBlock，检查价态/立体化学/混合物，或为描述符、相似性检索和建模准备结构数据。

化学结构标准化与质量检查

把本地结构数据转换为可审计的标准化结果。始终保留原始结构，显式展示失败、派生 parent、重复关系和人工复核点。

执行流程

1. 确认用户目标、输入文件/结构和期望 profile。未指定时使用 chembl-pipeline。
2. 检查本地依赖：

python -c "import rdkit, chembl_structure_pipeline; print(rdkit.__version__, chembl_structure_pipeline.__version__)"

3. 运行确定性脚本。文件输入示例：

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

4. 校验 JSON：

python scripts/validate_output.py structures-qc.json

5. 读取输入输出与标准化边界，解释 disposition、QC、重复分组和 parent 边界。
6. 向用户总结总数、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 记录和人工复核项。