Package chemaxon.reaction.mapper

Class AutoMapper

java.lang.Object
chemaxon.reaction.mapper.AutoMapper
All Implemented Interfaces:
ReactionMapper
@PublicApi public final class AutoMapper extends Object implements ReactionMapper

AutoMapper is a tool that performs automated chemical reaction mapping. The term mapping refers to the association of reactant side atoms to product side atoms. It can also identify and mark the reaction center during mapping. Please note, that when potential tetrahedral stereo centers need to be taken into account for correct mapping, it is necessary to provide coordinates for all the atoms in the reaction.

AutoMapper supports three mapping styles:

Helper functions are added to support concurrent mapping of reactions coming from various sources, such as


API usage examples


Basic example, shows how to map a single reaction: 
 RxnMolecule reaction = RxnMolecule.getReaction(MolImporter
         .importMol("COC1OC(CO)C(OC)C(O)C1O.OS(O)(=O)=O>>COC1OC(COS(O)(=O)=O)C(OC)C(O)C1O.[H]O[H]"));
 AutoMapper mapper = new AutoMapper();
 mapper.map(reaction);
 System.out.println(MolExporter.exportToFormat(reaction, "smiles"));

Map all reactions in a file, and mark the reaction centers: 

 MolImporter importer = new MolImporter("unmapped.smiles");
 MolExporter exporter = new MolExporter("mapped.mrv", "mrv");
 AutoMapper.mapReaction(importer, exporter, new AutoMapper.Options().setMarkBonds(true));
 importer.close();
 exporter.close();

Map reactions during iteration: 

 MolImporter importer = new MolImporter("unmapped.smiles");
 Iterator<Molecule> mappedMoleculeIterator = AutoMapper.iterator(importer.iterator());
 while (mappedMoleculeIterator.hasNext()) {
     Molecule mappedReaction = mappedMoleculeIterator.next();
     // do something with the mapped reaction ...
 }
 importer.close();

In concurrent mode reactions are cached. The default cache size is 1000, which can be overridden with "chemaxon.automapper.AutoMapper.cacheSize" Java system property. In case of invalid cache size (not positive, or not a valid number) the default value is used.

Since:
6.0

  • Field Details

    • DEFAULT_CACHE_SIZE_PROPERTY

      public static final String DEFAULT_CACHE_SIZE_PROPERTY
      cache size property key
      See Also:

    • DEFAULT_CACHE_SIZE

      public static final int DEFAULT_CACHE_SIZE
      default cache size
      See Also:

  • Constructor Details

    • AutoMapper

      public AutoMapper()
      Initializes an AutoMapper object

  • Method Details

    • mapReaction

      public static void mapReaction(Molecule reaction)
      Maps the given reaction.
      Parameters:
      reaction - the reaction to map

    • mapReaction

      public static void mapReaction(Molecule reaction, AutoMapper.Options options)
      Maps the given reaction.
      Parameters:
      reaction - the reaction to map
      options - the mapping options to use
      See Also:

    • mapReactions

      public static void mapReactions(Molecule... reactions)
      Maps the given reactions. Utilizes multiple threads if possible.
      Parameters:
      reactions - the reactions to map

    • mapReactions

      public static void mapReactions(Collection<Molecule> reactions)
      Maps the given reactions. Utilizes multiple threads if possible.
      Parameters:
      reactions - the collection of reactions to map

    • mapReactions

      public static void mapReactions(Collection<Molecule> reactions, AutoMapper.Options options)
      Maps the given reactions using the given options. Utilizes multiple threads if possible.
      Parameters:
      reactions - the collection of reactions to map
      options - the mapping options to use
      See Also:

    • mapReactions

      public static void mapReactions(MolImporter importer, MolExporter exporter) throws IOException
      Maps the reactions read from the given importer and writes them to the given exporter. Utilizes multiple threads if possible.
      Parameters:
      importer - the importer to read reactions from
      exporter - the exporter to write mapped reactions to
      Throws:
      IOException - on export failure

    • mapReactions

      public static void mapReactions(MolImporter importer, MolExporter exporter, AutoMapper.Options options) throws IOException
      Maps the reactions read from the given importer using the given options and writes them to the given exporter. Utilizes multiple threads if possible.
      Parameters:
      importer - the importer to read reactions from
      exporter - the exporter to write mapped reactions to
      options - the mapping options to use for mapping
      Throws:
      MolExportException - on export failure
      IOException - on export failure
      See Also:

    • iterator

      public static AutoMapper.ResultIterator iterator(Iterator<Molecule> reactions)
      Returns an auto-closeable result iterator that maps the reactions provided by the given input iterator. Utilizes multiple threads if possible.

      NOTE: the returned iterator provides the same molecule instances with mapping numbers added. Use this iterator with try-with-resources statement.

      Parameters:
      reactions - the input iterator for the reactions to map
      Returns:
      AutoMapper.ResultIterator that provides the mapped molecules

    • iterator

      public static AutoMapper.ResultIterator iterator(Iterator<Molecule> reactions, AutoMapper.Options options)
      Returns an auto-closeable result iterator that maps the reactions provided by the given input iterator using the given options. Utilizes multiple threads if possible.

      NOTE: the returned iterator provides the same molecule instances with mapping numbers added. Use this iterator with try-with-resources statement.

      Parameters:
      reactions - the input iterator for the reactions to map
      options - the mapping options to use
      Returns:
      AutoMapper.ResultIterator that provides the mapped molecules
      See Also:

    • mapReaction

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2026) public static void mapReaction(Molecule... reactions)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use mapReactions(Molecule...) instead. This method will be removed in a future release.
      Maps the reactions in the specified collection using multiple threads if possible.
      Parameters:
      reactions - the array of reactions to map

    • mapReaction

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2026) public static void mapReaction(AutoMapper.Options options, Molecule... reactions)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use mapReactions(Collection, Options) instead. This method will be removed in a future release.
      Maps the reactions in the specified collection using the specified options.
      Parameters:
      options - the mapping options to use
      reactions - the array of reactions to map

    • mapReaction

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2026) public static void mapReaction(ReactionMapper[] mappers, Molecule... reactions)
      Deprecated, for removal: This API element is subject to removal in a future version.
      No replacement. This method will be removed in a future release.
      Maps the reactions in the specified collection using the specified mappers in multiple threads. The number of mappers specifies the number of threads to use.
      Parameters:
      mappers - the mappers to use
      reactions - the collections of reactions to map

    • mapReaction

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2026) public static void mapReaction(Collection<Molecule> reactions)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use mapReactions(Collection) instead. This method will be removed in a future release.
      Maps the reactions in the specified collection using multiple threads if possible.
      Parameters:
      reactions - the collection of reactions to map

    • mapReaction

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2026) public static void mapReaction(Collection<Molecule> reactions, AutoMapper.Options options)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use mapReactions(Collection, Options) instead. This method will be removed in a future release.
      Maps the reactions in the specified collection using the specified options.
      Parameters:
      reactions - the collections of reactions to map
      options - the mapping options to use
      See Also:

    • mapReaction

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2026) public static void mapReaction(Collection<Molecule> reactions, ReactionMapper... mappers)
      Deprecated, for removal: This API element is subject to removal in a future version.
      No replacement. This method will be removed in a future release.
      Maps the reactions in the specified collection using the specified mappers in multiple threads. The number of mappers specifies the number of threads to use.
      Parameters:
      reactions - the collections of reactions to map
      mappers - the mappers to use

    • mapReaction

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2026) public static void mapReaction(MolImporter importer, MolExporter exporter) throws MolExportException, IOException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use mapReactions(MolImporter, MolExporter) instead. This method will be removed in a future release.
      Reads the reactions from the importer, maps them, and writes to the exporter. Uses multiple threads for mapping if possible.
      Parameters:
      importer - the importer to read reactions from
      exporter - the exporter to write mapped reactions to
      Throws:
      MolExportException - on export failure
      IOException - on export failure

    • mapReaction

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2026) public static void mapReaction(MolImporter importer, MolExporter exporter, AutoMapper.Options options) throws MolExportException, IOException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use mapReactions(MolImporter, MolExporter, Options) instead. This method will be removed in a future release.
      Reads the reactions from the importer, maps them, and writes to the exporter. Uses the specified number of threads for mapping.
      Parameters:
      importer - the importer to read reactions from
      exporter - the exporter to write mapped reactions to
      options - the mapping options to use for mapping
      Throws:
      MolExportException - on export failure
      IOException - on export failure
      See Also:

    • mapReaction

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2026) public static void mapReaction(MolImporter importer, MolExporter exporter, ReactionMapper... mappers) throws MolExportException, IOException
      Deprecated, for removal: This API element is subject to removal in a future version.
      No replacement. This method will be removed in a future release.
      Reads the reactions from the importer, maps them, and writes to the exporter. Uses the specified mappers for mapping. The number of mappers specified the number of threads to use.
      Parameters:
      importer - the importer to read reactions from
      exporter - the exporter to write mapped reactions to
      mappers - the mappers to use
      Throws:
      MolExportException - on export failure
      IOException - on export failure

    • map

      public boolean map(RxnMolecule reaction)
      Maps the reaction.
      Specified by:
      map in interface ReactionMapper
      Parameters:
      reaction - is the reaction to be mapped
      Returns:
      true if mapping was successful

    • setMappingStyle

      public void setMappingStyle(ReactionMapper.MappingStyle style)
      Sets the mapping style
      Specified by:
      setMappingStyle in interface ReactionMapper
      Parameters:
      style - the mapping style to set
      See Also:

    • getMappingStyle

      public ReactionMapper.MappingStyle getMappingStyle()
      Returns the mapping style of the mapper.
      Returns:
      the mapping style of the mapper

    • setMarkBonds

      public void setMarkBonds(boolean markResult)
      Description copied from interface: ReactionMapper
      Sets if the changing bonds should be marked or not.
      Specified by:
      setMarkBonds in interface ReactionMapper
      Parameters:
      markResult - specifies if the reaction center should be marked or not

    • isMarkBonds

      public boolean isMarkBonds()
      Returns if the mapper marks the reaction center bonds or not.
      Returns:
      if the mapper marks the reaction center bonds or not

    • setKeepMapping

      public void setKeepMapping(boolean keepMapping)
      Description copied from interface: ReactionMapper
      Sets if the initial mapping of the atoms should be kept or not.
      Specified by:
      setKeepMapping in interface ReactionMapper
      Parameters:
      keepMapping - specifies if the initial mapping of the atoms should be kept or not

    • setTimeLimit

      public void setTimeLimit(long timeLimitMilliseconds)
      Description copied from interface: ReactionMapper
      Sets time limit for the calculation. When the time limit is reached, the atoms are mapped according to the mapping found so far.
      Specified by:
      setTimeLimit in interface ReactionMapper
      Parameters:
      timeLimitMilliseconds - time limit in milliseconds, -1 means disabled.

    • isKeepMapping

      public boolean isKeepMapping()
      Returns if the mapper will keep the initial mapping or not.
      Returns:
      if the mapper will keep the initial mapping or not

    • unmap

      public static void unmap(Molecule mol)
      Remove atom maps from the given structure
      Parameters:
      mol - the structure to unmap