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: