Package chemaxon.sss.search

Class Search

java.lang.Object
chemaxon.sss.search.Search
All Implemented Interfaces:
SearchConstants, StereoConstants
Direct Known Subclasses:
MolSearch
@PublicApi public abstract class Search extends Object implements StereoConstants, SearchConstants
Abstract base class of all structural search classes.

  • Field Details

    • searchOptions

      protected final MolSearchOptions searchOptions
      Object to store all search parameters.

    • preMatchMap

      protected Map<Integer,Integer> preMatchMap
      Map for storing pre-match data. Keys are query atom indexes, values are target atom indexes.

    • MRV_OUTPUT_LEVEL

      public static final System.Logger.Level MRV_OUTPUT_LEVEL
      MRV format of the query and target is logged at this level.

  • Constructor Details

    • Search

      public Search()

  • Method Details

    • setTarget

      public abstract void setTarget(Molecule mol)
      Specifies the target molecule.

      Note: If the molecule is changed, it will need to be reset for the searcher.

      Parameters:
      mol - the possibly standardized target molecule. See note on aromatic bonds

    • setTarget

      public abstract void setTarget(Molecule mol, int[] exclude)
      Specifies the target molecule with excluded atoms. Excluded atoms are not used during the search procedure. Atoms connected to excluded ones keep their stereo features.

      Note: If the molecule is changed, it will need to be reset for the searcher.

      Parameters:
      mol - the standardized target molecule. See note on aromatic bonds
      exclude - index of target atoms to exclude from search

    • getTarget

      public abstract Molecule getTarget()
      Retrieves the target molecule.
      Returns:
      the target molecule

    • setQuery

      public abstract void setQuery(Molecule mol)
      Specifies the query structure to search for. Note: If the molecule is changed, it will need to be reset for the searcher.
      Parameters:
      mol - the standardized query structure. See note on aromatic bonds

    • setQuery

      public abstract void setQuery(Molecule mol, int[] exclude)
      Specifies the query structure to search for. Excluded atoms are not used during the search procedure. Atoms connected to excluded ones keep their stereo features. Note: If the molecule is changed, it will need to be reset for the searcher.
      Parameters:
      mol - the standardized query structure. See note on aromatic bonds
      exclude - index of atoms to exclude from search

    • getQuery

      public abstract Molecule getQuery()
      Retrieves the query structure.
      Returns:
      the query structure

    • isMatching

      public abstract boolean isMatching() throws SearchException
      Checks if the query structure matches the target structure with respect to the search options.
      Returns:
      true if a match is found.
      Throws:
      SearchException - when an error is encountered.
      See Also:

    • findFirst

      public final int[] findFirst() throws SearchException
      Looks for the first matching pattern in the target molecule. If the search object was previously used, this method re-initializes the search process, and starts returning the hits from the beginning.
      Returns:
      an array containing the atom indexes of the target atoms that match the query atoms (in the order of the appropriate query atoms) or null if there are no hits. See SearchHit.getSingleHit() for the description of special atom indexes.
      Throws:
      SearchException - when an error is encountered.
      See Also:

    • findNext

      public final int[] findNext() throws SearchException
      Looks for the next matching pattern in the target molecule. If the search object was not used previously, it also initializes the search. (So findFirst() call is not necessary prior to a findNext() call.)
      Returns:
      an array containing the atom indexes of the target atoms that match the query atoms (in the order of the appropriate query atoms) or null if there are no more hits. See SearchHit.getSingleHit() for the description of special atom indexes.
      Throws:
      SearchException - when an error is encountered.
      See Also:

    • findAll

      public final int[][] findAll() throws SearchException
      Looks for all matching patterns in the molecule.
      Returns:
      an array containing the matches as arrays or null if there are no hits. The match arrays contain the atom indexes of the target atoms that match the query atoms (in the order of the appropriate query atoms). See SearchHit.getSingleHit() for the description of special atom indexes.
      Throws:
      SearchException - when an error is encountered.
      See Also:

    • findFirstGroup

      public final int[][] findFirstGroup() throws SearchException
      Returns the group hit corresponding to the first hit.

      See SearchHit.getGroupHit() for more information on group hits.

      Returns:
      the group hit corresponding to the first hit
      Throws:
      SearchException - when an error is encountered.
      Since:
      JChem 5.3
      See Also:

    • findNextGroup

      public final int[][] findNextGroup() throws SearchException
      Returns the group hit corresponding to the next hit.

      See SearchHit.getGroupHit() for more information on group hits.

      Returns:
      the group hit corresponding to the next hit
      Throws:
      SearchException - when an error is encountered.
      Since:
      JChem 5.3
      See Also:

    • findAllGroups

      public final int[][][] findAllGroups() throws SearchException
      Returns the group hits corresponding to all hits.

      See SearchHit.getGroupHit() for more information on group hits.

      Returns:
      the group hits corresponding to all hits, each element of the array is a group hit glove array
      Throws:
      SearchException - when an error is encountered.
      Since:
      JChem 5.3
      See Also:

    • findFirstHit

      protected abstract SearchHit findFirstHit() throws SearchException
      Looks for the first matching pattern in the target molecule. If the search object was previously used, this method re-initializes the search process, and starts returning the hits from the beginning.

      See SearchHit for more information.

      Returns:
      the search hit or null if there is not hit
      Throws:
      SearchException - when an error is encountered.
      Since:
      JChem 5.4
      See Also:

    • findNextHit

      protected abstract SearchHit findNextHit() throws SearchException
      Searches for the next hit. If the search object was not used previously, it also initializes the search. (So findFirstHit() call is not necessary prior to a findNextHit() call.)

      See SearchHit for more information.

      Returns:
      the next search hit or null if there is no more hit
      Throws:
      SearchException - when an error is encountered.
      Since:
      JChem 5.4
      See Also:

    • findAllHits

      protected SearchHit[] findAllHits() throws SearchException
      Looks for all matching patterns in the molecule.

      See SearchHit for more information.

      Returns:
      the search hits or null if there are no hits.
      Throws:
      SearchException - when an error is encountered.
      Since:
      JChem 5.4
      See Also:

    • addMatch

      public void addMatch(int[] queryAtoms, int[] targetAtoms, int length)
      Specifies extra prerequisites of the structure search that queryAtoms[0] must match to targetAtoms[0] only AND queryAtoms[1] must match to targetAtoms[1], etc. If this is impossible, the search methods will report no matching. The use of this method makes the search more effective than checking the hits afterwards.

      Several addMatch() calls represent conditions connected by boolean operator AND.

      The effect of all addMatch() calls can be canceled by clearMatch().

      Parameters:
      queryAtoms - the query atom indexes
      targetAtoms - the target atom indexes
      length - the length for which queryAtoms/targetAtoms should be interpreted.
      Since:
      JChem 2.2

    • clearMatch

      public void clearMatch()
      Clears the extra prerequisites of the structure search specified using addMatch calls.
      Since:
      JChem 2.2

    • isMatchCountInRelation

      public final boolean isMatchCountInRelation(String relation, int hitLimit) throws SearchException
      Decides questions like "does the query match the target at least 3 times", "[] up to 5 times", "[] exactly once". Makes this efficiently, which means it only searches for the number of hits necessary to decide the question.

      Example:

      isMatchCountInRelation("<", 2) - true if the query can be found in the target less than two times.

      Parameters:
      relation - The relational operation of the question. This operation will be used to compare the number of hits to hitLimit. Available values:
      "=" - tests equality to hitLimit.
      "<" - returns true if the number of found hits is less than hitLimit.
      "<=" - less than or equality
      ">" - greater than
      ">=" - greater than or equality
      hitLimit - The limit for the number of hits.
      Returns:
      "actual number of hits (of query in target)" <relation> hitLimit
      Throws:
      SearchException - if encountered during the search.
      See Also:

    • isMatchCountInRelation

      @Beta public static boolean isMatchCountInRelation(String relation, int hitLimit, int foundHits) throws SearchException
      Throws:
      SearchException

    • isMatchCountBetween

      public final boolean isMatchCountBetween(int hitLimitLow, boolean isLowerLimitIncluded, int hitLimitHigh, boolean isHigherLimitIncluded) throws SearchException
      Decides questions like "does the query match the target between 2 and 5 times (inclusively)" Makes this efficiently, which means it only searches for the number of hits necessary to decide the question.

      Example:

      isMatchCountBetween(2, true, 4, true) - true if the query can be found in the target exactly 2, 3 or 4 times.

      isMatchCountBetween(2, false, 4, false) - true if the query can be found in the target exactly 3 times.

      Parameters:
      hitLimitLow - The lower limit for the number of hits.
      isLowerLimitIncluded - If true, equality is allowed with hitLimitLow.
      hitLimitHigh - The upper limit for the number of hits. If you pass Integer.MAX_VALUE, it will be treated as infinity. (I.e. only the lower limit is applied.)
      isHigherLimitIncluded - If true, equality is allowed with hitLimitHigh.
      Returns:
      Whether the "actual number of hits (of query in target)" is between hitLimitLow and hitLimitHigh, inclusively.
      Throws:
      SearchException - if encountered during the search.
      See Also:

    • getMatchCount

      public final int getMatchCount() throws SearchException
      The number of times the query molecule appears in the target molecule.

      If you would like to decide a simple relation regarding this number, you should consider method isMatchCountInRelation( String, int), because it is more efficient than this method.

      Returns:
      the above occurrence number.
      Throws:
      SearchException - If encountered during the search.
      See Also:

    • isVerbose

      public boolean isVerbose()
      For debugging purposes only.
      Returns:
      true if verbose mode is on.

    • setVerbose

      public void setVerbose(boolean verbose)
      For debugging purposes only.
      Parameters:
      verbose - enables or disables verbose mode.

    • stop

      public abstract void stop()
      Tries to stop the running search as fast as possible. (E.g. used in another thread.)
      Since:
      JChem 3.0

    • getSearchOptions

      public MolSearchOptions getSearchOptions()
      Returns the SearchOptions object associated with this Search object. The object returned is linked with this Search object, so modifications in the returned SearchOptions object will also change the behavior of this Search object!
      Returns:
      the current search settings as a SearchOptions object.
      Since:
      JChem 5.0
      See Also:

    • setSearchOptions

      public void setSearchOptions(SearchOptions options)
      Sets search options. This function makes a copy of the given search options object, thus modification of the original object does not affect future searches unless this method is called again.
      Parameters:
      options - search options. A copy of this object will be stored.
      Since:
      JChem 5.0
      See Also:

    • getQueryToPrint

      protected Molecule getQueryToPrint()
      For internal purposes only.
      Returns:
      the query to be displayed for debug purposes only.

    • getTargetToPrint

      protected Molecule getTargetToPrint()
      For internal purposes only.
      Returns:
      the target to be displayed for debug purposes only.

    • getTargetAsString

      public static String getTargetAsString(Molecule tToPrint)
      For internal purposes only.
      Parameters:
      tToPrint - the molecule to be flattened to a string array
      Returns:
      the target to be displayed for debug purposes only.

    • getQueryAsString

      protected static String getQueryAsString(Molecule qToPrint)
      For internal purposes only.
      Parameters:
      qToPrint - the molecule to be flattened to a string array
      Returns:
      the query to be displayed for debug purposes only.