Atom mapping assigns correspondence labels to atoms on the supplied sides of a reaction. RXNMapper uses attention from a reaction language model to propose those correspondences. It does not supply an unknown product, design a synthesis route, establish a mechanism or prove a reaction occurred. This guide is for reaction-data curators who already have reactant/product records and want an audit trail.

Define an input policy before mapping

Reaction SMILES commonly use reactants>agents>products; reactants>>products leaves the middle field empty. Dots separate components within a side. Document whether reagents are retained in the middle, moved to the left, or excluded: moving them may change which atoms are available as mapping sources. Never discard the original string.

For the minimal example below, accept only nonempty left>>right records. This is an intentionally narrow review policy, not a statement that RXNMapper accepts only that notation. Reject unresolved placeholders, invalid molecules and pre-existing atom labels for this example rather than silently changing their meaning. Do not try to repair malformed strings by deleting arbitrary characters.

The official README shows RXNMapper().get_attention_guided_atom_maps(...) and the output keys mapped_rxn and confidence; the implementation identifies the default packaged model location. PyPI reports 0.4.3 on 2026-10-18. Its broad Python metadata is not a verified compatibility claim for every RDKit/PyTorch/Transformers combination. Lock the complete environment before execution.

A minimal audit record, without fabricated outputs

The code proposes a mapping for a small illustrative dehydrogenation string, preserving raw input, source label and input hash. It is not an experimental reaction record, and the omitted hydrogen balance is not validated. Code status: not executed. No mapped string or confidence value is asserted here.

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))

The source label deliberately says synthetic-example; replace it with a real accession and source version only for a traceable record. Retain the mapping package/model file hashes and configuration beside the environment manifest. The repository identifies an MIT code licence; independently review training/source data and model-asset terms before redistribution.

Inspect what the mapper actually returned

A parseable mapped SMILES is the first check, not the final acceptance criterion. Within each side, a positive map label should identify one atom. Across sides, a shared label should preserve element identity; isotope consistency, charge changes, valence, bond changes and stereochemistry require additional inspection. The example checks only selected structural invariants and flags unmatched product labels.

Do not require every reactant atom to appear in the recorded product: leaving groups, salts or omitted by-products can make that inappropriate. Conversely, unexplained product atoms may indicate missing contributors or an incomplete source record. Many-to-one ambiguities, symmetric atoms and equivalent representations can produce multiple chemically plausible mappings. Review the bond-change pattern and original reaction context instead of declaring a single string uniquely correct.

confidence is the mapper’s internal score. It is not a calibrated probability of chemical correctness or an experimental yield. No universal confidence threshold is specified here. If a project needs a threshold, select it against a separately reviewed reaction set and document both false acceptance and rejection.

Make failure handling visible in a batch

The official BatchedMapper can return a sentinel string or empty information for invalid input rather than raising an exception. Count these as failures, not successfully mapped reactions. Preserve one output/status entry per input ID, including precheck rejection, mapper exception, empty result and manual-review flags. Do not let a filter change the denominator without explanation.

For large batches, record batch size, software versions, model identity, device and any preprocessing/canonicalization. Cache only where project data policy allows it. Logs can contain unpublished structures; treat a debug log as data exposure, not just a technical file. The example’s exception handler records the exception type; production diagnostics should be reviewed before retaining raw strings or tracebacks.

Keep ORD provenance outside the SMILES string

The Open Reaction Database data repository stores structured reaction records with dataset/reaction identities. A flattened reaction string cannot retain all conditions, roles, measurements or provenance. Preserve dataset ID, reaction ID, revision/file hash, conversion rule and source licence with the mapping record. Review current ORD file/schema documentation rather than assuming that every export uses an old storage format.

An atom-map label is an index in a particular representation, not a persistent chemical identifier across an entire database. Keep the raw and normalized records together so someone can reconstruct what the mapper received. Source availability and a technically valid map do not establish ownership or experimental reliability.

Acceptance and next workflow

Accept a record only after parsing, label consistency, source completeness and the task-relevant chemical review are documented. Mark unresolved chemistry for manual review rather than manufacturing missing species. Mapping can later support reaction-center analysis or template extraction, but those are separate tasks. The existing retrosynthesis Recipe is related reading, not an RXNMapper pipeline or evidence of CARS integration.

Related ChemAI Atlas resources and workflows

RxnMapper · RDKit · Open Reaction Database

Planning a Retrosynthesis Tool Evaluation · Dataset Provenance and Licensing for Chemistry AI

Chemical Data Cleaning Stack · Retrosynthesis Starter Stack

CARS

Sources and evidence status

Sources inspected on 2026-10-18. Primary documentation supports capability/API statements. Audit protocols are editorial proposals; no scientific validation or measured performance is reported.