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 Link icon

    • searchOptions Link icon

      protected final MolSearchOptions searchOptions
      Object to store all search parameters.

    • preMatchMap Link icon

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

    • MRV_OUTPUT_LEVEL Link icon

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

  • Constructor Details Link icon

    • Search Link icon

      public Search()

  • Method Details Link icon

    • setTarget Link icon

      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 Link icon

      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 Link icon

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

    • setQuery Link icon

      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 Link icon

      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 Link icon

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

    • isMatching Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

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

    • isMatchCountInRelation Link icon

      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 Link icon

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

    • isMatchCountBetween Link icon

      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 Link icon

      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 Link icon

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

    • setVerbose Link icon

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

    • stop Link icon

      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 Link icon

      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 Link icon

      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 Link icon

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

    • getTargetToPrint Link icon

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

    • getTargetAsString Link icon

      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 Link icon

      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.