Package org.openscience.cdk.smarts

Class Smarts

java.lang.Object
org.openscience.cdk.smarts.Smarts
public final class Smarts extends Object
Parse and generate the SMARTS query language. Given an IAtomContainer a SMARTS pattern is parsed and new IQueryAtoms and IQueryBonds are appended to the connection table. Each query atom/bond contains an Expr that describes the predicate to check when matching. This Expr is also used for generating SMARTS. 
 
 IAtomContainer mol = ...;
 if (Smarts.parse(mol, "[aD3]a-a([aD3])[aD3]")) {
     String smarts = Smarts.generate(mol);
 }
When parsing SMARTS several flavors are available. The flavors affect how queries are interpreted. The following flavors are available:
  • FLAVOR_LOOSE - allows all unambiguous extensions.
  • FLAVOR_DAYLIGHT - no extensions, as documented in Daylight theory manual.
  • FLAVOR_CACTVS - '[#X]' hetero atom, '[#G8]' periodic group 8, '[G]' or '[i]' means insaturation. '[Z2]' means 2 aliphatic hetero neighbors, '[z2]' means 2 aliphatic hetero
  • FLAVOR_MOE - '[#X]' hetero atom, '[#G8]' periodic group 8, '[i]' insaturation.
  • FLAVOR_OECHEM - '[R3]' means ring bond count 3 (e.g. [x3]) instead of in 3 rings (problems with SSSR uniqueness). '[^2]' matches hybridisation (2=Sp2)
  • FLAVOR_CDK - Same as FLAVOR_LOOSE
  • FLAVOR_CDK_LEGACY - '[D3]' means heavy degree 3 instead of explicit degree 3. '[^2]' means hybridisation (2=Sp2). '[G8]' periodic group 8

In threaded environments error handling can be improved by using the SmartsResult return type. Other wise the error message is set on a shared variable which is access via getLastErrorMesg(). 
 
 IAtomContainer mol = ...;
 SmartsResult res = Smarts.parseToResult(mol, "[aD3]a-a([aD3])[aD3]");
 if (res.ok()) {
     String smarts = Smarts.generate(mol);
 } else {
     System.err.println(res.getMessage());
 }

In addition to the flavors above CACTVS toolkit style ranges are supported. For example [D{2-4}] means degree 2, 3, or 4. On writing such ranges are converted to [D2,D3,D4].

  • Field Details

  • Constructor Details

    • Smarts

      public Smarts()

  • Method Details

    • getLastErrorMesg

      public static String getLastErrorMesg()
      Access the error message from previously parsed SMARTS (when parse(org.openscience.cdk.interfaces.IAtomContainer, java.lang.String, int)=false).
      Note: This is not thread-safe, in threaded environments use parseToResult(org.openscience.cdk.interfaces.IAtomContainer, java.lang.String, int)
      Returns:
      the error message, or null if none

    • getLastErrorLocation

      public static String getLastErrorLocation()
      Access a display of the error position from previously parsed SMARTS (when parse(org.openscience.cdk.interfaces.IAtomContainer, java.lang.String, int)=false).
      Note: This is not thread-safe, in threaded environments use parseToResult(org.openscience.cdk.interfaces.IAtomContainer, java.lang.String, int).
      Returns:
      the error message, or null if none

    • parseToResult

      public static SmartsResult parseToResult(IAtomContainer mol, String smarts, int flavor)
      Parse the provided SMARTS string appending query atom/bonds to the provided molecule. This method allows the flavor of SMARTS to specified that changes the meaning of queries.
      Parameters:
      mol - the molecule to store the query in
      smarts - the SMARTS string
      flavor - (optional) the SMARTS flavor, default is FLAVOR_LOOSE.
      Returns:
      the result of the SMARTS
      See Also:

    • parseToResult

      public static SmartsResult parseToResult(IAtomContainer mol, String smarts)
      Parse the provided SMARTS string appending query atom/bonds to the provided molecule. This method allows the flavor of SMARTS to specified that changes the meaning of queries.
      Parameters:
      mol - the molecule to store the query in
      smarts - the SMARTS string
      Returns:
      the result of the SMARTS
      See Also:

    • parse

      public static boolean parse(IAtomContainer mol, String smarts, int flavor)
      Parse the provided SMARTS string appending query atom/bonds to the provided molecule. This method allows the flavor of SMARTS to specified that changes the meaning of queries.
      Parameters:
      mol - the molecule to store the query in
      smarts - the SMARTS string
      flavor - the SMARTS flavor (e.g. FLAVOR_LOOSE.
      Returns:
      whether the SMARTS was valid, if invalid the getLastErrorMesg() is set.
      See Also:

    • parse

      public static boolean parse(IAtomContainer mol, String smarts)
      Parse the provided SMARTS string appending query atom/bonds to the provided molecule. This method uses FLAVOR_LOOSE.
      Parameters:
      mol - the molecule to store the query in
      smarts - the SMARTS string
      Returns:
      whether the SMARTS was valid, if invalid the getLastErrorMesg() is set.
      See Also:

    • generateAtom

      public static String generateAtom(Expr expr)
      Utility to generate an atom expression. 
      
 Expr   expr  = new Expr(Expr.Type.DEGREE, 4).and(
                  new Expr(Expr.Type.IS_AROMATIC));
 String aExpr = Smarts.generateAtom(expr);
 // aExpr='[D4a]'
      Parameters:
      expr - the expression
      Returns:
      the SMARTS atom expression
      See Also:

    • generateBond

      public static String generateBond(Expr expr)
      Utility to generate a bond expression. 
      
 Expr   expr  = new Expr(Expr.Type.TRUE);
 String bExpr = Smarts.generateBond(expr);
 // bExpr='~'
      Parameters:
      expr - the expression
      Returns:
      the SMARTS atom expression
      See Also:

    • generate

      public static String generate(IAtomContainer mol)
      Generate a SMARTS string from the provided molecule. The generator uses Exprs stored on the QueryAtom and QueryBond instances. 
       
 IAtomContainer mol = ...;
 QueryAtom qatom1 = new QueryAtom(mol.getBuilder());
 QueryAtom qatom2 = new QueryAtom(mol.getBuilder());
 QueryBond qbond  = new QueryBond(mol.getBuilder());
 qatom1.setExpression(new Expr(Expr.Type.IS_AROMATIC));
 qatom2.setExpression(new Expr(Expr.Type.IS_AROMATIC));
 qbond.setExpression(new Expr(Expr.Type.IS_ALIPHATIC));
 qbond.setAtoms(new IAtom[]{qatom1, qatom2});
 mol.addAtom(qatom1);
 mol.addAtom(qatom2);
 mol.addBond(qbond);
 String smartsStr = Smarts.generate(mol);
 // smartsStr = 'a!:a'
      Parameters:
      mol - the query molecule
      Returns:
      the SMARTS
      See Also: