org.openscience.cdk.smiles.smarts

Class SMARTSQueryTool

    • Constructor Detail

      • SMARTSQueryTool

        public SMARTSQueryTool(String smarts,
                       IChemObjectBuilder builder)
        Create a new SMARTS query tool for the specified SMARTS string. Query objects will contain a reference to the specified IChemObjectBuilder.
        Parameters:
        smarts - SMARTS query string
        Throws:
        IllegalArgumentException - if the SMARTS string can not be handled
    • Method Detail

      • setQueryCacheSize

        public void setQueryCacheSize(int maxEntries)
        Set the maximum size of the query cache.
        Parameters:
        maxEntries - The maximum number of entries
      • useSmallestSetOfSmallestRings

        public void useSmallestSetOfSmallestRings()
        Indicates that ring properties should use the Smallest Set of Smallest Rings. The set is not unique and may lead to ambiguous matches.
        See Also:
        useEssentialRings(), useRelevantRings()
      • useRelevantRings

        public void useRelevantRings()
        Indicates that ring properties should use the Relevant Rings. The set is unique and includes all of the SSSR but may be exponential in size.
        See Also:
        useSmallestSetOfSmallestRings(), useEssentialRings()
      • setAromaticity

        @TestMethod(value="setAromaticity,nullAromaticity")
        public void setAromaticity(Aromaticity aromaticity)
        Set the aromaticity perception to use. Different aromaticity models may required certain attributes to be set (e.g. atom typing). These will not be automatically configured and should be preset before matching.
         SMARTSQueryTool sqt = new SMARTSQueryTool(...);
         sqt.setAromaticity(new Aromaticity(ElectronDonation.cdk(),
                                            Cycles.cdkAromaticSet));
         for (IAtomContainer molecule : molecules) {
         
             // CDK Aromatic model needs atom types
             AtomContainerManipulator.percieveAtomTypesAndConfigureAtoms(molecule);
             
             sqt.matches(molecule);     
         }                                   
         
        Parameters:
        aromaticity - the new aromaticity perception
        See Also:
        ElectronDonation, Cycles
      • 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