How to use SmallWorld API: Difference between revisions

From DISI
Jump to navigation Jump to search
mNo edit summary
m (asdf)
 
(19 intermediate revisions by one other user not shown)
Line 1: Line 1:
=Introduction=
=Introduction=


The Web Services API for SmallWorld Documentation is found in Section 7.3 of the SmallWorld version 5.5.3 manual.   
The Web Services API for SmallWorld Documentation is found in Section 6.3 of the SmallWorld version 5.6.2 manual.   
Copyright ©2012-2017 NextMove Software Limited.
I copied the section here, and provided a list of publicly available databases for searching on sw.docking.org and some simple examples.


==8.3 Web Services API Important Entry Points==
Here are some simple examples.
Unless stated otherwise all API entry points operate on HTTP GET/POST requests. A search on the server is first submitted (/search/submit), this returns a stream of events that report the hit list id (hlid). You can then use this hlid to fetch results either as JSON (/search/view) or TSV (/ search/export).


===/search/submit===
=API Routes=


Start a new SmallWorld search with topological distance bounded by the provided upper bounds.
==/search/maps==
'''List all available databases (map files).'''
 
<source> curl "https://sw.docking.org/search/maps" </source>
 
==/search/view==
'''View the results of a search.'''
 
Access the results of a search either using the a hit-list id or by using the query parameters to start
a new search automatically.


{| class="wikitable"
{| class="wikitable"
Line 17: Line 23:
! Type
! Type
! Description
! Description
|-
| id
| integer
| Hit List id
|-
|-
| smi
| smi
| text
| array
| Query SMILES
| Query SMILES/SMARTS strings
|-
|-
| db
| db
| text
| string
| Reference database (see List of available maps)
| Database name
|-
|-
| fmt
| string
| Format of results: tsv,csv
|-
| start
| integer
| Number of hits returned starting from this index
|-
| length
| integer
| Number of total hits returned
|-
| scores
| string
| Scoring function(s) to use
|-
| top
| integer
| Only collect this many (top) results, this option allows more resource efficient searches
|-
| async
| boolean
| Start new searches asynchronously or not (returns right away) or wait until timeout for search to run (default)
|-
| dist
| dist
| int
| string
| Topological distance upper bound (default: 10)
| Maximum Anonymous Distance
|-
| sdist
| string
| Maximum Scored Distance
|-
| tdn
| string
| Terminal Down Bounds
|-
|-
| tdn
| int
| Topological terminal down distance upper bound (default: 10)
|-
| tup
| tup
| int
| string
| Topological terminal up distance upper bound (default: 10)
| Terminal Up Bounds
|-
|-
| rdn
| rdn
| int
| string
| Topological ring down distance upper bound (default: 10)
| Ring Down Bounds
|-  
|-  
| rup
| rup
| int
| string
| Topological ring up distance upper bound (default: 10)
| Ring Up Bounds
|-
|-
| ldn
| ldn
| int
| string
| Topological linker down distance upper bound (default: 10)
| Linker Down Bounds
|-
|-
| lup
| lup
| int
| string
| Topological linker up distance upper bound (default: 10)
| Linker Up Bounds
|-
| maj
| string
| Major Transmutation Bounds (Aligned Atom Scores only)
|-
| min
| string
| Minor Transmutation Bounds (Aligned Atom Scores only)
|-
| sub
| string
| Substitution Bounds (Aligned Atom Scores only)
|-
| hyb
| string
| Hybridisation Bounds (Aligned Atom Scores only)
|-
| ms
| string
| Interpret a single SMILES query with multiple components as a multi-source (ms) search.
|-
|-
| scores
| text
| List of scoring functions (default : none) - see /search/config
|}
|}


===Example Request===
= Examples =
Suppose you want to search for c1ccccc1 in the ZINC-Interesting-297K Database:  There are two steps. The first step which involves /search/submit returns a stream of events that report the hit list id or hlid.  This hlid is required to fetch results using the other options such as /search/view
<source> </source>
 
== /search/view  ==
*Change the smi to the SMILES for the molecule you want to query
=== Basic Usage ===
*Change the db name to the database name from the List of Publicly Available Maps below
# Search of similar entries to benzene in ZINC-All-22Q2-1.6B
Everything else can stay the same
#: <source> curl "https://sw.docking.org/search/view?smi=c1ccccc1&db=ZINC-All-22Q2-1.6B" </source>
 
# Search of similar entries to pyridine in ZINC-All-22Q2-1.6B. Display in TSV. Show results from 0 to 50
    curl https://sw.docking.org/search/submit?smi=c1ccccc1&db=ZINC20-ForSale-22Q1-1.6B&dist=4&tdn=4&tup=4&rdn=4&rup=4&ldn=4&lup=4&maj=4&min=4&sub=4&scores=Atom%20Alignment,ECFP4,Daylight
#: <source> curl "https://sw.docking.org/search/view?smi=c1ccccc1&db=ZINC-All-22Q2-1.6B&fmt=tsv&start=0&length=50" </source>
 
=== Advanced Usage ===
The API streams back JSON chunks. Possible status messages are FIRST, MORE, END, and ‘Ground Control to Major Tom’ (hangup ping). Each status contains the hit list id (hlid) which can be used with the export and view API entry points.
==== Multi-Start Search ====
 
# Search of similar entries to either benzene or the chlorobenzene in ZINC-All-22Q2-1.6B. Display in TSV. Only show top 20 results.
From this example:
#: <source> curl "https://sw.docking.org/search/view?smi=c1ccccc1&smi=Clc1ccccc1&db=ZINC-All-22Q2-1.6B&fmt=tsv&length=30&top=20" </source>
<source>
# Search of similar entries to either benzene or the chlorobenzene in ZINC-All-22Q2-1.6B. Tagging which molecule the similarity is closest to. Display in TSVDisplay 30 results
data:{"status":"FIRST","hlid":4,"elap":"0.0 s","numEdges":0,"numNodes":0,"numWaveFront":0,"numEdgesPerSec":"NaN"}
#: <source> curl "https://sw.docking.org/search/view?smi=c1ccccc1%20benzene&smi=Clc1ccccc1%20chlorobenzene&db=ZINC-All-22Q2-1.6B&fmt=tsv&length=30" </source>
 
# Search of similar entries of 12 different molecules in ZINC-All-22Q2-1.6B.
data:{"status":"MORE","hlid":4,"elap":"0.0 s","numEdges":1,"numNodes":2,"numWaveFront":6,"numEdgesPerSec":235.13693552145494}
#: <source> curl 'https://sw.docking.org/search/view?smi=c1ccccc1%20ONE&smi=Clc1ccccc1%20TWO&smi=C1=CC=C2C(=C1)C(=C(N2)O)C3=NC4=CC=CC=C4C3=O%20Three&smi=Oc3c(N=Nc1ccc(Br)cc1S(O)(=O)=O)c(S(O)(=O)=O)cc4cc(S(O)(=O)=O)c(N=Nc2ccc(Br)cc2S(O)(=O)=O)c(O)c34%20FOUR&smi=Nc5c(N=Nc4ccc(c3ccc(N=Nc2cc(S(O)(=O)=O)c1ccccc1c2N)cc3)cc4)cc(S(O)(=O)=O)c6ccccc56%20FIVE&smi=OC(=O)c1ccccc1C(c2cc(I)c(O)c(I)c2)=c3cc(I)c(=O)c(I)c3%20SIX&smi=Oc2cc(S(O)(=O)=O)c1ccccc1c2N=Nc4ccc3ccccc3c4O%20SEVEN&smi=Oc2ccc1ccccc1c2N=Nc3c(O)cc(S(O)(=O)=O)c4ccccc34%20Eight&smi=Cn1cnc2c1c(=O)n(c(=O)n2C)C%20NINE&smi=CCCCCCC(Oc3ccc(S(=O)(=O)c2ccc(OCc1ccccc1)cc2)cc3)C(O)=O%20TEN&smi=OC(=O)COc3ccc(N=Nc2ccc1cc(Br)ccc1c2O)cc3%20Eleven&smi=C1=CC(=C(C=C1C2=C(C(=O)C3=C(C=C(C=C3O2)O)O)O)O)O%20Twelve&db=ZINC-All-22Q2-1.6B&fmt=tsv&length=30' </source>
 
data:{"status":"MORE","hlid":4,"elap":"0.0 s","numEdges":7,"numNodes":8,"numWaveFront":20,"numEdgesPerSec":627.698881010172}
 
data:{"status":"MORE","hlid":4,"elap":"0.0 s","numEdges":47,"numNodes":42,"numWaveFront":57,"numEdgesPerSec":1398.0183120172226}
 
data:{"status":"MORE","hlid":4,"elap":"0.1 s","numEdges":361,"numNodes":215,"numWaveFront":218,"numEdgesPerSec":3172.39634840835}
 
data:{"status":"Ground Control to Major Tom","hlid":4,"elap":"0.3 s","numEdges":1358,"numNodes":661,"numWaveFront":104,"numEdgesPerSec":4439.029279091838}
 
data:{"status":"END","hlid":4,"elap":"0.5 s","numEdges":2417,"numNodes":981,"numWaveFront":0,"numEdgesPerSec":4984.08672048595} </source>
 
Here the hlid for my request was 4.
 
===/search/export===
Export a hit list (given by the id) to a tab-separated value table. The other parameters describe what columns, order, and filters are applied to the hit list. Like /search/view it uses the JQuery DataTables server-side processing parameters - https://www.datatables.net/manual/server-side.
 
Useful information about column names and values:
'hlid': hlid,
 
'columns[0][data]': 0,
'columns[0][name]': 'alignment',
'columns[0][searchable]': 'true',
'columns[0][orderable]': 'false',
'columns[0][search][value]': '',
'columns[0][search][regex]': 'false',
 
'columns[1][data]': 1,
'columns[1][name]': 'dist',
'columns[1][searchable]': 'true',
'columns[1][orderable]': 'true',
'columns[1][search][value]': '0 - 10',
'columns[1][search][regex]': 'false',
 
'columns[2][data]': 2,
'columns[2][name]': 'ecfp4',
'columns[2][searchable]': 'true',
'columns[2][orderable]': 'true',
'columns[2][search][value]': '',
'columns[2][search][regex]': 'false',
 
'columns[3][data]': 3,
'columns[3][name]': 'daylight',
'columns[3][searchable]': 'true',
'columns[3][orderable]': 'true',
'columns[3][search][value]': '',
'columns[3][search][regex]': 'false',
 
'columns[4][data]': 4,
'columns[4][name]': 'topodist',
'columns[4][searchable]': 'true',
'columns[4][orderable]': 'true',
'columns[4][search][value]': '0 - 10',
'columns[4][search][regex]': 'false',
 
'columns[5][data]': 5,
'columns[5][name]': 'mces',
'columns[5][searchable]': 'true',
'columns[5][orderable]': 'true',
'columns[5][search][value]': '',
'columns[5][search][regex]': 'false',
 
'columns[6][data]': 6,
'columns[6][name]': 'tdn',
'columns[6][searchable]': 'true',
'columns[6][orderable]': 'true',
'columns[6][search][value]': '0 - 0',
'columns[6][search][regex]': 'false',
 
'columns[7][data]': 7,
'columns[7][name]': 'tup',
'columns[7][searchable]': 'true',
'columns[7][orderable]': 'true',
'columns[7][search][value]': '0 - 10',
'columns[7][search][regex]': 'false',
 
'columns[8][data]': 8,
'columns[8][name]': 'rdn',
'columns[8][searchable]': 'true',
'columns[8][orderable]': 'true',
'columns[8][search][value]': '0 - 0',
'columns[8][search][regex]': 'false',
 
'columns[9][data]': 9,
'columns[9][name]': 'rup',
'columns[9][searchable]': 'true',
'columns[9][orderable]': 'true',
'columns[9][search][value]': '0 - 10',
'columns[9][search][regex]': 'false',
 
'columns[10][data]': 10,
'columns[10][name]': 'ldn',
'columns[10][searchable]': 'true',
'columns[10][orderable]':
 
=Important! Once you run the /search/submit the most important value is the hlid=
 
The columns in the resulting tab separated file are  alignment dist ecfp4 daylight topodist mces tdn tup rdn rup ldn lup mut maj min hyb sub
The results are sorted in starting with the highest ECFP4
===Example Request===
*Here you only need to change the hlid!
 
    curl 'https://sw.docking.org//search/export/?hlid=4&draw=8&columns%5B0%5D%5Bdata%5D=0&columns%5B0%5D%5Bname%5D=alignment&columns%5B0%5D%5Bsearchable%5D=true&columns%5B0%5D%5Borderable%5D=false&columns%5B0%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B0%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B1%5D%5Bdata%5D=1&columns%5B1%5D%5Bname%5D=dist&columns%5B1%5D%5Bsearchable%5D=true&columns%5B1%5D%5Borderable%5D=true&columns%5B1%5D%5Bsearch%5D%5Bvalue%5D=0-10&columns%5B1%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B2%5D%5Bdata%5D=2&columns%5B2%5D%5Bname%5D=ecfp4&columns%5B2%5D%5Bsearchable%5D=true&columns%5B2%5D%5Borderable%5D=true&columns%5B2%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B2%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B3%5D%5Bdata%5D=3&columns%5B3%5D%5Bname%5D=daylight&columns%5B3%5D%5Bsearchable%5D=true&columns%5B3%5D%5Borderable%5D=true&columns%5B3%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B3%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B4%5D%5Bdata%5D=4&columns%5B4%5D%5Bname%5D=topodist&columns%5B4%5D%5Bsearchable%5D=true&columns%5B4%5D%5Borderable%5D=true&columns%5B4%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B4%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B5%5D%5Bdata%5D=5&columns%5B5%5D%5Bname%5D=mces&columns%5B5%5D%5Bsearchable%5D=true&columns%5B5%5D%5Borderable%5D=true&columns%5B5%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B5%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B6%5D%5Bdata%5D=6&columns%5B6%5D%5Bname%5D=tdn&columns%5B6%5D%5Bsearchable%5D=true&columns%5B6%5D%5Borderable%5D=true&columns%5B6%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B6%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B7%5D%5Bdata%5D=7&columns%5B7%5D%5Bname%5D=tup&columns%5B7%5D%5Bsearchable%5D=true&columns%5B7%5D%5Borderable%5D=true&columns%5B7%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B7%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B8%5D%5Bdata%5D=8&columns%5B8%5D%5Bname%5D=rdn&columns%5B8%5D%5Bsearchable%5D=true&columns%5B8%5D%5Borderable%5D=true&columns%5B8%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B8%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B9%5D%5Bdata%5D=9&columns%5B9%5D%5Bname%5D=rup&columns%5B9%5D%5Bsearchable%5D=true&columns%5B9%5D%5Borderable%5D=true&columns%5B9%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B9%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B10%5D%5Bdata%5D=10&columns%5B10%5D%5Bname%5D=ldn&columns%5B10%5D%5Bsearchable%5D=true&columns%5B10%5D%5Borderable%5D=true&columns%5B10%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B10%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B11%5D%5Bdata%5D=11&columns%5B11%5D%5Bname%5D=lup&columns%5B11%5D%5Bsearchable%5D=true&columns%5B11%5D%5Borderable%5D=true&columns%5B11%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B11%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B12%5D%5Bdata%5D=12&columns%5B12%5D%5Bname%5D=mut&columns%5B12%5D%5Bsearchable%5D=true&columns%5B12%5D%5Borderable%5D=true&columns%5B12%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B12%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B13%5D%5Bdata%5D=13&columns%5B13%5D%5Bname%5D=maj&columns%5B13%5D%5Bsearchable%5D=true&columns%5B13%5D%5Borderable%5D=true&columns%5B13%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B13%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B14%5D%5Bdata%5D=14&columns%5B14%5D%5Bname%5D=min&columns%5B14%5D%5Bsearchable%5D=true&columns%5B14%5D%5Borderable%5D=true&columns%5B14%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B14%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B15%5D%5Bdata%5D=15&columns%5B15%5D%5Bname%5D=hyb&columns%5B15%5D%5Bsearchable%5D=true&columns%5B15%5D%5Borderable%5D=true&columns%5B15%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B15%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B16%5D%5Bdata%5D=16&columns%5B16%5D%5Bname%5D=sub&columns%5B16%5D%5Bsearchable%5D=true&columns%5B16%5D%5Borderable%5D=true&columns%5B16%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B16%5D%5Bsearch%5D%5Bregex%5D=false&order%5B0%5D%5Bcolumn%5D=0&order%5B0%5D%5Bdir%5D=asc&start=0&length=18&search%5Bvalue%5D=&search%5Bregex%5D=false&_=1561063193443'
 
The result should be a tab-separated file.  An example of the first 5 rows of data is shown below:
    alignment  dist    ecfp4  daylight    topodist    mces    tdn tup rdn rup ldn lup mut maj min hyb sub
    c1ccccc1 ZINC000000967532  0  1.0 1.0 0  6  0  0  0  0  0  0  0  0  0  0  0
    Cc1ccccc1 ZINC000000967534  1  0.25    0.5 1  6  0  1  0  0  0  0  0  0  0  0  1
    Clc1ccccc1 ZINC000000896527 1  0.25    0.46153846153846156 1  6  0  1  0  0  0  0  0  0  0  0  1
    Nc1ccccc1 ZINC000017886255 1  0.25    0.46153846153846156 1  6  0  1  0  0  0  0  0  0  0  0  1
    Oc1ccccc1 ZINC000005133329  1  0.25    0.46153846153846156 1  6  0  1  0  0  0  0  0  0  0  0  1
 
==List of Publicly Available Maps==
 
Find updated list of maps
https://sw.docking.org/search/maps
 
==The SmallWorld API provides the following additional entry points:==
 
===/search/view===
Provides data in JSON format.
 
*Here again you only need to change the hlid
 
    curl 'https://sw.docking.org//search/view/?hlid=4&draw=8&columns%5B0%5D%5Bdata%5D=0&columns%5B0%5D%5Bname%5D=alignment&columns%5B0%5D%5Bsearchable%5D=true&columns%5B0%5D%5Borderable%5D=false&columns%5B0%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B0%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B1%5D%5Bdata%5D=1&columns%5B1%5D%5Bname%5D=dist&columns%5B1%5D%5Bsearchable%5D=true&columns%5B1%5D%5Borderable%5D=true&columns%5B1%5D%5Bsearch%5D%5Bvalue%5D=0-10&columns%5B1%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B2%5D%5Bdata%5D=2&columns%5B2%5D%5Bname%5D=ecfp4&columns%5B2%5D%5Bsearchable%5D=true&columns%5B2%5D%5Borderable%5D=true&columns%5B2%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B2%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B3%5D%5Bdata%5D=3&columns%5B3%5D%5Bname%5D=daylight&columns%5B3%5D%5Bsearchable%5D=true&columns%5B3%5D%5Borderable%5D=true&columns%5B3%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B3%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B4%5D%5Bdata%5D=4&columns%5B4%5D%5Bname%5D=topodist&columns%5B4%5D%5Bsearchable%5D=true&columns%5B4%5D%5Borderable%5D=true&columns%5B4%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B4%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B5%5D%5Bdata%5D=5&columns%5B5%5D%5Bname%5D=mces&columns%5B5%5D%5Bsearchable%5D=true&columns%5B5%5D%5Borderable%5D=true&columns%5B5%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B5%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B6%5D%5Bdata%5D=6&columns%5B6%5D%5Bname%5D=tdn&columns%5B6%5D%5Bsearchable%5D=true&columns%5B6%5D%5Borderable%5D=true&columns%5B6%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B6%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B7%5D%5Bdata%5D=7&columns%5B7%5D%5Bname%5D=tup&columns%5B7%5D%5Bsearchable%5D=true&columns%5B7%5D%5Borderable%5D=true&columns%5B7%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B7%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B8%5D%5Bdata%5D=8&columns%5B8%5D%5Bname%5D=rdn&columns%5B8%5D%5Bsearchable%5D=true&columns%5B8%5D%5Borderable%5D=true&columns%5B8%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B8%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B9%5D%5Bdata%5D=9&columns%5B9%5D%5Bname%5D=rup&columns%5B9%5D%5Bsearchable%5D=true&columns%5B9%5D%5Borderable%5D=true&columns%5B9%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B9%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B10%5D%5Bdata%5D=10&columns%5B10%5D%5Bname%5D=ldn&columns%5B10%5D%5Bsearchable%5D=true&columns%5B10%5D%5Borderable%5D=true&columns%5B10%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B10%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B11%5D%5Bdata%5D=11&columns%5B11%5D%5Bname%5D=lup&columns%5B11%5D%5Bsearchable%5D=true&columns%5B11%5D%5Borderable%5D=true&columns%5B11%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B11%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B12%5D%5Bdata%5D=12&columns%5B12%5D%5Bname%5D=mut&columns%5B12%5D%5Bsearchable%5D=true&columns%5B12%5D%5Borderable%5D=true&columns%5B12%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B12%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B13%5D%5Bdata%5D=13&columns%5B13%5D%5Bname%5D=maj&columns%5B13%5D%5Bsearchable%5D=true&columns%5B13%5D%5Borderable%5D=true&columns%5B13%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B13%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B14%5D%5Bdata%5D=14&columns%5B14%5D%5Bname%5D=min&columns%5B14%5D%5Bsearchable%5D=true&columns%5B14%5D%5Borderable%5D=true&columns%5B14%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B14%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B15%5D%5Bdata%5D=15&columns%5B15%5D%5Bname%5D=hyb&columns%5B15%5D%5Bsearchable%5D=true&columns%5B15%5D%5Borderable%5D=true&columns%5B15%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B15%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B16%5D%5Bdata%5D=16&columns%5B16%5D%5Bname%5D=sub&columns%5B16%5D%5Bsearchable%5D=true&columns%5B16%5D%5Borderable%5D=true&columns%5B16%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B16%5D%5Bsearch%5D%5Bregex%5D=false&order%5B0%5D%5Bcolumn%5D=0&order%5B0%5D%5Bdir%5D=asc&start=0&length=18&search%5Bvalue%5D=&search%5Bregex%5D=false&_=1561063193443'
 
===/search/maps===
Lists all available dataset mapfiles. The response is a JSON detailing the map name, id prefix, resolve url


Example Request:
==== Asynchronous Searching ====
    curl https://sw.docking.org/search/maps
# Search of similar entries to benzene in ZINC-All-22Q2-1.6B. Show 3 results that are within distance 1~2. Use an asynchronous query.
#:<source> curl "https://sw.docking.org/search/view?smi=c1ccccc1&db=ZINC-All-22Q2-1.6B&start=0&length=2&dist=1-2&async=true" | jq </source>
#* When running asynchronous searches it is useful to use the JSON output as this reports what the search is doing in the background
#* After calling once the server will return right away and you will see something like:
#*: <source>
{
  "draw": 0,
  "recordsTotal": 0,
  "recordsFiltered": 0,
  "status": {
    "dist": 0,
    "state": "RUNNING",
    "restarts": 0,
    "nodeHits": 0,
    "nodeVisit": 0,
    "edgeVisit": 0,
    "elapTime": 0,
    "runTime": 0,
    "wavefront": 0
  },
  "data": []
}
</source>
#* The search will tell you when it has finished and be marked as DONE:
#*: <source>
{
  "draw": 0,
  "recordsTotal": 19195,
  "recordsFiltered": 19046,
  "status": {
    "dist": 2,
    "state": "DONE",
    "restarts": 6,
    "nodeHits": 35,
    "nodeVisit": 41,
    "edgeVisit": 46,
    "elapTime": 47685,
    "runTime": 2529,
    "wavefront": 0
  },
  "data": [
    [
      {
        "id": "ZINC000078108232",
        "qryMappedSmiles": "[CH:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1",
        "hitMappedSmiles": "[CH2:1]=[CH:2]/[CH:3]=[CH:4]\\[CH:5]=[CH2:6]",
        "anonIdx": "B5R0.2",
        "mf": "C<sub>6</sub>H<sub>8</sub>",
        "mw": "80.128",
        "atomMap": [
          0,
          1,
          2,
          3,
          4,
          5
        ],
        "atomScore": [
          2,
          1,
          1,
          1,
          1,
          2
        ],
        "hitSmiles": "C=C\\C=C/C=C ZINC000078108232",
        "qrySmiles": "c1ccccc1"
      },
      0.0,
      0.07692307692307693,
      1,
      1
    ],
    [
      {
        "id": "ZINC000001592588",
        "qryMappedSmiles": "[CH:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1",
        "hitMappedSmiles": "[CH2:1]=[CH:2]/[CH:3]=[CH:4]/[CH:5]=[CH2:6]",
        "anonIdx": "B5R0.2",
        "mf": "C<sub>6</sub>H<sub>8</sub>",
        "mw": "80.128",
        "atomMap": [
          0,
          1,
          2,
          3,
          4,
          5
        ],
        "atomScore": [
          2,
          1,
          1,
          1,
          1,
          2
        ],
        "hitSmiles": "C=C\\C=C\\C=C ZINC000001592588",
        "qrySmiles": "c1ccccc1"
      },
      0.0,
      0.07692307692307693,
      1,
      1
    ]
  ]
}
</source>


===/search/config===
Retrieves the public server configuration as JSON including the list of available score functions. The names of the scoring functions can be provided as a parameter to the /search/submit endpoint.
Example Request:
    curl https://sw.docking.org/search/config


[[Category: API]]
[[Category: API]]
[[Category: SmallWorld]]
[[Category: Smallworld]]
[[Category: NextMove]]
[[Category: NextMove]]

Latest revision as of 23:31, 31 May 2024

Introduction

The Web Services API for SmallWorld Documentation is found in Section 6.3 of the SmallWorld version 5.6.2 manual.

Here are some simple examples.

API Routes

/search/maps

List all available databases (map files).

 curl "https://sw.docking.org/search/maps"

/search/view

View the results of a search.

Access the results of a search either using the a hit-list id or by using the query parameters to start a new search automatically.

Parameter Type Description
id integer Hit List id
smi array Query SMILES/SMARTS strings
db string Database name
fmt string Format of results: tsv,csv
start integer Number of hits returned starting from this index
length integer Number of total hits returned
scores string Scoring function(s) to use
top integer Only collect this many (top) results, this option allows more resource efficient searches
async boolean Start new searches asynchronously or not (returns right away) or wait until timeout for search to run (default)
dist string Maximum Anonymous Distance
sdist string Maximum Scored Distance
tdn string Terminal Down Bounds
tup string Terminal Up Bounds
rdn string Ring Down Bounds
rup string Ring Up Bounds
ldn string Linker Down Bounds
lup string Linker Up Bounds
maj string Major Transmutation Bounds (Aligned Atom Scores only)
min string Minor Transmutation Bounds (Aligned Atom Scores only)
sub string Substitution Bounds (Aligned Atom Scores only)
hyb string Hybridisation Bounds (Aligned Atom Scores only)
ms string Interpret a single SMILES query with multiple components as a multi-source (ms) search.

Examples

/search/view

Basic Usage

  1. Search of similar entries to benzene in ZINC-All-22Q2-1.6B
     curl "https://sw.docking.org/search/view?smi=c1ccccc1&db=ZINC-All-22Q2-1.6B"
  2. Search of similar entries to pyridine in ZINC-All-22Q2-1.6B. Display in TSV. Show results from 0 to 50
     curl "https://sw.docking.org/search/view?smi=c1ccccc1&db=ZINC-All-22Q2-1.6B&fmt=tsv&start=0&length=50"

Advanced Usage

Multi-Start Search

  1. Search of similar entries to either benzene or the chlorobenzene in ZINC-All-22Q2-1.6B. Display in TSV. Only show top 20 results.
     curl "https://sw.docking.org/search/view?smi=c1ccccc1&smi=Clc1ccccc1&db=ZINC-All-22Q2-1.6B&fmt=tsv&length=30&top=20"
  2. Search of similar entries to either benzene or the chlorobenzene in ZINC-All-22Q2-1.6B. Tagging which molecule the similarity is closest to. Display in TSV. Display 30 results
     curl "https://sw.docking.org/search/view?smi=c1ccccc1%20benzene&smi=Clc1ccccc1%20chlorobenzene&db=ZINC-All-22Q2-1.6B&fmt=tsv&length=30"
  3. Search of similar entries of 12 different molecules in ZINC-All-22Q2-1.6B.
     curl 'https://sw.docking.org/search/view?smi=c1ccccc1%20ONE&smi=Clc1ccccc1%20TWO&smi=C1=CC=C2C(=C1)C(=C(N2)O)C3=NC4=CC=CC=C4C3=O%20Three&smi=Oc3c(N=Nc1ccc(Br)cc1S(O)(=O)=O)c(S(O)(=O)=O)cc4cc(S(O)(=O)=O)c(N=Nc2ccc(Br)cc2S(O)(=O)=O)c(O)c34%20FOUR&smi=Nc5c(N=Nc4ccc(c3ccc(N=Nc2cc(S(O)(=O)=O)c1ccccc1c2N)cc3)cc4)cc(S(O)(=O)=O)c6ccccc56%20FIVE&smi=OC(=O)c1ccccc1C(c2cc(I)c(O)c(I)c2)=c3cc(I)c(=O)c(I)c3%20SIX&smi=Oc2cc(S(O)(=O)=O)c1ccccc1c2N=Nc4ccc3ccccc3c4O%20SEVEN&smi=Oc2ccc1ccccc1c2N=Nc3c(O)cc(S(O)(=O)=O)c4ccccc34%20Eight&smi=Cn1cnc2c1c(=O)n(c(=O)n2C)C%20NINE&smi=CCCCCCC(Oc3ccc(S(=O)(=O)c2ccc(OCc1ccccc1)cc2)cc3)C(O)=O%20TEN&smi=OC(=O)COc3ccc(N=Nc2ccc1cc(Br)ccc1c2O)cc3%20Eleven&smi=C1=CC(=C(C=C1C2=C(C(=O)C3=C(C=C(C=C3O2)O)O)O)O)O%20Twelve&db=ZINC-All-22Q2-1.6B&fmt=tsv&length=30'

Asynchronous Searching

  1. Search of similar entries to benzene in ZINC-All-22Q2-1.6B. Show 3 results that are within distance 1~2. Use an asynchronous query.
     curl "https://sw.docking.org/search/view?smi=c1ccccc1&db=ZINC-All-22Q2-1.6B&start=0&length=2&dist=1-2&async=true" | jq
    • When running asynchronous searches it is useful to use the JSON output as this reports what the search is doing in the background
    • After calling once the server will return right away and you will see something like:
      {
        "draw": 0,
        "recordsTotal": 0,
        "recordsFiltered": 0,
        "status": {
          "dist": 0,
          "state": "RUNNING",
          "restarts": 0,
          "nodeHits": 0,
          "nodeVisit": 0,
          "edgeVisit": 0,
          "elapTime": 0,
          "runTime": 0,
          "wavefront": 0
        },
        "data": []
      }
    • The search will tell you when it has finished and be marked as DONE:
      {
        "draw": 0,
        "recordsTotal": 19195,
        "recordsFiltered": 19046,
        "status": {
          "dist": 2,
          "state": "DONE",
          "restarts": 6,
          "nodeHits": 35,
          "nodeVisit": 41,
          "edgeVisit": 46,
          "elapTime": 47685,
          "runTime": 2529,
          "wavefront": 0
        },
        "data": [
          [
            {
              "id": "ZINC000078108232",
              "qryMappedSmiles": "[CH:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1",
              "hitMappedSmiles": "[CH2:1]=[CH:2]/[CH:3]=[CH:4]\\[CH:5]=[CH2:6]",
              "anonIdx": "B5R0.2",
              "mf": "C<sub>6</sub>H<sub>8</sub>",
              "mw": "80.128",
              "atomMap": [
                0,
                1,
                2,
                3,
                4,
                5
              ],
              "atomScore": [
                2,
                1,
                1,
                1,
                1,
                2
              ],
              "hitSmiles": "C=C\\C=C/C=C ZINC000078108232",
              "qrySmiles": "c1ccccc1"
            },
            0.0,
            0.07692307692307693,
            1,
            1
          ],
          [
            {
              "id": "ZINC000001592588",
              "qryMappedSmiles": "[CH:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1",
              "hitMappedSmiles": "[CH2:1]=[CH:2]/[CH:3]=[CH:4]/[CH:5]=[CH2:6]",
              "anonIdx": "B5R0.2",
              "mf": "C<sub>6</sub>H<sub>8</sub>",
              "mw": "80.128",
              "atomMap": [
                0,
                1,
                2,
                3,
                4,
                5
              ],
              "atomScore": [
                2,
                1,
                1,
                1,
                1,
                2
              ],
              "hitSmiles": "C=C\\C=C\\C=C ZINC000001592588",
              "qrySmiles": "c1ccccc1"
            },
            0.0,
            0.07692307692307693,
            1,
            1
          ]
        ]
      }