ZINC15:Syntax: Difference between revisions

From DISI
Jump to navigation Jump to search
(asdf)
No edit summary
 
(30 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The general form of a ZINC 15 api request is
ZINC 15 uses a uniform set of rules to interpret the URL allowing both web pages and a machine-readable application programming interface (API). This page describes both.
 
'''http[s]://host/resource[.format[:columns][/variant][?page-view-controls | resource-constraints]
 
Where items in \[ square brackets \] are optional.


{{TOCright}}
{{TOCright}}


* host = zinc15.docking.org
= Overview =
* resource is one of the 15 resources in the table below.
ZINC15 queries for all resource types can be formulated as HTTP requests using a consistent URL syntax. The syntax is consistent for both interactive (browser-based) and API (script-based) queries. The API downloads are triggered by specifying a download format and, optionally, a list of output fields to include.
* format is one of the 12 formats in the formats table below. If omitted, a web page is requested.
* columns is one or more of the columns in the columns table below. Not all columns make sense in all resource contexts.  Examples are provided. There are sensible defaults for each resource, so the column specification may be omitted.
* variant is optionally one or more of the variants in the variants table below
* page-view-controls is optionally one or more of those listed in the page-view-controls table, below.
* resource constraints is optionally one or more of those in the resource-constraints table, below.
 
= Resources =
A resource is the type of object you are asking for.  Each ZINC URL specifies only one of 15 available resources.  Resources are always plurals, indicating that the result is always a selection from among the rows in that resource. The supported reference-tables are:
 
{| class="wikitable"
|-
! table name !! Description !! Notes/Links
|-
|  substances || substance table || notes about substance table
|-
| catalogs || asdfasdf || sdfsdfdaf
|-
| genes || sdfasfd || sadfasdf
|-
| catalogitems || lala || asdf
|-
| protomers || qwer34 || seradsf
|-
| targets || asdfasdf || asdfasdf sa
|-
| activities || sadfasfsd || asdfasfd
|-
| purchasability ||asdf asdf || asdfasfd sadf
|-
| representatives ||asdf asdf || asdfasfd sadf
|-
| clusters ||asdf asdf || asdfasfd sadf
|-
| bioactivities ||asdf asdf || asdfasfd sadf
|-
| majorclasses ||asdf asdf || asdfasfd sadf
|-
| targetclasses ||asdf asdf || asdfasfd sadf
|-
| organisms ||asdf asdf || asdfasfd sadf
|-
| modeltypes ||asdf asdf || asdfasfd sadf
|-
| structures ||asdf asdf || asdfasfd sadf
|-
| traits ||asdf asdf || asdfasfd sadf
|-
| tools ||asdf asdf || asdfasfd sadf
|-
| ecfp4s  || lala || fingerprints
|}
 
Historical note:  In ZINC 12, the reference-table was always substances, and thus the result of any query was always a set of molecules. A few reports such as vendor and target listings were available via the webpages, but were not supported by the API.  This is a substantial change that appeared first in ZINC 15.
 
= Format =
We support the following formats
 
{| class="wikitable"
|-
! format !! Description !! options/links
|-
|  json || substance table || notes about substance table
|-
| txt  || lala || lala
|-
| csv || lala || asdf
|-
| xls || asdfasdf || sdfsdfdaf
|-
| tsv || qwer34 || seradsf
|-
| xml || sdfasfd || sadfasdf
|}
 
 
= Columns =
The result contains the specified columns in the output.  If the column is in the reference-table, it is specified without a table specfification, otherwise, the column specification must be of the form table.item.
 
The following items are supported in each of the tables.
 
 
{| class="wikitable"
|-
! table name !! Description !! Notes/Links
|-
|  substances || substance table || notes about substance table
|-
| ecfp4s  || lala || lala
|-
| catalogitems || lala || asdf
|-
| catalogs || asdfasdf || sdfsdfdaf
|-
| protomers || qwer34 || seradsf
|-
| genes || sdfasfd || sadfasdf
|-
| targets || asdfasdf || asdfasdf sa
|-
| activities || sadfasfsd || asdfasfd
|-
| organisms ||asdf asdf || asdfasfd sadf
|}


All URLs will be provided relative to [//zinc15.docking.org zinc15.docking.org], thus /substances/ implies [http://zinc15.docking.org/substances/ zinc15.docking.org/substances/].


= Syntax =


Objects from among these may be specified as part of a query_specification.
The full syntax of a query is defined as:
<pre style="overflow-x: scroll">
/<RESOURCE>[/<IDENTIFIER>[/<RELATION>]][/subsets/<SUBSET>[+<SUBSET>...]][/having/[no-]<EXT_RELATION>[+[no-]<EXT_RELATION>...]][/subsets/[<EXT_RELATION>.]<RELATION_SUBSET>+[[<EXT_RELATION>.]<RELATION_SUBSET>...]](/[<VIEW>.html]|.<FORMAT>[:<OUTPUT_FIELD>[+<OUTPUT_FIELD>...]])[?<OPTION_NAME>=<OPTION_VALUE>|<QUERY_FIELD>[-<OPERATOR>[-<OPERATOR_ARG>...]]=<FIELD_CONSTRAINT>[&<OPTION_NAME>=<OPTION_VALUE>|<QUERY_FIELD>[-<OPERATOR>[-<OPERATOR_ARG>...]]=<FIELD_CONSTRAINT>...]]
</pre>


More Concisely, this can be written as:
<pre style="overflow-x: scroll">
/<Root>[/<Subsets>][/<Existential>[/<Ext. Subsets>]]<Formatting>[?[<Constraints>][<Options>]]
</pre>


Broken down into individual components:


{| class="wikitable"
{| class="wikitable"
|-
|-  
! table name !! Description !! Notes/Links
! Syntax
|-
! Name
|  substances || sub_id, structure, inchikey, up_date, logp, tpsa, hbd, hba || notes about substance table
! Explanation
|-
! Example
| structure || mwt, logp, tpsa, hba, hbd, num_atoms, num_heavy_atoms, rotatable_bonds, num_hetero_atoms, num_rings, inchi || lala
! Notes
|-
|-
| protomers || prot_id, sub_id_fk, desolv_apol, desolv_pol, net_charge || asdf
| <RESOURCE>[/<IDENTIFIER>[/<RELATION>]]
|-
  | ('''Root''') <br>Query Root
| catalogs || cat_id, name, short_name, purchasable, free, version, updated, bb, np, drug || sdfsdfdaf
| Defines where the query should be performed: either on the whole resource or only those related to another, single resource.
|-
| [//zinc15.docking.org/trials/NCT00001251/substances/ /trials/NCT00001251/substances]
| catalogitems || sub_id_fk, cat_id_fk, supplier_code, depleted || seradsf
| Valid values for <IDENTIFIER> and <RELATION> parts of the query root are defined separate for each resource.
|-
|-
| genes || short_name || sadfasdf
| subsets/<SUBSET>[+<SUBSET>...]
|-
  | ('''Subsets''') <br>Query Subsets
| targets || swissprot, uniprot, target, gene, affinity || asdfasdf sa
| Applies one or more named, predefined constraints to the query.
|-
| [//zinc15.docking.org/substances/subsets/fda+for-sale/ .../subsets/fda+for-sale/]
| activities || affinitynM, target, gene, organism || asdfasfd
| Subsets are defined separately for each resource. Some subsets are disjoint, so it's possible to accidentally construct null queries
|-
|-
| organisms ||asdf asdf || asdfasfd sadf
| having/[no-]<EXT_RELATION>[+[no-]<EXT_RELATION>...]
| ('''Existential''') <br>Existential Requirements
| Applies existential (or non-existential with the "no-" prefix) constraints based on on the results of the query
| [//zinc15.docking.org/genes/having/no-protomers/ .../having/no-protomers/]
| The available relations depend on the resultant resource, which is not necessarily the same as the root resource
|-
| subsets/[<EXT_RELATION>.]<RELATION_SUBSET>+[[<EXT_RELATION>.]<RELATION_SUBSET>...]
| ('''Ext. Subsets''') <br>Existential Relation Subsets
| Applies subset requirements to the **existential relation requirement** (see above) of the query
| [//zinc15.docking.org/substances/having/trials/subsets/cancer/ .../subsets/cancer/]
| The relation subsets are completely independent of the query subsets, and valid values depend on the type of the existential resource. When multiple existential relations are specified, the subsets must be prefixed with "<EXT_RELATION>." to identify which they apply to.
|-  
| /[<VIEW>.html] OR<br> .<FORMAT>[:<OUTPUT_FIELD>[+<OUTPUT_FIELD>...]]
| ('''Formatting''') <br>Formatting Options
| Dictates how the result of a query will be returned. If <FORMAT> is specified the result will be sent as a download. If a <VIEW> is specified the result will be rendered as HTML. If neither is provided (just "/") the "**Accept**"  header will be interrogated to determine the requested format, which defaults to HTML.
| [//zinc15.docking.org/majorclasses.json%3Apublic_identifier+name+num_genes+num_substances .json:public_identifier+name +num_genes+num_substances]
| Valid views (currently) include table or tile. The default is always tile. Valid [[ZINC15:Formats]] are explained in the wiki. Valid <OUTPUT_FIELD>s depend on the specific resource being requested, and  can be found on the resource help pages.
|}
|}


== Query Root ==


= Variants =
There are three basic types of queries supported by ZINC15.
We support the following variants


{| class="wikitable"
{| class="wikitable"
|-
|-  
! format !! Description !! options/links
! Kind
|-
! Syntax
|  page=x || substance table || notes about substance table
! Description  
|-
! Example
| perpage=y || lala || lala
|-  
|-
| Full Resource Listing
| count=all || lala || asdf
  | /<RESOURCE>
|-
| Performs the query on all <RESOURCE>s
| distinct || asdfasdf || sdfsdfdaf
| [//zinc15.docking.org/genes/ /genes]
|-
|-  
| sort-by || qwer34 || seradsf
| Single Resource Lookup
|-
  | /<RESOURCE>/<IDENTIFIER>
| xml || sdfasfd || sadfasdf
| Retrieves information about a specific <RESOURCE> instance identified by <IDENTIFIER>
|}
| [//zinc15.docking.org/genes/ADRB1 /genes/ADRB1]
|-  
| Single Resource Relation
| /<RESOURCE>/<IDENTIFIER>/<RELATION>
| Performs the query on only resources that are linked to a specific instance of a <RESOURCE> identified by <IDENTIFIER> via the <RELATION> relationship. The type of the result will depend on the taret of <RELATION> (see below).
| [//zinc15.docking.org/genes/ADRB1/substances/ /genes/ADRB1/substances]
|}


 
=== Parameters ===
= Format =
We support the following resource constraints


{| class="wikitable"
{| class="wikitable"
|-
|-  
! format !! Description !! options/links
! Name
|-
! Meaning
|  resource.attribute:operator || substance table || notes about substance table
! Example
|-
! Example URL
| blah || lala || lala
! Options
|-
|-  
| blah || lala || asdf
| <RESOURCE>
|-
  | The name of a ZINC15 resource.
| xls || asdfasdf || sdfsdfdaf
| catalogs
|-
| [//zinc15.docking.org/catalogs/ /<b>catalogs</b>/]
| tsv || qwer34 || seradsf
| [[ZINC15:Resources|Wiki Explanation of Resources]] [//zinc15.docking.org/help/resources/ ZINC15 Meta-resource]
|-
|-  
| xml || sdfasfd || sadfasdf
| <IDENTIFIER>
|}
  | The unique identifier (key) for a specific resource instance.
 
| ZINC000000000053
 
| [//zinc15.docking.org/substances/ZINC000000000053 /substances/<b>ZINC000000000053</b>/]
= Query operators =
| The identifier column is listed on each resources' "help" page (e.g. [//zinc15.docking.org/substances/help/]) and can also always be accessed via the `public_identifier` attribute of a resource instance.
|-
| <RELATION>
| The name of a relation defined on <RESOURCE> objects.
| activities
| [//zinc15.docking.org/substances/ZINC000000000053/activities /substances/ZINC000000000053/<b>activities</b>]
| The name and type of each resources' relations is defined on the "help" page (e.g. [//zinc15.docking.org/substances/help/])
|}


Note that a query rooted on /catalog/sial/items will not return **catalogs**, but instead **catitems**, as the catalog relation named **items** returns **catitem** resources. This can be seen on the [//zinc15.docking.org/catalogs/help Catalog Help Page].


{| class="wikitable"
|-
! operator !! Description !! synonyms
|-
| @>  || lala || contains
|-
| <@ || lala || contained in
|-
| = || equals || eq
|-
| < || less than || lt
|-
| > || greater than || gt
|-
| <= || less than or equal || le
|-
| >= || greater than or equal || ge
|-
| between || sadfasfsd || asdfasfd
|-
| like, is, not , startswith, endswith, similar to ||asdf asdf || asdfasfd sadf
|}


= NP, Drug and BB =
The items in [ square brackets ] are optional.  The items in < angled braces > are each described below.


* <RESOURCE> is an object type, such as molecules, catalogs or genes, and are fully described here: [[ZINC15:Resources]]


{| class="wikitable"
* <FORMAT> is one of the supported formats, such as smi, sdf, csv, fully described here: [[ZINC15:Formats]]. If a format is omitted, a webpage is implicitly requested.
|-
! quality !! values !! Notes/Links
|-
| NP || 0=unknown, 1=biogenic, 2=metabolite, 3=endogenous human metabolite || lala
|-
| Drug  || 0=unknown, 1=annotated catalog, 2=bioactive, 4=bioactive in vitro < 1uM, 5=bioactive in cells <1uM, 6=in man, 8=world drug, 10=fda approved || lala
|-
| BB || f=not bb, t=bb || asdf
|}
 
= examples =


* <FIELDS> are individual properties, including calculated ones, and are described together with the [[ZINC15:Resources]] to which they belong.
[[ZINC15:Properties]] Not all properties make sense in all resource contexts.  [[ZINC15:examples]] are provided. Each resource has default fields, if none are specified.


http://zincapi.ucsf.bkslab.org/v1/substances/txt:smiles,zinc_id,tanimoto_similarity/catalog.purchasable%20gt%209&ecfp4.data%20similarto%20CC(=O)Oc1ccccc1C(=O)O%20within%20.5?count=all
* <ENDPOINT> is one of (tile, table, detail, etc.) (only available if the underlying template exists); where items in [ square brackets ] are optional, and:


[[ZINC15:Variants]].


* <PREDICATE_LIST> is a query string, one or more of <PREDICATE> delimited by &<PREDICATE> is <ATTRIBUTE>[:<OPERATOR>[;<OPERATOR_ARGS>]]=<THRESHOLD>


* [[ZINC15:Page Controls]] are optional, and are used to qualify how a search is to be performed and formatted for the page.


* [[ZINC15:Query operators]]


* https is currently not supported, but it will be.


= Reserved words =
* list, tile, subsets, help, overview  - these have special meaning in the URL, and can never be the names of resources or their columns.


= Examples =
We illustrate the use of the website and the API with [[ZINC15:examples]].


Back to [[ZINC15]]
[[Category:API]]
[[Category:API]]
[[Category:ZINC]]
[[Category:ZINC15]]

Latest revision as of 01:01, 5 January 2019

ZINC 15 uses a uniform set of rules to interpret the URL allowing both web pages and a machine-readable application programming interface (API). This page describes both.

Overview

ZINC15 queries for all resource types can be formulated as HTTP requests using a consistent URL syntax. The syntax is consistent for both interactive (browser-based) and API (script-based) queries. The API downloads are triggered by specifying a download format and, optionally, a list of output fields to include.

All URLs will be provided relative to zinc15.docking.org, thus /substances/ implies zinc15.docking.org/substances/.

Syntax

The full syntax of a query is defined as: 

/<RESOURCE>[/<IDENTIFIER>[/<RELATION>]][/subsets/<SUBSET>[+<SUBSET>...]][/having/[no-]<EXT_RELATION>[+[no-]<EXT_RELATION>...]][/subsets/[<EXT_RELATION>.]<RELATION_SUBSET>+[[<EXT_RELATION>.]<RELATION_SUBSET>...]](/[<VIEW>.html]|.<FORMAT>[:<OUTPUT_FIELD>[+<OUTPUT_FIELD>...]])[?<OPTION_NAME>=<OPTION_VALUE>|<QUERY_FIELD>[-<OPERATOR>[-<OPERATOR_ARG>...]]=<FIELD_CONSTRAINT>[&<OPTION_NAME>=<OPTION_VALUE>|<QUERY_FIELD>[-<OPERATOR>[-<OPERATOR_ARG>...]]=<FIELD_CONSTRAINT>...]]

More Concisely, this can be written as: 

/<Root>[/<Subsets>][/<Existential>[/<Ext. Subsets>]]<Formatting>[?[<Constraints>][<Options>]]

Broken down into individual components:

Syntax Name Explanation Example Notes
<RESOURCE>[/<IDENTIFIER>[/<RELATION>]] (Root)
Query Root 		Defines where the query should be performed: either on the whole resource or only those related to another, single resource. /trials/NCT00001251/substances Valid values for <IDENTIFIER> and <RELATION> parts of the query root are defined separate for each resource.
subsets/<SUBSET>[+<SUBSET>...] (Subsets)
Query Subsets 		Applies one or more named, predefined constraints to the query. .../subsets/fda+for-sale/ Subsets are defined separately for each resource. Some subsets are disjoint, so it's possible to accidentally construct null queries
having/[no-]<EXT_RELATION>[+[no-]<EXT_RELATION>...] (Existential)
Existential Requirements 		Applies existential (or non-existential with the "no-" prefix) constraints based on on the results of the query .../having/no-protomers/ The available relations depend on the resultant resource, which is not necessarily the same as the root resource
subsets/[<EXT_RELATION>.]<RELATION_SUBSET>+[[<EXT_RELATION>.]<RELATION_SUBSET>...] (Ext. Subsets)
Existential Relation Subsets 		Applies subset requirements to the **existential relation requirement** (see above) of the query .../subsets/cancer/ The relation subsets are completely independent of the query subsets, and valid values depend on the type of the existential resource. When multiple existential relations are specified, the subsets must be prefixed with "<EXT_RELATION>." to identify which they apply to.
/[<VIEW>.html] OR
.<FORMAT>[:<OUTPUT_FIELD>[+<OUTPUT_FIELD>...]] 		(Formatting)
Formatting Options 		Dictates how the result of a query will be returned. If <FORMAT> is specified the result will be sent as a download. If a <VIEW> is specified the result will be rendered as HTML. If neither is provided (just "/") the "**Accept**" header will be interrogated to determine the requested format, which defaults to HTML. .json:public_identifier+name +num_genes+num_substances Valid views (currently) include table or tile. The default is always tile. Valid ZINC15:Formats are explained in the wiki. Valid <OUTPUT_FIELD>s depend on the specific resource being requested, and can be found on the resource help pages.


Query Root

There are three basic types of queries supported by ZINC15.

Kind Syntax Description Example
Full Resource Listing /<RESOURCE> Performs the query on all <RESOURCE>s /genes
Single Resource Lookup /<RESOURCE>/<IDENTIFIER> Retrieves information about a specific <RESOURCE> instance identified by <IDENTIFIER> /genes/ADRB1
Single Resource Relation /<RESOURCE>/<IDENTIFIER>/<RELATION> Performs the query on only resources that are linked to a specific instance of a <RESOURCE> identified by <IDENTIFIER> via the <RELATION> relationship. The type of the result will depend on the taret of <RELATION> (see below). /genes/ADRB1/substances

Parameters

Name Meaning Example Example URL Options
<RESOURCE> The name of a ZINC15 resource. catalogs /catalogs/ Wiki Explanation of Resources ZINC15 Meta-resource
<IDENTIFIER> The unique identifier (key) for a specific resource instance. ZINC000000000053 /substances/ZINC000000000053/ The identifier column is listed on each resources' "help" page (e.g. [1]) and can also always be accessed via the `public_identifier` attribute of a resource instance.
<RELATION> The name of a relation defined on <RESOURCE> objects. activities /substances/ZINC000000000053/activities The name and type of each resources' relations is defined on the "help" page (e.g. [2])

Note that a query rooted on /catalog/sial/items will not return **catalogs**, but instead **catitems**, as the catalog relation named **items** returns **catitem** resources. This can be seen on the Catalog Help Page.


The items in [ square brackets ] are optional. The items in < angled braces > are each described below.

  • <RESOURCE> is an object type, such as molecules, catalogs or genes, and are fully described here: ZINC15:Resources
  • <FORMAT> is one of the supported formats, such as smi, sdf, csv, fully described here: ZINC15:Formats. If a format is omitted, a webpage is implicitly requested.
  • <FIELDS> are individual properties, including calculated ones, and are described together with the ZINC15:Resources to which they belong.

ZINC15:Properties Not all properties make sense in all resource contexts. ZINC15:examples are provided. Each resource has default fields, if none are specified.

  • <ENDPOINT> is one of (tile, table, detail, etc.) (only available if the underlying template exists); where items in [ square brackets ] are optional, and:
ZINC15:Variants.
  • <PREDICATE_LIST> is a query string, one or more of <PREDICATE> delimited by &<PREDICATE> is <ATTRIBUTE>[:<OPERATOR>[;<OPERATOR_ARGS>]]=<THRESHOLD>
  • ZINC15:Page Controls are optional, and are used to qualify how a search is to be performed and formatted for the page.
  • https is currently not supported, but it will be.

Reserved words

  • list, tile, subsets, help, overview - these have special meaning in the URL, and can never be the names of resources or their columns.

Examples

We illustrate the use of the website and the API with ZINC15:examples.

Back to ZINC15

Retrieved from "http://wiki.docking.org/index.php?title=ZINC15:Syntax&oldid=11358"