How to use SmallWorld API: Difference between revisions

From DISI
Jump to navigation Jump to search
No edit summary
Line 190: Line 190:
#* <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>
#* <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>


=Example Request=
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
*Change the smi to the SMILES for the molecule you want to query
*Change the db name to the database name from the List of Publicly Available Maps below
Everything else can stay the same
    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'
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.
From this example:
<source>
data:{"status":"FIRST","hlid":4,"elap":"0.0 s","numEdges":0,"numNodes":0,"numWaveFront":0,"numEdgesPerSec":"NaN"}
data:{"status":"MORE","hlid":4,"elap":"0.0 s","numEdges":1,"numNodes":2,"numWaveFront":6,"numEdgesPerSec":235.13693552145494}
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:
    curl https://sw.docking.org/search/maps
===/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]]

Revision as of 23:57, 22 January 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
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.

/search/submit

Start a new SmallWorld search with topological distance bounded by the provided upper bounds.

Parameter Type Description
smi array Query SMILES/SMARTS strings (Required)
db string Database name (Required)
top integer Only collect this many (top) results, this option allows more resource efficient searches
dist string Maxmium Anonymous Distance
sdist string Maxmium Scored Distance
tdn int Topological terminal down distance upper bound (default: 10)
tup int Topological terminal up distance upper bound (default: 10)
rdn int Topological ring down distance upper bound (default: 10)
rup int Topological ring up distance upper bound (default: 10)
ldn int Topological linker down distance upper bound (default: 10)
lup int Topological linker up distance upper bound (default: 10)
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)

Examples

/search/view

  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"
  3. 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"
  4. 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"
Retrieved from "http://wiki.docking.org/index.php?title=How_to_use_SmallWorld_API&oldid=15596"