原子映射是在已给定反应两侧之间分配原子对应标签。RXNMapper 从反应语言模型的注意力中提出对应关系,不负责补出未知产物、设计合成路线、确认机理或证明反应已发生。本指南面向已有反应物/产物记录、需要审计链的反应数据整理人员。
先制定反应输入政策
Reaction SMILES 常写作 reactants>agents>products,reactants>>products 表示中间字段为空;同侧多个组分用点号分隔。必须声明试剂保留在中间、移到左侧还是排除,因为它会改变可作为原子来源的组分。始终保存原字符串。
下方最小示例只接受左右非空的 left>>right。这是为便于审核设置的狭义政策,不是 RXNMapper 全部支持格式的说明。示例拒绝占位符、非法分子和已有映射标签,避免静默改变其含义。不要通过任意删字符来修补反应字符串。
官方 README 展示 RXNMapper().get_attention_guided_atom_maps(...),输出包含 mapped_rxn 与 confidence;实现源码 指明默认随包模型路径。2026-10-18 的 PyPI 元数据 为 0.4.3。其宽泛 Python 声明不能证明所有 RDKit/PyTorch/Transformers 组合可用,执行前需锁定完整环境。
最小审计记录示例
代码为一个脱氢示意字符串请求映射,保留原输入、来源标签及输入哈希。它不是实验反应记录,也没有核验省略的氢平衡。Code status: not executed(未运行)。这里不预设映射结果或分数。
import hashlib
import json
from collections import Counter
from rdkit import Chem
from rxnmapper import RXNMapper
def parse_pair(text):
if text.count(">") != 2 or text.count(">>") != 1:
raise ValueError("This example requires left>>right")
sides = text.split(">>")
if not all(sides):
raise ValueError("Empty reaction side")
mols = [Chem.MolFromSmiles(side) for side in sides]
if any(mol is None for mol in mols):
raise ValueError("Unparseable reaction side")
return mols
raw = "CCO>>CC=O"
record = {"source_id": "synthetic-example", "raw_rxn": raw,
"input_sha256": hashlib.sha256(raw.encode()).hexdigest()}
try:
original = parse_pair(raw)
if any(a.GetAtomMapNum() for m in original for a in m.GetAtoms()):
raise ValueError("Existing atom maps require a separate policy")
result = RXNMapper().get_attention_guided_atom_maps([raw])[0]
mapped = result["mapped_rxn"]
mols = parse_pair(mapped)
flags = []
maps = []
for mol in mols:
labels = [a.GetAtomMapNum() for a in mol.GetAtoms() if a.GetAtomMapNum()]
if any(n > 1 for n in Counter(labels).values()):
flags.append("duplicate_positive_label_on_one_side")
maps.append({a.GetAtomMapNum(): a.GetAtomicNum()
for a in mol.GetAtoms() if a.GetAtomMapNum()})
if any(maps[0][k] != maps[1][k] for k in maps[0].keys() & maps[1].keys()):
flags.append("element_mismatch")
if maps[1].keys() - maps[0].keys():
flags.append("unmatched_product_labels")
if any(a.GetAtomMapNum() == 0 for a in mols[1].GetAtoms()):
flags.append("unmapped_product_atom")
record.update(mapped_rxn=mapped, confidence=result.get("confidence"),
flags=flags, status="needs_chemical_review")
except Exception as exc:
record.update(status="failed", error_type=type(exc).__name__)
print(json.dumps(record, ensure_ascii=False))
来源刻意标为 synthetic-example;只有真实可追溯数据才替换为实际 accession 和版本。还应在环境清单旁保存映射软件、模型文件哈希和配置。仓库标明 MIT 代码许可;训练/原始数据及模型资产的使用条件仍须在再分发前分别确认。
检查映射含义,而不只检查字符串
映射后 SMILES 能解析只是第一步。同一侧的正整数标签应唯一;两侧相同标签应对应同一元素。还要检查同位素、电荷变化、价态、键变化和立体化学。示例只检查部分结构约束,并将产物中无左侧对应的标签标为待审。
不要要求每个反应物原子都出现在所记录产物中:离去基团、盐和省略副产物可能使这一要求不合理。反过来,来源无法解释的产物原子可能意味着缺失贡献组分或源记录不完整。对称原子、等价表示与多对一歧义也可能产生多个合理映射;需要结合键变化和原始语境审阅,不能认定一个字符串就是唯一答案。
confidence 是映射器内部评分,不是化学正确性的校准概率,更不是实验收率。本文不设通用阈值。项目若需要自动通过阈值,应在独立人工审核集上确定,并记录误接收与误拒绝。
批处理时显式保存失败
官方 BatchedMapper 对非法输入可能返回占位字符串或空信息,而不是抛异常。应计入失败,不能算成功映射。每个输入 ID 必须有一个状态记录,区分前置拒绝、模型异常、空结果和待人工复核;过滤失败时不能悄悄改变统计分母。
批量处理中保存 batch size、版本、模型身份、设备及预处理/规范化。缓存也须符合项目的数据政策。调试日志可能包含未公开结构,属于数据暴露面。示例只记录异常类型;实际系统保留原字符串或堆栈前仍需检查其敏感内容。
ORD 的来源信息不能压缩成一个 SMILES
Open Reaction Database 数据仓库 保存带数据集、反应标识的结构化记录。扁平字符串不能承载全部条件、组分角色、测量和出处。应保留 dataset ID、reaction ID、revision/文件哈希、转换规则及源许可,并查当前文件与 schema 文档,不假设一直沿用旧存储格式。
映射标签只是在特定表示中的索引,不是跨库稳定化学标识。保留原始与规范化记录,才能重建模型实际收到的内容。来源可下载、映射可解析,都不能证明数据权属或实验可靠性。
验收与后续工作边界
只有记录解析、标签一致性、来源完整性和任务所需化学审阅,才可接受该条数据。未解决问题进入人工队列,不臆造缺失物种。映射可供后续反应中心分析或模板提取,但它们属于另一个任务。已有逆合成 Recipe 是关联阅读,不是已执行的 RXNMapper 流水线或 CARS 集成证明。
站内资源、指南与工作流
RxnMapper · RDKit · Open Reaction Database
来源与证据状态
来源查阅日期:2026-10-18。官方资料支持能力与 API 陈述;审计与验收流程属于编辑建议,不代表科学验证或实测性能。