chemaxon.sss.search
Class MolSearch

java.lang.Object
  chemaxon.sss.search.Search
      chemaxon.sss.search.MolSearch

All Implemented Interfaces:

chemaxon.license.Licensable, SearchConstants, StereoConstants, chemaxon.util.search.MolSearcher

Direct Known Subclasses:

StandardizedMolSearch

public class MolSearch
extends Search
implements chemaxon.license.Licensable

Atom-by-atom structure search.

Features:

• Determines whether a target structure contains a query structure
• Specifies the matching atoms in the target structure in order of the corresponding query atoms. (When the returning match is larger than the original query atoms, eg. in link node queries, the extra target atom indexes appear at the end.)
• Generic query atoms (Any, Q), atom properties (A , a, R<n>, H<n> etc.) , atom lists (e.g.:"[C,N,F]"), generic bonds (any bond) are evaluated. For full details of JChem substructure features, see the JChem Query Guide
• Stereo specific search: chiral and cis/trans stereo isomers are recognized.
• R-groups: If the query is an RgMolecule with R-groups defined, R-group search is performed. In this case hits of the root atoms are returned.
  Note: Nested R-groups are not supported yet. Specifying excluded atoms for setQuery() is not implemented yet for RgMolecules either.
• Filtering expression: filters search hits by chemical feasibility. For details of the expression syntax, see the Chemical Terms Evaluator Guide.

For correct behaviour of the MolSearch class, both the query and target molecules has to be standardized prior to searching. See note on aromatic bonds Alternatively, you can use the StandardizedMolSearch class.

Example:

  import chemaxon.sss.search.MolSearch;
  import chemaxon.sss.search.SearchException;
  import chemaxon.util.MolHandler;
  import chemaxon.formats.MolInputStream;
  import chemaxon.formats.MolImporter;
  import chemaxon.struc.Molecule;

  import java.io.BufferedInputStream;
  import java.io.FileInputStream;
  import java.io.IOException;

  public class searchTest {

      public static void main(String[] args) {
          try {
              MolSearch s = new MolSearch();

              // queryMode = true forces string to be imported as SMARTS
              // If SMILES import needed, set queryMode = false.
              MolHandler mh1 = new MolHandler("c1ccccc1Cl", true);
              
              // The query molecule must be aromatized if it uses the
              // alternating single/double bonds for the description of
              // aromaticity.
              mh1.aromatize();
              s.setQuery(mh1.getMolecule());

              // use Molfile molecule as target
              BufferedInputStream tis=null;
              tis = new BufferedInputStream(
                              new FileInputStream("target.mol"));
              MolInputStream tmis = new MolInputStream(tis);
              MolImporter tmolimp = new MolImporter(tmis);
              Molecule target = tmolimp.read();

              target.aromatize(true);
              s.setTarget(target);

              // search all matching substructures and print hits
              int[][] hits=null;

              hits = s.findAll();
              if(hits==null)
                  System.out.println("No hits");
              else  {
                  for(int i=0; i < hits.length; i++) {
                      System.out.print("Hit " + (i+1) + ":  ");
                      int[] hit = hits[i];
                      for(int j=0; j < hit.length; j++) {
                          System.out.print(hit[j]+" ");
                      }
                      System.out.println();
                  }
              }//end else
          } catch (IOException e) {
              e.printStackTrace();
              System.exit(1);
          } catch (SearchException e) {
              e.printStackTrace();
              System.exit(1);
          }//end catch
      }//end main
  }//end searchTest
 

Author:

Tamas Karpati, Ferenc Csizmadia, Gyorgy Pirok, Szilard Dorant, Szabolcs Csepregi

Field Summary

protected boolean	isOrigTargetMayBeMarkush FS#9166 Should be set to 'false' to indicate that any bonds (Markush components) occurred only after generating generic tautomer of target.
protected boolean	isQueryStandardizable
protected boolean	isTargetStandardizable

Fields inherited from class chemaxon.sss.search.Search

MRV_OUTPUT_LEVEL, preMatchLength, preMatchQueryAtoms, preMatchTargetAtoms, searchOptions

Fields inherited from interface chemaxon.struc.StereoConstants

ANTI, ATOMSTEREO_EITHER, ATOMSTEREO_MASK, ATOMSTEREO_NONE, ATOMSTEREO_SPECIFIC, CHIRALITY_M, CHIRALITY_MASK, CHIRALITY_P, CHIRALITY_r, CHIRALITY_R, CHIRALITY_s, CHIRALITY_S, CHIRALITYSUPPORT_ALL, CHIRALITYSUPPORT_NONE, CHIRALITYSUPPORT_SELECTED, CIS, CTUMASK, CTUNKNOWN, CTUNSPEC, DBS_ALL, DBS_MARKED, DBS_NONE, ENDO, EXO, PARITY_ALLENE, PARITY_EITHER, PARITY_EVEN, PARITY_MASK, PARITY_ODD, PARITY_TETRAHEDRAL, PARITY_UNSPEC, STGRP_ABS, STGRP_AND, STGRP_NONE, STGRP_OR, SYN, TRANS

Fields inherited from interface chemaxon.sss.SearchConstants

ABS_STEREO_ALWAYS_ON, ABS_STEREO_CHIRAL_FLAG, ABS_STEREO_TABLE_OPTION, ATTACHED_DATA_MATCH_EXACT, ATTACHED_DATA_MATCH_GENERAL, ATTACHED_DATA_MATCH_IGNORE, CHARGE_MATCHING_DEFAULT, CHARGE_MATCHING_EXACT, CHARGE_MATCHING_IGNORE, DEFAULT_DISSIMILARITY_THRESHOLD, DEFAULT_SEARCHTYPE, DISSIMILARITY_PROPERTY_NAME, DUPLICATE, FULL, FULL_FRAGMENT, HCOUNT_MATCHING_AUTO, HCOUNT_MATCHING_EQUAL, HCOUNT_MATCHING_GREATER_OR_EQUAL, HIT_EXCLUDEDQ, HIT_LP, HIT_MULTICENTER, HIT_NON_R, HIT_ORDERING_NONE, HIT_ORDERING_UNDEF_R_MATCHING_GROUP_FIRST, HIT_R, HIT_R_EMPTY_MATCH, HIT_UNMAPABLE, IMPLICIT_H_MATCHING_DEFAULT, IMPLICIT_H_MATCHING_DISABLED, IMPLICIT_H_MATCHING_ENABLED, IMPLICIT_H_MATCHING_IGNORE, ISOTOPE_MATCHING_DEFAULT, ISOTOPE_MATCHING_EXACT, ISOTOPE_MATCHING_IGNORE, MARKUSH_AROM_FINAL_CHECK, MARKUSH_AROM_NO_FINAL_CHECK, MARKUSH_AROM_OFF, MARKUSH_HIT_INNER, MARKUSH_HIT_ORIGINAL, MARKUSH_MCS, MATCH_COUNT_BETWEEN, MATCH_COUNT_RELATION, NO_ABAS, NO_SCREEN, RADICAL_MATCHING_DEFAULT, RADICAL_MATCHING_EXACT, RADICAL_MATCHING_IGNORE, SEARCH_MODE_NAMES, SEARCH_OPTIONS_LENGTH, SIMILARITY, STEREO_DIASTEREOMER, STEREO_ENANTIOMER, STEREO_EXACT, STEREO_IGNORE, STEREO_MODEL_COMPREHENSIVE, STEREO_MODEL_DEFAULT, STEREO_MODEL_GLOBAL, STEREO_MODEL_LOCAL, STEREO_SPECIFIC, SUBSTRUCTURE, SUPERSTRUCTURE, TAUTOMER_SEARCH_DEFAULT, TAUTOMER_SEARCH_OFF, TAUTOMER_SEARCH_ON, UNDEF_R_MATCHING_ALL, UNDEF_R_MATCHING_GROUP, UNDEF_R_MATCHING_GROUP_H, UNDEF_R_MATCHING_GROUP_H_EMPTY, UNDEF_R_MATCHING_UNDEF_R, VAGUE_BOND_DEFAULT, VAGUE_BOND_LEVEL_HALF, VAGUE_BOND_LEVEL1, VAGUE_BOND_LEVEL2, VAGUE_BOND_LEVEL3, VAGUE_BOND_LEVEL4, VAGUE_BOND_OFF

Constructor Summary

MolSearch()
Constructs a MolSearch object.

Method Summary

void	addComparator(MolComparator mc) Add a comparator to the search object.
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.
void	addMatch(int queryAtom, int targetAtom) Specifies an extra prerequisite of the structure search that queryAtom must match to targetAtom only.
static void	checkFilter(java.lang.String filteringExpression) Checks the syntax of the filtering expression.
static void	checkFilter(java.lang.String filteringExpression, java.io.File config) Checks the syntax of the filtering expression.
void	clearComparators() Delete all comparator from the search object.
void	clearMatch() Clears the extra prerequisites of the structure search specified using addMatch calls.
protected boolean	filter(SearchHit hit) Returns true if the hit is accepted by the filteringExpression.
SearchHit[]	findAllHits() Looks for all matching patterns in the molecule.
SearchHit	findFirstHit() Looks for the first matching pattern in the target molecule.
SearchHit	findNextHit() Looks for the next matching pattern in the target molecule.
java.lang.String	getFilter() Returns the filtering expression.
Molecule	getMatchingQuery() Returns the most specific enumeration of the query which produced the hit vector of the last findNext(), findFirst() or findAll() result.
Molecule	getMatchingTarget() Returns the most specific enumeration of the target which produced the hit vector of the last findNext(), findFirst() or findAll() result.
Molecule	getQuery() Retrieves the query structure stored in the MolSearch object.
Molecule	getTarget() Retrieves the target molecule to search in.
protected boolean	hasFilter() Returns true if filter is set.
protected boolean	hasHitFilter() Returns true if filter is set and references the hit, not only the query/target structures.
boolean	isLicensed() Gets whether searching is included in the user licence.
boolean	isMatching() Checks if the query structure matches a substructure in the molecule.
void	removeComparator(MolComparator mc) Delete a comparator from the search object.
void	setFilter(java.lang.String filteringExpression) Sets the filtering expression.
void	setFilterConfig(java.io.File config) Sets additional evaluator configuration for filtering expression evaluation.
void	setLicenseEnvironment(java.lang.String env) Set the license to be used by the search object.
void	setOrigTargetMayBeMarkush(boolean value) Only for internal use!
void	setQuery(Molecule mol) Specifies the query structure to search for.
void	setQuery(Molecule mol, int[] exclude) Specifies the query structure to search for.
void	setQuery(java.lang.String queryString) Specifies the query structure to search for in String format.
void	setSearchOptions(MolSearchOptions options) Sets search parameters.
void	setStandardizer(Standardizer st, boolean bq, boolean bt) Sets standardizer object of this MolSearch class, to be used for the query and target molecules, Chemical Terms configuration and re-standardization of query tautomers at tautomer searching.
void	setTarget(Molecule mol) Specifies the target molecule to search in.
void	setTarget(Molecule mol, int[] exclude) Specifies the target molecule to search in.
void	stop() Tries to stop the running search as fast as possible.

Methods inherited from class chemaxon.sss.search.Search

areMatchingBondTypes, areMatchingBondTypes, findAll, findAllGroups, findFirst, findFirstGroup, findNext, findNextGroup, getAtomStereo, getMatchCount, getQueryAsString, getQueryToPrint, getSearchOptions, getTargetAsString, getTargetToPrint, isMatchCountBetween, isMatchCountInRelation, isVerbose, logException, setSearchOptions, setVerbose

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

isQueryStandardizable

protected boolean isQueryStandardizable

isTargetStandardizable

protected boolean isTargetStandardizable

isOrigTargetMayBeMarkush

protected boolean isOrigTargetMayBeMarkush

FS#9166 Should be set to 'false' to indicate that any bonds (Markush components) occurred only after generating generic tautomer of target. Is used only in selectSearchMode()!

Constructor Detail

MolSearch

public MolSearch()

Constructs a MolSearch object.

Method Detail

setTarget

public void setTarget(Molecule mol)

Specifies the target molecule to search in.
Note: If the molecule is changed it will need to be reset for the searcher.

Specified by:

setTarget in interface chemaxon.util.search.MolSearcher

Specified by:

setTarget in class Search

Parameters:

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

setTarget

public void setTarget(Molecule mol,
                      int[] exclude)

Specifies the target molecule to search in. 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.

Specified by:

setTarget in class Search

Parameters:

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

exclude - index of target atoms to exclude from search

getTarget

public Molecule getTarget()

Retrieves the target molecule to search in.

Specified by:

getTarget in class Search

Returns:

the Molecule to search in

setQuery

public 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.

Specified by:

setQuery in interface chemaxon.util.search.MolSearcher

Specified by:

setQuery in class Search

Parameters:

mol - the standardized query structure. See note on aromatic bonds

setQuery

public 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.

Specified by:

setQuery in class Search

Parameters:

mol - the standardized query structure. See note on aromatic bonds

exclude - index of atoms to exclude from search

getQuery

public Molecule getQuery()

Retrieves the query structure stored in the MolSearch object.

Specified by:

getQuery in class Search

Returns:

Molecule to search for

setQuery

public void setQuery(java.lang.String queryString)

Specifies the query structure to search for in String format.

Parameters:

queryString - the standardized query structure. See note on aromatic bonds

setStandardizer

public void setStandardizer(Standardizer st,
                            boolean bq,
                            boolean bt)

Sets standardizer object of this MolSearch class, to be used for the query and target molecules, Chemical Terms configuration and re-standardization of query tautomers at tautomer searching. Default is no standardization, but query standardization is always switched on at tautomer search.

Parameters:

st - Standardizer object. null means default aromatization. WARNING: Standardization that changes atom indexes are not supported!

bq - if true, standardization is done on query.

bt - if true, standardization is done on target.

Since:

JChem 3.2

setFilterConfig

public void setFilterConfig(java.io.File config)
                     throws chemaxon.sss.search.SearchException

Sets additional evaluator configuration for filtering expression evaluation. If not set then the default configuration is used only.

Parameters:

config - the expression evaluator config XML

Throws:

chemaxon.sss.search.SearchException

Since:

JChem 3.2

setFilter

public void setFilter(java.lang.String filteringExpression)
               throws chemaxon.sss.search.SearchException

Sets the filtering expression. For details of the expression syntax, see the Chemical Terms Evaluator Guide and its short reference. Use specific functions from the search context to refer to the query and the target molecules, the search hit array and its elements.

Parameters:

filteringExpression - the filtering expression

Throws:

chemaxon.sss.search.SearchException

Since:

JChem 3.0

getFilter

public java.lang.String getFilter()

Returns the filtering expression.

Returns:

the filtering expression

setSearchOptions

public void setSearchOptions(MolSearchOptions options)

Sets search parameters.

Parameters:

options - search options. Will be copied, modification of the original object does not affect future searches unless this method is called again.

Since:

JChem 5.0

See Also:

Search.getSearchOptions()

getMatchingQuery

public Molecule getMatchingQuery()

Returns the most specific enumeration of the query which produced the hit vector of the last findNext(), findFirst() or findAll() result.

Overrides:

getMatchingQuery in class Search

Returns:

The enumerated query or null if the query is not initialized yet or no searching operations were performed. In case of superstructure search, it returns the query (larger) molecule.

Since:

JChem 3.1.2

See Also:

getMatchingTarget()

getMatchingTarget

public Molecule getMatchingTarget()

Returns the most specific enumeration of the target which produced the hit vector of the last findNext(), findFirst() or findAll() result. (May only be relevant for superstructure search.)

Returns:

The enumerated target or null if the target is not initialized yet or no searching operations were performed. In case of superstructure search, it returns the target (smaller) molecule.

Since:

JChem 5.0

See Also:

getMatchingQuery()

addComparator

public void addComparator(MolComparator mc)

Add a comparator to the search object.

Parameters:

mc - comparator add

See Also:

MolComparator, removeComparator(MolComparator), clearComparators(), SearchOptions.addUserComparator(MolComparator)

removeComparator

public void removeComparator(MolComparator mc)

Delete a comparator from the search object.

Parameters:

mc - comparator to be removed

See Also:

MolComparator, addComparator(MolComparator), clearComparators(), SearchOptions.deleteUserComparator(MolComparator)

clearComparators

public void clearComparators()

Delete all comparator from the search object.

See Also:

MolComparator, addComparator(MolComparator), clearComparators(), SearchOptions.deleteAllUserComparators()

hasFilter

protected boolean hasFilter()

Returns true if filter is set.

Returns:

true if filter is set

hasHitFilter

protected boolean hasHitFilter()

Returns true if filter is set and references the hit, not only the query/target structures.

Returns:

true if filter references the hit

isMatching

public boolean isMatching()
                   throws chemaxon.sss.search.SearchException

Checks if the query structure matches a substructure in the molecule.

Specified by:

isMatching in class Search

Returns:

true if the query was found.

Throws:

chemaxon.sss.search.SearchException

See Also:

Search.findFirst(), Search.findNext(), Search.findAll()

findFirstHit

public SearchHit findFirstHit()
                       throws chemaxon.sss.search.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.

Specified by:

findFirstHit in class Search

Returns:

the search hit or null if there is not hit

Throws:

chemaxon.sss.search.SearchException

Since:

JChem 5.4

See Also:

findNextHit(), findAllHits(), Search.findNext(), Search.findAll(), Search.findFirstGroup(), Search.findNextGroup(), Search.findAllGroups(), isMatching(), getMatchingQuery()

findNextHit

public SearchHit findNextHit()
                      throws chemaxon.sss.search.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 findFirstHit() call is not necessary prior to a findNextHit() call.)

Specified by:

findNextHit in class Search

Returns:

the next search hit or null if there is no more hit

Throws:

chemaxon.sss.search.SearchException

Since:

JChem 5.4

See Also:

findFirstHit(), findAllHits(), Search.findFirst(), Search.findAll(), Search.findFirstGroup(), Search.findNextGroup(), Search.findAllGroups(), isMatching(), getMatchingQuery()

findAllHits

public SearchHit[] findAllHits()
                        throws chemaxon.sss.search.SearchException

Looks for all matching patterns in the molecule.

Overrides:

findAllHits in class Search

Returns:

the search hits or null if there are no hits.

Throws:

chemaxon.sss.search.SearchException

Since:

JChem 5.4

See Also:

findFirstHit(), findNextHit(), isMatching(), Search.findFirst(), Search.findNext(), Search.findFirstGroup(), Search.findNextGroup(), Search.findAllGroups()

stop

public void stop()

Tries to stop the running search as fast as possible. (E.g. used in another thread.)

Specified by:

stop in class Search

Since:

JChem 3.0

addMatch

public void addMatch(int queryAtom,
                     int targetAtom)

Specifies an extra prerequisite of the structure search that queryAtom must match to targetAtom only. 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().

Overrides:

addMatch in class Search

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().

Overrides:

addMatch in class Search

Since:

JChem 2.2

clearMatch

public void clearMatch()

Clears the extra prerequisites of the structure search specified using addMatch calls.

Overrides:

clearMatch in class Search

Since:

JChem 2.2

filter

protected boolean filter(SearchHit hit)
                  throws chemaxon.sss.search.SearchException

Returns true if the hit is accepted by the filteringExpression. If the filteringExpression is not set or the hit is null then also returns true.

Parameters:

hit - is the search hit

Returns:

true if the hit is accepted

Throws:

chemaxon.sss.search.SearchException

checkFilter

public static void checkFilter(java.lang.String filteringExpression)
                        throws chemaxon.nfunk.jep.ParseException

Checks the syntax of the filtering expression. For internal use only.

Parameters:

filteringExpression - the expression to be checked

Throws:

chemaxon.nfunk.jep.ParseException - if the syntax is not sorrect

Since:

JChem 3.0

checkFilter

public static void checkFilter(java.lang.String filteringExpression,
                               java.io.File config)
                        throws chemaxon.nfunk.jep.ParseException

Checks the syntax of the filtering expression. For internal use only.

Parameters:

filteringExpression - the expression to be checked

config - the expression evaluator config XML

Throws:

chemaxon.nfunk.jep.ParseException - if the syntax is not sorrect

Since:

JChem 3.0

setOrigTargetMayBeMarkush

public void setOrigTargetMayBeMarkush(boolean value)

Only for internal use!
Used for indicating that any bonds appeared after generating the generic tautomer of the target.

Parameters:

value - if true indicates that any bonds appeared only after tautomer generation.

setLicenseEnvironment

public void setLicenseEnvironment(java.lang.String env)

Set the license to be used by the search object.

Specified by:

setLicenseEnvironment in interface chemaxon.license.Licensable

isLicensed

public boolean isLicensed()

Gets whether searching is included in the user licence.

Specified by:

isLicensed in interface chemaxon.license.Licensable

Returns:

true if searching is included in the license, false otherwise