RXNMapper Documentation

You can automatically generate project documentation in HTML, LaTeX, or GitHub Pages formats using Sphinx.

First, ensure all development dependencies are installed:

pip install -r dev_requirements.txt

Then, navigate to the docs_source/ directory, run the module generation script, and use make to compile the desired format.

# 1. Install dependencies
pip install -r dev_requirements.txt

# 2. Compile documentation
cd docs_source/
sh generate_modules_rst.sh

# For HTML output
make html

# For LaTeX/PDF output
make latex
make latexpdf

# For GitHub Pages
make github

To run the test suite, install the project with the [dev,rdkit] extras and use pytest.

pip install -e .[dev,rdkit]
pytest tests

You can install RXNMapper using pip. It is recommended to install with the [rdkit] extra if RDKit is not already present in your environment to ensure full functionality.

pip install "rxnmapper[rdkit]"

To install from the source repository, clone the repository and install it in editable mode with the [rdkit] extra.

git clone https://github.com/rxn4chemistry/rxnmapper.git
cd rxnmapper
pip install -e ".[rdkit]"

To use the reaction mapping capabilities, import RXNMapper from the rxnmapper package and instantiate it. This object provides the interface for extracting atom maps from chemical reaction SMILES strings.

from rxnmapper import RXNMapper

rxn_mapper = RXNMapper()

To map a large dataset of chemical reactions, use the run_rxnmapper_on_dataset.py script. The input file must be in .csv, .tsv, or .json format and must contain a column named rxn which holds the reaction data.

Run the script from the examples/ directory using the following command structure:

python ../scripts/run_rxnmapper_on_dataset.py  \    --file_path example_rxns.csv \    --output_path  out.json \    --batch_size 8

For processing large datasets, use BatchedMapper. It automatically handles batching and provides robust error handling. If an input reaction is invalid, it will not raise an exception; instead, it will return ">>" (for string outputs) or an empty dictionary (for info outputs).

from rxnmapper import BatchedMapper

# Initialize with a specific batch size
rxn_mapper = BatchedMapper(batch_size=32)
rxns = ['CC[O-]~[Na+].BrCC>>CCOCC', 'invalid>>reaction']

# Returns mapped reaction strings directly
results_strings = list(rxn_mapper.map_reactions(rxns))

# Returns dictionaries containing 'mapped_rxn' and 'confidence'
results_with_info = list(rxn_mapper.map_reactions_with_info(rxns))

The RXNMapper class provides attention-guided atom mapping for reaction SMILES. Use the get_attention_guided_atom_maps method to receive both the mapped reaction SMILES and a confidence score for each input.

from rxnmapper import RXNMapper

rxn_mapper = RXNMapper()
rxns = ['CC(C)S.CN(C)C=O.Fc1cccnc1F.O=C([O-])[O-].[K+].[K+]>>CC(C)Sc1ncccc1F']
results = rxn_mapper.get_attention_guided_atom_maps(rxns)

# results format:
# [{'mapped_rxn': '...', 'confidence': 0.9565619900376546}]

Use the get_attention_guided_atom_maps method to perform reaction mapping on a list of reaction SMILES.

For each reaction provided in the input list, the method returns a dictionary containing:

• mapped_rxn: A string representing the reaction SMILES with the newly assigned atom maps.
• confidence: A float representing the model's confidence score for the mapping.

# rxns is a list of reaction SMILES strings
outputs = rxn_mapper.get_attention_guided_atom_maps(rxns)

for out in outputs:
    print(f"Mapped Reaction: {out['mapped_rxn']}")
    print(f"Confidence: {out['confidence']:.2f}")