org.openscience.cdk.smiles.smarts

Class SMARTSQueryTool

java.lang.Object

org.openscience.cdk.smiles.smarts.SMARTSQueryTool

@TestClass(value="org.openscience.cdk.smiles.smarts.SMARTSQueryToolTest")
public class SMARTSQueryTool
extends Object

This class provides a easy to use wrapper around SMARTS matching functionality.

User code that wants to do SMARTS matching should use this rather than using SMARTSParser (and UniversalIsomorphismTester) directly. Example usage would be

 SmilesParser sp = new SmilesParser(DefaultChemObjectBuilder.getInstance());
 IAtomContainer atomContainer = sp.parseSmiles("CC(=O)OC(=O)C");
 SMARTSQueryTool querytool = new SMARTSQueryTool("O=CO");
 boolean status = querytool.matches(atomContainer);
 if (status) {
    int nmatch = querytool.countMatches();
    List mappings = querytool.getMatchingAtoms();
    for (int i = 0; i < nmatch; i++) {
       List atomIndices = (List) mappings.get(i);
    }
 }
 

Unsupported Features

• Component level grouping
• Stereochemistry
• Reaction support

SMARTS Extensions

Currently the CDK supports the following SMARTS symbols, that are not described in the Daylight specification. However they are supported by other packages and are noted as such.

Symbol	Meaning	Default	Notes
Gx	Periodic group number	None	x must be specified and must be a number between 1 and 18. This symbol is supported by the MOE SMARTS implementation
#X	Any non-carbon heavy element	None	This symbol is supported by the MOE SMARTS implementation
^x	Any atom with the a specified hybridization state	None	x must be specified and should be between 1 and 8 (inclusive), corresponding to SP1, SP2, SP3, SP3D1, SP3D2 SP3D3, SP3D4 and SP3D5. Supported by the OpenEye SMARTS implementation

Notes

• As described by Craig James the h<n> SMARTS pattern should not be used. It was included in the Daylight spec for backwards compatibility. To match hydrogens, use the H<n> pattern.
• The wild card pattern (*) will not match hydrogens (explicit or implicit) unless an isotope is specified. In other words, * gives two hits against C[2H] but 1 hit against C[H]. This also means that it gives no hits against [H][H]. This is contrary to what is shown by Daylights depictmatch service, but is based on this discussion. A work around to get * to match [H][H] is to write it in the form [1H][1H].

  It's not entirely clear what the behavior of * should be with respect to hydrogens. it is possible that the code will be updated so that * will not match any hydrogen in the future.

• The CDKHueckelAromaticityDetector only considers single rings and two fused non-spiro rings. As a result, it does not properly detect aromaticity in polycyclic systems such as [O-]C(=O)c1ccccc1c2c3ccc([O-])cc3oc4cc(=O)ccc24. Thus SMARTS patterns that depend on proper aromaticity detection may not work correctly in such polycyclic systems

Author:

Rajarshi Guha

Keywords:

SMARTS, substructure search

Created on:

2007-04-08

Constructor Summary

Constructors

Constructor and Description
SMARTSQueryTool(String smarts)

Method Summary

Methods

Modifier and Type	Method and Description
int	countMatches() Returns the number of times the pattern was found in the target molecule.
List<List<Integer>>	getMatchingAtoms() Get the atoms in the target molecule that match the query pattern.
String	getSmarts() Returns the current SMARTS pattern being used.
List<List<Integer>>	getUniqueMatchingAtoms() Get the atoms in the target molecule that match the query pattern.
boolean	matches(IAtomContainer atomContainer) Perform a SMARTS match and check whether the query is present in the target molecule.
boolean	matches(IAtomContainer atomContainer, boolean forceInitialization) Perform a SMARTS match and check whether the query is present in the target molecule.
void	setQueryCacheSize(int maxEntries) Set the maximum size of the query cache.
void	setSmarts(String smarts) Set a new SMARTS pattern.

Methods inherited from class java.lang.Object

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

Constructor Detail

SMARTSQueryTool

public SMARTSQueryTool(String smarts)
                throws CDKException

Throws:

CDKException

Method Detail

setQueryCacheSize

public void setQueryCacheSize(int maxEntries)

Set the maximum size of the query cache.

Parameters:

maxEntries - The maximum number of entries

getSmarts

@TestMethod(value="testQueryTool")
public String getSmarts()

Returns the current SMARTS pattern being used.

Returns:

The SMARTS pattern

setSmarts

@TestMethod(value="testQueryTool, testQueryToolResetSmart")
public void setSmarts(String smarts)
               throws CDKException

Set a new SMARTS pattern.

Parameters:

smarts - The new SMARTS pattern

Throws:

CDKException - if there is an error in parsing the pattern

matches

public boolean matches(IAtomContainer atomContainer)
                throws CDKException

Perform a SMARTS match and check whether the query is present in the target molecule.

This function simply checks whether the query pattern matches the specified molecule. However the function will also, internally, save the mapping of query atoms to the target molecule

Note: This method performs a simple caching scheme, by comparing the current molecule to the previous molecule by reference. If you repeatedly match different SMARTS on the same molecule, this method will avoid initializing ( ring perception, aromaticity etc.) the molecule each time. If however, you modify the molecule between such multiple matchings you should use the other form of this method to force initialization.

Parameters:

atomContainer - The target moleculoe

Returns:

true if the pattern is found in the target molecule, false otherwise

Throws:

CDKException - if there is an error in ring, aromaticity or isomorphism perception

See Also:

getMatchingAtoms(), countMatches(), matches(org.openscience.cdk.interfaces.IAtomContainer, boolean)

matches

@TestMethod(value="testQueryTool, testQueryToolSingleAtomCase, testQuery")
public boolean matches(IAtomContainer atomContainer,
                              boolean forceInitialization)
                throws CDKException

Perform a SMARTS match and check whether the query is present in the target molecule.

This function simply checks whether the query pattern matches the specified molecule. However the function will also, internally, save the mapping of query atoms to the target molecule

Parameters:

atomContainer - The target moleculoe

forceInitialization - If true, then the molecule is initialized (ring perception, aromaticity etc). If false, the molecule is only initialized if it is different (in terms of object reference) than one supplied in a previous call to this method.

Returns:

true if the pattern is found in the target molecule, false otherwise

Throws:

CDKException - if there is an error in ring, aromaticity or isomorphism perception

See Also:

getMatchingAtoms(), countMatches(), matches(org.openscience.cdk.interfaces.IAtomContainer)

countMatches

@TestMethod(value="testQueryTool")
public int countMatches()

Returns the number of times the pattern was found in the target molecule.

This function should be called after matches(org.openscience.cdk.interfaces.IAtomContainer). If not, the results may be undefined.

Returns:

The number of times the pattern was found in the target molecule

getMatchingAtoms

@TestMethod(value="testQueryTool")
public List<List<Integer>> getMatchingAtoms()

Get the atoms in the target molecule that match the query pattern.

Since there may be multiple matches, the return value is a List of List objects. Each List object contains the indices of the atoms in the target molecule, that match the query pattern

Returns:

A List of List of atom indices in the target molecule

getUniqueMatchingAtoms

@TestMethod(value="testUniqueQueries")
public List<List<Integer>> getUniqueMatchingAtoms()

Get the atoms in the target molecule that match the query pattern.

Since there may be multiple matches, the return value is a List of List objects. Each List object contains the unique set of indices of the atoms in the target molecule, that match the query pattern

Returns:

A List of List of atom indices in the target molecule