Package chemaxon.marvin.calculations

Class MarkushEnumerationPlugin

java.lang.Object
chemaxon.marvin.plugin.CalculatorPlugin
chemaxon.marvin.calculations.MarkushEnumerationPlugin
All Implemented Interfaces:
TaggedCalculator, chemaxon.license.Licensable
@PublicApi public class MarkushEnumerationPlugin extends CalculatorPlugin
Plugin class for enumerating Markush molecules.
Input: a Markush structure.
Output: the number of possible enumerations and the enumerated molecules.

Note: Enumeration does not consider R-Logic conditions.

API usage examples:

  • Sequential enumeration: 
     // Create plugin
 MarkushEnumerationPlugin plugin = new MarkushEnumerationPlugin();

 // Set target molecule
 plugin.setMolecule(mol);

 // Run the calculation
 plugin.run();

 // 1. Get results one by one
 Molecule m = plugin.getNextStructure();
 while (m != null) {
     System.out.println(m.toFormat("smiles"));
     // ...
     // Getting next enumerated molecule
     m = plugin.getNextStructure();
 }

 // OR
 // 2. Get results in an array
 long size = plugin.getStructureCount();
 if (size != -1 && size <= Integer.MAX_VALUE) {
     Molecule[] enumerated = plugin.getStructures();
     for (int i = 0; i < enumerated.length; i++) {
         System.out.println(enumerated[i].toFormat("smiles"));
         // ...
     }
 }
  • Random enumeration: 
     // Create plugin
 MarkushEnumerationPlugin plugin = new MarkushEnumerationPlugin();

 // Set random enumeration
 plugin.setRandomEnumeration();

 // Set the number of random structures to generate
 plugin.setMaxStructureCount(10);

 // Set target molecule
 plugin.setMolecule(mol);

 // Run the calculation
 plugin.run();

 for (int i = 0; i < 10; i++) {
     Molecule m = plugin.getNextStructure();
     System.out.println(m.toFormat("smiles"));
     // ...
 }

For concurrent plugin example applications using Chemaxon's concurrent framework, refer to the Concurrent plugin examples.

Since:
Marvin 5.0.3

  • Field Details

    • FILTER_VALENCE

      public static final MolFilter FILTER_VALENCE
      Filter constant: valence filter. Set this filter in setFilter(chemaxon.util.MolFilter) in order to reject molecules with valence errors.
      Since:
      Marvin 5.1
      See Also:

    • COLORING_NONE

      public static final int COLORING_NONE
      Constant for no hit coloring.
      Since:
      Marvin 5.1
      See Also:

    • COLORING_SCAFFOLD

      public static final int COLORING_SCAFFOLD
      Constant for scaffold coloring.
      Since:
      Marvin 5.1
      See Also:

    • COLORING_RGROUPS

      public static final int COLORING_RGROUPS
      Constant for R-group coloring.
      Since:
      Marvin 5.1
      See Also:

    • COLORING_ALL

      public static final int COLORING_ALL
      Constant for setting all coloring options, currently scaffold and R-groups.
      Since:
      Marvin 5.1
      See Also:

  • Constructor Details

    • MarkushEnumerationPlugin

      public MarkushEnumerationPlugin()
      Constructor.

  • Method Details

    • isLicensed

      public boolean isLicensed()
      Description copied from class: CalculatorPlugin
      Returns true if the plugin is licensed. The license checking is based on the product name, returned by CalculatorPlugin.getProductName().
      Specified by:
      isLicensed in interface chemaxon.license.Licensable
      Overrides:
      isLicensed in class CalculatorPlugin
      Returns:
      true if the plugin is licensed

    • setLicenseEnvironment

      public void setLicenseEnvironment(String env)
      Description copied from class: CalculatorPlugin
      Sets license environment to be stored.
      Specified by:
      setLicenseEnvironment in interface chemaxon.license.Licensable
      Overrides:
      setLicenseEnvironment in class CalculatorPlugin
      Parameters:
      env - environment String to be stored and passed to the LicenseHandler in the isLicensed method

    • getProductName

      public String getProductName()
      Returns the product identifier of the plugin as given by LicenseManager.
      Specified by:
      getProductName in class CalculatorPlugin
      Returns:
      The identifier LicenseManager.MARKUSH_ENUM_PLUGIN

    • handlesMultiFragmentMolecules

      public boolean handlesMultiFragmentMolecules()
      Returns true if the plugin handles multifragment molecules, false otherwise. In the latter case the plugin takes the fragment with more atoms if a multifragment molecule is given as input. Returns true if parameter "single" is set to "false", false otherwise (default: false).
      Overrides:
      handlesMultiFragmentMolecules in class CalculatorPlugin
      Returns:
      true if the plugin handles multifragment molecules, false otherwise

    • setParameters

      public void setParameters(Properties params) throws PluginException
      Sets the input parameters for the plugin. Enumeration parameters and value ranges:
      • type: structure,structures,count
      • calctype: enumerate,random
      • mode: count mode (small, large, magnitude or string, default: small)
      • max: max structure count
      • atoms: 1-based atom indexes to be enumerated (','-separated list)
      • code: true if Markush code should be generated (default: false)
      • valencecheck: true if valence filter is on (default: false)
      • alignscaffold: true if scaffold alignment is set (default: false)
      • coloring: "scaffold", "rgroups", "none" or "all" (default: "none")
      Overrides:
      setParameters in class CalculatorPlugin
      Parameters:
      params - is the parameter table
      Throws:
      PluginException - on error

    • setChemicalTermsArgument

      @Deprecated protected void setChemicalTermsArgument(String arg) throws PluginException
      Deprecated.
      For internal use only.
      Sets the argument string as specified in Chemical Terms expressions.
      Overrides:
      setChemicalTermsArgument in class CalculatorPlugin
      Parameters:
      arg - is the atom string as a '-'-separated list
      Throws:
      PluginException - on error

    • setRandomEnumeration

      public void setRandomEnumeration()
      Sets random enumeration. Must be called before setting the molecule in CalculatorPlugin.setMolecule(chemaxon.struc.Molecule). Set also the number of requested structures in setMaxStructureCount(long), otherwise only one randomly enumerated structure will be generated.
      Since:
      Marvin 5.1

    • setRandomSeed

      public void setRandomSeed(long seed)
      Sets the random seed to be used in case of random enumeration. Must be called before setting the molecule in CalculatorPlugin.setMolecule(chemaxon.struc.Molecule).
      Parameters:
      seed - the random seed. 0 means using the current time (default behavior).
      See Also:

    • isRandomEnumeration

      public boolean isRandomEnumeration()
      Returns true if random enumeration is requested.
      Returns:
      true if random enumeration is requested

    • setEnumerateHomology

      public void setEnumerateHomology(boolean enumerate)
      Sets if homology groups should be enumerated or not. Must be called before setting the molecule.
      Since:
      Marvin 5.2

    • isHomologyEnumerated

      public boolean isHomologyEnumerated()
      Indicates if homology groups are enumerated or not.
      Since:
      Marvin 5.2

    • setEnumCodeNeeded

      public void setEnumCodeNeeded(boolean value)
      Indicates whether unique Markush enumeration code should be generated. Must be called before setting the molecule.
      Parameters:
      value - true, if code generation is needed
      Since:
      Marvin 5.1.2

    • getEnumCodeNeeded

      public boolean getEnumCodeNeeded()
      Tests whether unique Markush enumeration code should be generated
      Returns:
      true, if code generation is needed
      Since:
      Marvin 5.1.2

    • setStructureID

      public void setStructureID(String id)
      Sets structure ID to be used in Markush code generation. The name of the SDF / MRV tag storing the ID in the Markush structure or else the ID itself. Must be called before setting the molecule. Set null for no structure ID (default). Calling this method with non-null argument will automatically switch on Markush code generation.
      Parameters:
      id - the tag name or the ID
      Since:
      Marvin 5.1.3
      See Also:

    • getStructureID

      public String getStructureID()
      Returns the structure ID used in Markush code (enumeration ID) generation.
      Returns:
      the structure ID storing tag name or the ID itself
      Since:
      Marvin 5.1.3
      See Also:

    • setFilter

      public void setFilter(MolFilter filter)
      Sets the molecule filter. Must be called before setting the molecule. Default: null (get all enumerated structures).
      Parameters:
      filter - the molecule filter or null for no filtering
      Since:
      Marvin 5.0
      See Also:

    • isFiltered

      public boolean isFiltered()
      Return true if molecule filter is set.
      Returns:
      true if molecule filter is set

    • isApproximateCount

      public boolean isApproximateCount() throws PluginException
      Returns true if count is approximate due to multiple position bonds with multicenters of variable size, false otherwise.
      Returns:
      true if count is approximate
      Throws:
      PluginException

    • setMaxStructureCount

      public void setMaxStructureCount(long max)
      Sets the maximum number of structures to be generated. Set -1 for unlimited. Default: unlimited for the sequential case, 1 for the random case. Must be called before setting the molecule in CalculatorPlugin.setMolecule(chemaxon.struc.Molecule).
      Parameters:
      max - is the maximum number of structures to be generated
      See Also:

    • setAlignScaffold

      public void setAlignScaffold(boolean value)
      Sets the scaffold aligning mode. Must be called before setting the molecule in CalculatorPlugin.setMolecule(chemaxon.struc.Molecule).
      Parameters:
      value - if true, tries to align scaffold in enumerated structures as it was in the original Markush structure
      Since:
      Marvin 5.1

    • getAlignScaffold

      public boolean getAlignScaffold()
      Gets the scaffold aligning mode
      Returns:
      true, if enumerated structures should be aligned to the scaffold
      Since:
      Marvin 5.1

    • setColoring

      public void setColoring(int coloring)
      Sets hit coloring options. Must be called before setting the molecule in CalculatorPlugin.setMolecule(chemaxon.struc.Molecule).
      Parameters:
      coloring - COLORING_SCAFFOLD, COLORING_RGROUPS, COLORING_NONE, or COLORING_ALL
      Since:
      Marvin 5.1

    • getColoring

      public int getColoring()
      Returns the hit coloring options.
      Returns:
      the hit coloring options
      Since:
      Marvin 5.1
      See Also:

    • isCleanNeeded

      public boolean isCleanNeeded()
      Returns true if clean is needed for GUI display.
      Returns:
      true if clean is needed for GUI display

    • checkMolecule

      public void checkMolecule(Molecule mol) throws PluginException
      Checks the input molecule.
      Overrides:
      checkMolecule in class CalculatorPlugin
      Parameters:
      mol - is the input molecule
      Throws:
      PluginException - with error message for the user if the molecule is refused

    • setMolecule

      protected Molecule setMolecule(Molecule mol, boolean st, boolean om, boolean storeExplicitHydrogens) throws PluginException
      Overrides:
      setMolecule in class CalculatorPlugin
      Throws:
      PluginException

    • setInputMolecule

      protected void setInputMolecule(Molecule mol) throws PluginException
      Sets the input molecule.
      Specified by:
      setInputMolecule in class CalculatorPlugin
      Parameters:
      mol - is the input molecule
      Throws:
      PluginException - on error

    • run

      public boolean run() throws PluginException
      Creates enumerated structures.
      Specified by:
      run in class CalculatorPlugin
      Returns:
      true
      Throws:
      PluginException - on error
      See Also:

    • countEnumerations

      public BigInteger countEnumerations() throws PluginException
      Returns the number of all enumerated structures, no arithmetic overflow because counts in BigInteger.

      In case when the result does not exceed Long.MAX_VALUE, the number of enumerates is also returned by getStructureCount() (after run() is called).

      Note: run() need not be called before using this function.

      Returns:
      the number of enumerated structures
      Throws:
      PluginException - on expansion error
      See Also:

    • countEnumerationsMagnitude

      public int countEnumerationsMagnitude() throws PluginException
      Returns the magnitude (the number of decimal "digits") of the number of all enumerated structures. No arithmetic overflow because counts in BigInteger.

      Note: run() need not be called before using this function.

      Returns:
      the magnitude of the number of enumerated structures
      Throws:
      PluginException - on expansion error
      See Also:

    • getStructureCount

      public long getStructureCount()
      Returns the number of all enumerated structures, -1 in case of arithmetical overflow (if the number would exceed Long.MAX_VALUE). To handle the case of arithmetical overflow, call countEnumerations() or countEnumerationsMagnitude(). Returns the number of structures to be returned in case of random enumeration.

      Warning: run() must be called before using this function.

      Returns:
      the number of enumerated structures
      See Also:

    • getLimitedStructureCount

      public int getLimitedStructureCount()
      Returns the number of structures to be generated. This is the minimum of the actual structure count returned by getStructureCount() and the specified maximum (see setMaxStructureCount(long)). Returns the number of structures to be returned in case of random enumeration.
      Returns:
      the number of structures to be generated
      See Also:

    • hasMoreStructures

      public boolean hasMoreStructures()
      Returns true if there are more structures.
      Returns:
      true if there are more structures

    • getNextStructure

      public Molecule getNextStructure()
      Returns the next enumerated structure, or null if no more structures.
      Returns:
      the sructure

    • getNextAromatizedStructure

      public Molecule getNextAromatizedStructure()
      Returns the next enumerated structure. The structure is returned in aromatized form.
      Returns:
      the structure

    • getStructures

      public Molecule[] getStructures() throws PluginException
      Returns the enumerated structures.
      Returns:
      the enumerated structures
      Throws:
      PluginException - if too many structures

    • getAromatizedStructures

      public Molecule[] getAromatizedStructures() throws PluginException
      Returns the enumerated structures in aromatized form.
      Returns:
      the enumerated structures in aromatized form
      Throws:
      PluginException - if too many structures

    • getResultSource

      public PluginMDocSource getResultSource() throws PluginException
      Returns the result as a document source object. This is useful for displaying the molecules in a viewer dynamically as they become available instead of collecting all results before display.
      Overrides:
      getResultSource in class CalculatorPlugin
      Returns:
      the document source interface
      Throws:
      PluginException - on error
      Since:
      Marvin 5.0

    • getResultTypes

      public Object[] getResultTypes()
      Returns the result types.
      Overrides:
      getResultTypes in class CalculatorPlugin
      Returns:
      the result types

    • getResultDomain

      public int getResultDomain(Object type)
      Returns the calculation domain.
      Overrides:
      getResultDomain in class CalculatorPlugin
      Parameters:
      type - is the result type
      Returns:
      the calculation domain
      See Also:

    • getResultCount

      public int getResultCount(Object type)
      Returns the number of result items for the given result key.
      Overrides:
      getResultCount in class CalculatorPlugin
      Parameters:
      type - is the result type
      Returns:
      the number of result items
      See Also:

    • getTypeString

      public String getTypeString(Object type)
      Returns a string representation of the given type.
      Overrides:
      getTypeString in class CalculatorPlugin
      Parameters:
      type - is the type object
      Returns:
      the type string

    • getResult

      public Object getResult(Object type, int index) throws PluginException
      Returns the result item for the specified key and index.
      Overrides:
      getResult in class CalculatorPlugin
      Parameters:
      type - is the result type
      index - is the result index
      Returns:
      the result item for the specified key and index
      Throws:
      PluginException - if the result cannot be returned
      See Also:

    • getResult

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) public Object getResult(Object type, String arg) throws PluginException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Some implementations of this method modify the state of the plugin, which is a very confusing behavior, so the method is now deprecated and should no longer be used. If you used this method with an index argument, parse the index instead, and call getResult(Object, int). Otherwise, call the appropriate setter method of the plugin to configure it with the argument, and call getResult(Object, int) with a 0 index.
      Returns the enumerated structures. For internal use only.
      Overrides:
      getResult in class CalculatorPlugin
      Parameters:
      type - is the result type ("structures")
      arg - is the atom string as a '-'-separated list
      Returns:
      the enumerated structures
      Throws:
      PluginException - on error
      See Also:

    • getResultAsString

      public String getResultAsString(Object type, int index, Object result) throws PluginException
      Returns the specified result in String format.
      Overrides:
      getResultAsString in class CalculatorPlugin
      Parameters:
      type - is the result type
      index - is the result index
      result - is the result item
      Returns:
      the specified result in String format
      Throws:
      PluginException - if an invalid result item is given

    • getRemark

      public String getRemark()
      Returns a warning message in case of arithmetical overflow (the number of enumerated structures exceeds Long.MAX_VALUE), null otherwise.
      Overrides:
      getRemark in class CalculatorPlugin
      Returns:
      a warning message if there are no tautomers

    • getLibrarySizeString

      public String getLibrarySizeString() throws PluginException
      Returns the display string representation of the Markush library size (number of all enumerated structures). It can be of two different forms: exact count with thousands separator for relative small values (e.g. 1,234,567) or "~10^x" for large values. If the count is approximate, then the returned string always starts with "~".

      No arithmetic overflow can occur because counts in BigInteger.

      Note: run() need not be called before using this function.

      Returns:
      display string representation of the library size or null in case of random enumeration.
      Throws:
      PluginException - on expansion error
      See Also:

    • getResultMolecule

      public Molecule getResultMolecule() throws PluginException
      Returns the result molecule for display. Atomic results are stored in atom extra labels (MolAtom.getExtraLabel()). Molecular results are stored in molecule properties with keys being the result types (MPropHandler.convertToString(MPropertyContainer, String)).
      Overrides:
      getResultMolecule in class CalculatorPlugin
      Returns:
      the result molecule
      Throws:
      PluginException - on error
      Since:
      Marvin 4.0