agave-chem

AgaveChem

Try the web demo: denovochem.com/demos/reaction-atom-mapper

An open-source Python library for classification and atom-to-atom mapping (AAM) of chemical reactions. The default interface map_reactions for extracting atom-mapped reaction SMILES achieves state-of-the-art accuracy on the 1,758 reaction golden dataset benchmark.

AgaveChem mappers:

• Template mapper: Reaction SMIRKS templates sourced from ReactionFlash, Rxn-INSIGHT, and manual curation are applied to classify and map reactions into a scheme inspired by Carey et al., as well as RXNO ontology classifications.

• MCS-like mapper: Fingerprint based mapper that generates conservative partial maps at some radius around detected reaction centers.

• Identical fragment mapper: Maps fragments appearing structurally unchanged on both sides of the reaction (counter-ions, solvents, spectator reagents).

• Neural mapper: An ALBERT model trained in two phases - unsupervised masked language model (MLM) pre-training followed by supervised fine-tuning with a direct attention alignment objective against generated "ground truth" maps from the other three mappers. The supervised training data for the second phase is generated automatically from ~0.97M filtered Lowe USPTO reactions; the other three mappers fully map ~63% of reactions and ~90% of all product atoms in this dataset. The neural mapper is capable of mapping and automatically balancing unbalanced reactions.

These mappers can be used individually, or called as a pipeline using map_reactions().

Benchmark:

Requirements

• Python (version >= 3.10)
• RDKit
• rdchiral-plus
• PyTorch
• Transformers (Hugging Face)

Installation

Install AgaveChem from PyPi:

pip install agave_chem

Or install AgaveChem with pip directly from this repo:

pip install git+https://github.com/denovochem/agave_chem.git

Or clone and install locally:

git clone https://github.com/denovochem/agave_chem.git
cd agave_chem
pip install .

Basic usage

Mapping a batch of reactions through the full pipeline

from agave_chem import map_reactions

reactions = [
    "CC(Cl)(Cl)OC(C)(Cl)Cl.CC(=O)C(=O)O>>CC(=O)C(=O)Cl",
    "OCC(=O)OCCCO.Cl>>ClCC(=O)OCCCO",
]
results = map_reactions(reactions)
for r in results:
    print(r.final_mapping)

Neural mapper

from agave_chem import NeuralReactionMapper

mapper = NeuralReactionMapper("neural_mapper")
result = mapper.map_reaction("CC(Cl)(Cl)OC(C)(Cl)Cl.CC(=O)C(=O)O>>CC(=O)C(=O)Cl")
print(result.selected_mapping)

MCS-like mapper

from agave_chem import MCSReactionMapper

mapper = MCSReactionMapper("mcs_mapper")
result = mapper.map_reaction("CC(Cl)(Cl)OC(C)(Cl)Cl.CC(=O)C(=O)O>>CC(=O)C(=O)Cl")
print(result.selected_mapping)

Template mapper

from agave_chem import TemplateReactionMapper

mapper = TemplateReactionMapper("template_mapper")
result = mapper.map_reaction("CC(Cl)(Cl)OC(C)(Cl)Cl.CC(=O)C(=O)O>>CC(=O)C(=O)Cl")
print(result.selected_mapping)

Handling unbalanced reactions

The neural mapper is capable of mapping unbalanced reactions and returning balanced mapped reactions when one_to_one_correspondence is set to "auto" or False. When one_to_one_correspondence is set to "auto", the neural mapper uses heuristics to automatically determine for each reaction whether one_to_one_correspondence should be True or False.

from rdkit import Chem
from rdkit.Chem import rdChemReactions

rxn = "c1c(O)cc(O)cc1O.O=[N+]([O-])O>>c(O)1c([N+](=O)[O-])c(O)c([N+](=O)[O-])c(O)c1[N+](=O)[O-]"
rdChemReactions.ReactionFromSmarts(rxn, useSmiles=True)

from agave_chem import NeuralReactionMapper

mapper = NeuralReactionMapper("neural_mapper")
result = mapper.map_reaction(rxn, one_to_one_correspondence=False)
rdChemReactions.ReactionFromSmarts(result.selected_mapping, useSmiles=True)

Documentation

Documentation is a work in progress available here.

Contributing

• Feature ideas and bug reports are welcome on the Issue Tracker.
• Fork the source code on GitHub, make changes and file a pull request.

License

AgaveChem is licensed under the MIT license.

References

• RXNMapper: Schwaller et al., Science Advances, 2021
• RXNMapperv2: Grandjean et al., ChemRxiv, 2026
• LocalMapper: Chen et al., Nat. Commun., 2024
• GraphormerMapper: Nugmanov et al., ChemRxiv, 2022
• Rxn-INSIGHT: Probst et al.
• rdchiral: Coley et al., J. Chem. Inf. Model., 2019
• rdchiral_plus
• Lowe USPTO dataset
• Benchmarking study: Lin et al., ChemRxiv, 2020
• ReactionFlash