MolSearch (JChem Base API documentation (c) 1998-2021 ChemAxon Ltd.)

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

All Implemented Interfaces:: chemaxon.license.Licensable, SearchConstants, StereoConstants, SimpleSearcher

Direct Known Subclasses:: StandardizedMolSearch

@PublicAPI
public class MolSearch
extends Search
implements chemaxon.license.Licensable, SimpleSearcher

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

Please note that similarity search is not supported in MolSearch.

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:: JChem Base team, Tamas Karpati, Ferenc Csizmadia, Gyorgy Pirok, Szilard Dorant, Szabolcs Csepregi, Robert Wagner, Nore Mate, Tamas Csizmazia, Vencel Bors, Zoltan Nagy, Gabor Hornyak, Peter Kovacs (pkovacs84)

Field Summary

Fields
Modifier and Type	Field and Description
`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.

Fields inherited from class chemaxon.sss.search.Search
MRV_OUTPUT_LEVEL, preMatchMap, 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_ALL_POSSIBLE, CHIRALITYSUPPORT_NONE, CHIRALITYSUPPORT_SELECTED, CIS, CIS_TRANS, CTUMASK, CTUNKNOWN, CTUNSPEC, DBS_ALL, DBS_MARKED, DBS_NONE, ENDO, EXO, PARITY_ALLENE, PARITY_EITHER, PARITY_EVEN, PARITY_MASK, PARITY_NONE, 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, ATTACHMENT_ATOM, ATTACHMENT_LABEL, ATTACHMENT_MAP, ATTACHMENT_NONE, ATTACHMENT_POINT, ATTACHMENT_RLABEL, 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_HIT_INNER, MARKUSH_HIT_ORIGINAL, MATCH_COUNT_BETWEEN, MATCH_COUNT_RELATION, NO_ABAS, NO_SCREEN, POSITION_ON_0TH_HEAVY_ATOM, RADICAL_MATCHING_DEFAULT, RADICAL_MATCHING_EXACT, RADICAL_MATCHING_IGNORE, SEARCH_MODE_NAMES, SEARCH_TYPE_NAMES, 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, TAUTOMER_SEARCH_ON_IGNORE_TAUTOMERSTEREO, 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

Constructors
Constructor and Description

MolSearch()
Constructs a MolSearch object.

Constructors
Constructor and Description
`MolSearch()` Constructs a MolSearch object.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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 queryAtomIndex, int targetAtomIndex)` Adds a fixed matching between the given query and target atoms.
`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.
`SearchHit[]`	`findAllHits()` Looks for all matching patterns in the molecule.
`SearchHit`	`findFirstHit()` Looks for the first matching pattern in the target molecule.
`SearchHit`	`findNextHit()` Searches for the next hit.
`Molecule`	`getQuery()` Retrieves the query structure.
`protected chemaxon.sss.matcher.StructureMatcher`	`getSearcher()`
`Molecule`	`getTarget()` Retrieves the target molecule.
`boolean`	`isLicensed()`
`boolean`	`isMatching()` Checks if the query structure matches the target structure with respect to the search options.
`void`	`removeComparator(MolComparator mc)` Delete a comparator from the search object.
`void`	`setLicenseEnvironment(java.lang.String env)`
`void`	`setOrigTargetMayBeMarkush(boolean value)` Only for internal use! Used for indicating that any bonds appeared after generating the generic tautomer of the target.
`protected void`	`setParameters()`
`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 options.
`void`	`setStandardizer(Standardizer standardizer)` Sets the standardizer to be used for query and target molecules and re-standardization of query tautomers in case of tautomer substructure search.
`void`	`setTarget(Molecule mol)` Specifies the target molecule.
`void`	`setTarget(Molecule mol, int[] exclude)` Specifies the target molecule with excluded atoms.
`protected void`	`setTransformer(Transformer transformer)` Sets the `Transformer` to be used for query and target standardization.
`void`	`stop()` Tries to stop the running search as fast as possible.

Methods inherited from class chemaxon.sss.search.Search
findAll, findAllGroups, findFirst, findFirstGroup, findNext, findNextGroup, getMatchCount, getQueryAsString, getQueryToPrint, getSearchOptions, getTargetAsString, getTargetToPrint, isMatchCountBetween, isMatchCountInRelation, isMatchCountInRelation, isVerbose, setSearchOptions, setVerbose

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - 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)
```
    Description copied from class: Search
    
    Specifies the target molecule.
    Note: If the molecule is changed, it will need to be reset for the searcher.
    
    Specified by:
    
    setTarget in interface SimpleSearcher
    
    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)
```
    Description copied from class: Search
    
    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.
    
    Specified by:
    
    setTarget in interface SimpleSearcher
    
    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()
```
    Description copied from class: Search
    
    Retrieves the target molecule.
    
    Specified by:
    
    getTarget in class Search
    
    Returns:
    
    the target molecule
  - setQuery
```
public void setQuery(Molecule mol)
```
    Description copied from class: Search
    
    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 SimpleSearcher
    
    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)
```
    Description copied from class: Search
    
    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 interface SimpleSearcher
    
    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()
```
    Description copied from class: Search
    
    Retrieves the query structure.
    
    Specified by:
    
    getQuery in class Search
    
    Returns:
    
    the query structure
  - 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
  - setTransformer
```
protected final void setTransformer(Transformer transformer)
```
    Sets the Transformer to be used for query and target standardization. For internal use only.
    
    Parameters:
    
    transformer - the transformer
  - setStandardizer
```
public void setStandardizer(Standardizer standardizer)
```
    Sets the standardizer to be used for query and target molecules and re-standardization of query tautomers in case of tautomer substructure search.
    
    By default there is no standardization.
    
    Parameters:
    
    standardizer - the standardizer, null for no standardization
    
    Since:
    
    JChem 5.12
  - setSearchOptions
```
public void setSearchOptions(MolSearchOptions 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:
    
    Search.getSearchOptions()
  - addComparator
```
public void addComparator(MolComparator mc)
```
    Add a comparator to the search object.
    
    Parameters:
    
    mc - comparator to 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()
  - isMatching
```
public boolean isMatching()
                   throws SearchException
```
    Description copied from class: Search
    
    Checks if the query structure matches the target structure with respect to the search options.
    
    Specified by:
    
    isMatching in interface SimpleSearcher
    
    Specified by:
    
    isMatching in class Search
    
    Returns:
    
    true if a match is found.
    
    Throws:
    
    SearchException - when an error is encountered.
    
    See Also:
    
    Search.findFirstHit(), Search.findNextHit(), Search.findAllHits(), Search.getQuery()
  - findFirstHit
```
public SearchHit findFirstHit()
                       throws SearchException
```
    Description copied from class: Search
    
    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.
    
    Specified by:
    
    findFirstHit in class Search
    
    Returns:
    
    the search hit or null if there is not hit
    
    Throws:
    
    SearchException - when an error is encountered.
    
    See Also:
    
    Search.findNextHit(), Search.findAllHits(), Search.isMatching(), Search.getQuery(), Search.findNext(), Search.findAll(), Search.findFirstGroup(), Search.findNextGroup(), Search.findAllGroups()
  - findNextHit
```
public SearchHit findNextHit()
                      throws SearchException
```
    Description copied from class: Search
    
    Searches for the next hit. If the search object was not used previously, it also initializes the search. (So Search.findFirstHit() call is not necessary prior to a Search.findNextHit() call.)
    See SearchHit for more information.
    
    Specified by:
    
    findNextHit in interface SimpleSearcher
    
    Specified by:
    
    findNextHit in class Search
    
    Returns:
    
    the next search hit or null if there is no more hit
    
    Throws:
    
    SearchException - when an error is encountered.
    
    See Also:
    
    Search.findFirstHit(), Search.findAllHits(), Search.isMatching(), Search.getQuery(), Search.findFirst(), Search.findAll(), Search.findFirstGroup(), Search.findNextGroup(), Search.findAllGroups()
  - findAllHits
```
public SearchHit[] findAllHits()
                        throws SearchException
```
    Description copied from class: Search
    
    Looks for all matching patterns in the molecule.
    See SearchHit for more information.
    
    Overrides:
    
    findAllHits in class Search
    
    Returns:
    
    the search hits or null if there are no hits.
    
    Throws:
    
    SearchException - when an error is encountered.
    
    See Also:
    
    Search.findFirstHit(), Search.findNextHit(), Search.isMatching(), Search.findFirst(), Search.findNext(), Search.findFirstGroup(), Search.findNextGroup(), Search.findAllGroups()
  - stop
```
public void stop()
```
    Description copied from class: Search
    
    Tries to stop the running search as fast as possible. (E.g. used in another thread.)
    
    Specified by:
    
    stop in class Search
  - setParameters
```
protected void setParameters()
                      throws SearchException
```
    Throws:
    
    SearchException
  - getSearcher
```
protected final chemaxon.sss.matcher.StructureMatcher getSearcher()
```
  - addMatch
```
public void addMatch(int queryAtomIndex,
                     int targetAtomIndex)
```
    Adds a fixed matching between the given query and target atoms. That is, the query atom can only match the given target atom. If such a hit is not possible, no hits will be returned. 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().
    
    Specified by:
    
    addMatch in interface SimpleSearcher
    
    Parameters:
    
    queryAtomIndex - index of the query atom
    
    targetAtomIndex - index of the target atom
  - addMatch
```
public void addMatch(int[] queryAtoms,
                     int[] targetAtoms,
                     int length)
```
    Description copied from class: Search
    
    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
    
    Parameters:
    
    queryAtoms - the query atom indexes
    
    targetAtoms - the target atom indexes
    
    length - the length for which queryAtoms/targetAtoms should be interpreted.
  - clearMatch
```
public void clearMatch()
```
    Description copied from class: Search
    
    Clears the extra prerequisites of the structure search specified using addMatch calls.
    
    Overrides:
    
    clearMatch in class Search
  - 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 correct
    
    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 correct
    
    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 false indicates that any bonds appeared only after tautomer generation.
  - setLicenseEnvironment
```
public void setLicenseEnvironment(java.lang.String env)
```
    Specified by:
    
    setLicenseEnvironment in interface chemaxon.license.Licensable
  - isLicensed
```
public boolean isLicensed()
```
    Specified by:
    
    isLicensed in interface chemaxon.license.Licensable

Class MolSearch

Field Summary

Fields inherited from class chemaxon.sss.search.Search

Fields inherited from interface chemaxon.struc.StereoConstants

Fields inherited from interface chemaxon.sss.SearchConstants

Constructor Summary

Method Summary

Methods inherited from class chemaxon.sss.search.Search

Methods inherited from class java.lang.Object

Field Detail

isOrigTargetMayBeMarkush

Constructor Detail

MolSearch

Method Detail

setTarget

setTarget

getTarget

setQuery

setQuery

getQuery

setQuery

setTransformer

setStandardizer

setSearchOptions

addComparator

removeComparator

clearComparators

isMatching

findFirstHit

findNextHit

findAllHits

stop

setParameters

getSearcher

addMatch

addMatch

clearMatch

checkFilter

checkFilter

setOrigTargetMayBeMarkush

setLicenseEnvironment

isLicensed