Encoded Queries

One of the principal query formats supported by ADMET Predictor is the encoded query. This internal format provides users considerable flexibility in creating queries based on substructure, pharmacophore signature, and molecular property, with the additional option for Boolean logic and range specification (e.g., a molecular weight range). ADMET Predictor supports the use of encoded queries in spreadsheet searches and in key generation, and these queries serve as the format for individual records within query files. Each of these topics is covered in a relevant section of this manual.

A single encoded query is constructed by writing one or more encoded-query primitives, separated by logical operators. The format for an encoded-query primitive is:

QUERY_CODE QUERY_STRING SEARCH_CODE RANGE

The individual elements, which may be separated by any type of whitespace (excluding newline), are discussed below.

QUERY_CODE is a three-letter code that specifies the particular type of query that is being requested (e.g., a SMARTS query). The following list provides the most important of the supported codes. A few additional codes, including RSQ, ERSQ, and NULL, are used internally and are not described. Note that these values are not case sensitive.

NPQ specifies a named-property query. This code indicates that the subsequent query string will be a special name recognized by ADMET Predictor as a synonym for a molecular property. See the named-property queries section for the complete list of supported query names and for instructions on defining customized named-property queries. Users can also reference previously loaded attributes using the NPQ tag. For instance, if a user has registered “cLogP” as a numeric attribute, he can then search using “NPQ cLogP < 2.5”. This duplication (see the discussion of “NAQ” below) is particularly useful because the NPQ tag is considered the default tag and can thus be omitted. Hence queries such as “MolWeight <= 500” and “cLogP < 2.5” are recognized as valid.

SLQ specifies a query based on the SMARTS syntax defined by Daylight CIS, Inc. See www.daylight.com for a detailed tutorial on the SMARTS language. Note that the SLQ code also permits specification of named-property queries, using the angled bracket syntax (<>). For instance, the string “SLQ <HAcc>_C<HDon>” specifies a Hydrogen-bond donor and acceptor group, separated by a single Carbon atom. See the discussion of SMARTS queries in the Query Formats section for more detail.

EQN specifies a query based on an equation. These generally refer to one or more existing numeric attributes: for example, EQN "AP_FWeight"/100 computes a value equal to the attribute AP_FWeight divided by 100. SMARTS strings can be embedded inside equations: EQN "[!#6]"/"[*]" computes the fraction of atoms that are heteroatoms. Please see the file AttributeExamples.cqf for several example equations.

NAQ specifies a numeric-attribute query. This code indicates that the subsequent query string will be the name of a numeric molecular attribute previously loaded by the user. For instance, if a user has loaded a numeric attribute named “cLogP,” he can search against this property using a syntax such as “NAQ cLogP >= 0.5 <= 3.5”. Note that molecules not having the requested attribute, so-called “missing values,” always fail in a query containing a range specification; see below for more about missing-value searches. Numeric attributes (as well as text attributes) can also be referenced using the NPQ tag described earlier, the benefit being that the NPQ tag can be omitted (allowing “cLogP <= 2.5”). However, use of the NPQ tag requires that the attribute be registered (e.g., via Import Attributes), and thus will not work, for instance, when filtering an external SD/SMILES file whose attributes have not been loaded. Unregistered attributes can only be searched using the NAQ (or TAQ) tag. For more information regarding molecule attributes, see the section Working with Attributes.

TAQ specifies a text-attribute query. This is simply the text analog of NAQ. Missing values are assigned a value of “”. Text attributes can also be referenced by the NPQ tag, which can be omitted (allowing “Target == “kinase”).

QUERY_STRING. This is the actual query, written in a format appropriate for the preceding query code. Hence “MolWeight” would be an appropriate query string for the “NPQ” code, while “c1ccccc1” (benzene) would be an appropriate query string for the “SLQ” code.

SEARCH_CODE is optional. One of three single-letter codes indicates whether to perform a full match (“F”), single match (“S”), or unique match (“U”). For instance, if a benzene query is used to search a naphthalene molecule, a full match will return 24 hits, a unique match two hits, and a single match one hit. Note that if no code is provided, the default is usually to perform a full match; however, if the query includes range operations (see below), the default is to perform a unique match.

RANGE is an optional range specification applied to the match result. This range must take the form of either one or two symbol/value pairs, where the symbol is ">", "<", "=", ">=", "<=", "==", "<>", or "!=". For example, "= 3" indicates a result equal to 3, and "> 1 < 4" indicates a result that is greater than 1 and less than 4. The match-result value depends on the type of match requested. For example, "NPQ MolWeight" returns an actual weight value, while "SLQ c1ccccc1" returns the number of benzene matches. Note that text-attribute queries require the use of double quotes around the range value (taq Mech == "kinase").

Partial text matching is supported using the contains keyword. For example, the query Name contains "oxacin" will match the names ofloxacin and OFLOXACIN. Analogously, the excludes keyword can be used to prevent a particular text fragment from occurring.

Molecules missing the value of a particular attribute will never match a query that includes a range specification for that attribute. A special symbol, M, has been introduced to allow searches of missing values. Thus the query "Assay1 = M" will match all molecules that are missing the value of the attribute called Assay1. Similarly, "Assay1 != M" matches all molecules with any value of that attribute.

The following are examples of valid encoded-query primitives:

NPQ MolWeight >= 200 <= 500

Ring == 4 <<the "NPQ" code is assumed>>

Name != "ofloxacin" <<the "NPQ" code is assumed>>

SLQ c1ccccc1 = 2 <<"=" is identical to "==">>

Slq <HDon>~<HAcc> S

PHQ HAcc.HAcc.HAcc.2.2.2

Name contains “oxacin” <<name must contain "oxacin">>

Name excludes “oxacin” <<name must not contain "oxacin">>

pIC50_A < pIC50_B

The first query specifies molecules having a molecular weight greater than or equal to 200 and less than or equal to 500. The second query specifies molecules having exactly 4 rings. The third query specifies molecules having a name not equal to "ofloxacin." The fourth query specifies molecules having two distinct benzene rings. The fifth query specifies all molecules containing at least one example of a Hydrogen-bond acceptor connected to a Hydrogen-bond donor. The "S" ensures that at most a single match will be identified in each molecule. The sixth query specifies all molecules containing the particular pharmacophore. The seventh query is an example of partial text matching; such queries are not case sensitive. The eighth query is another example of partial text matching; in this case, the specified text fragment must not be included in the name. The final query illustrates that one attribute value can be compared against another.

Several operators are available to combine two numeric attribute values. For example, the query pIC50_A avg pIC50_B returns the average of the attributes pIC50_A and pIC50_B. The following operators are supported:

avg average; if one value is missing, the result is the other value

avg2 average; if any value is missing, the result is a missing value

min minimum; if one value is missing, the result is the other value

min2 minimum; if any value is missing, the result is a missing value

max maximum; if one value is missing, the result is the other value

max2 maximum; if any value is missing, the result is a missing value

mrg merge: the result is the first value if not missing; otherwise it is the second value

ADMET Predictor also allows two or more encoded-query primitives to be combined to form a logical expression. The primitives must be separated by one of three logical operators: AND, OR, and LPAND. The last of these operators is a "low precedence" AND operator, equivalent to the SMARTS ";" symbol. If no operator is specified between primitives, an LPAND operator is assumed. When logical expressions are formed, the primitives and operators must be separated by newline ("\n") or carriage return ("\r\n") symbols. Thus the following are examples of valid encoded queries:

NPQ MolWeight < 500

AND

NPQ Act > 50

AND

SLQ [F,Cl,Br,I] = 0

SLQ n1cccc1 S

SLQ n1ccccc1 S

NPQ Ring < 3

NPQ RotBond < 6

ADMET Predictor also supports an expanded syntax for logical operators. These are "&&" (for AND), "||" (for OR), and ";" (for LPAND). An advantage of these operators is that they do not require newline characters, but rather can be placed on a single line. Thus the equivalent queries to those shown above are:

NPQ MolWeight < 500 && NPQ Act > 50 && SLQ [F,Cl,Br,I] = 0

SLQ n1cccc1 S || SLQ n1ccccc1 S

NPQ Ring < 3 ; NPQ RotBond < 6

Encoded queries support a grouping operator for complex queries. These operators can be nested. The following example illustrates the syntax:

NPQ MolWeight < 500

AND

BEGINGROUP

SLQ n1cnccc1

SLQ n1ccncc1

ENDGROUP

ADMET Predictor also supports an expanded syntax for grouping operators. These are "(" (for BEGINGROUP) and ")" (for ENDGROUP). Thus the following is equivalent to above:

NPQ MolWeight < 500 && ( SLQ n1cnccc1 || SLQ n1ccncc1 )

An important requirement of these operators ("&&", "||", ";", "(", ")") is that they each be enclosed by one or more whitespace characters. For instance, the query "( Ring > 2 ) && ( Act > 50 )" is valid, while "(Ring>2)&&(Act>50)" is invalid. Though somewhat inconvenient, this syntax is currently required due to the fact that many complicated query patterns (such as Daylight SMARTS) do not require quotation marks, and can thus easily interfere with the encoded-query syntax.