How to use SmallWorld API

From DISI
Jump to navigation Jump to search

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