How to use SmallWorld API: Difference between revisions
Jump to navigation
Jump to search
Jgutierrez6 (talk | contribs) m (→Examples) |
Jgutierrez6 (talk | contribs) |
||
Line 181: | Line 181: | ||
<source> </source> | <source> </source> | ||
== /search/view == | == /search/view == | ||
=== Basic Usage === | |||
# Search of similar entries to benzene in ZINC-All-22Q2-1.6B | # Search of similar entries to benzene in ZINC-All-22Q2-1.6B | ||
#: <source> curl "https://sw.docking.org/search/view?smi=c1ccccc1&db=ZINC-All-22Q2-1.6B" </source> | #: <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 | # Search of similar entries to pyridine in ZINC-All-22Q2-1.6B. Display in TSV. Show results from 0 to 50 | ||
#: <source> curl "https://sw.docking.org/search/view?smi=c1ccccc1&db=ZINC-All-22Q2-1.6B&fmt=tsv&start=0&length=50" </source> | #: <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 === | |||
==== 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. | # Search of similar entries to either benzene or the chlorobenzene in ZINC-All-22Q2-1.6B. Display in TSV. Only show top 20 results. | ||
#: <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> curl "https://sw.docking.org/search/view?smi=c1ccccc1&smi=Clc1ccccc1&db=ZINC-All-22Q2-1.6B&fmt=tsv&length=30&top=20" </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 TSV. Display 30 results | # 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 | ||
#: <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> | ||
==== Asynchronous Searching ==== | |||
# Search of similar entries to benzene in ZINC-All-22Q2-1.6B. Show 5 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=5&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 | |||
], | |||
[ | |||
{ | |||
"id": "ZINC000307159050", | |||
"qryMappedSmiles": "[CH:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1", | |||
"hitMappedSmiles": "B[C:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1", | |||
"anonIdx": "B7R1.3", | |||
"mf": "C<sub>6</sub>H<sub>7</sub>B", | |||
"mw": "89.931", | |||
"atomMap": [ | |||
1, | |||
2, | |||
3, | |||
4, | |||
5, | |||
6 | |||
], | |||
"atomScore": [ | |||
6, | |||
2, | |||
1, | |||
1, | |||
1, | |||
1, | |||
1 | |||
], | |||
"hitSmiles": "Bc1ccccc1 ZINC000307159050", | |||
"qrySmiles": "c1ccccc1" | |||
}, | |||
0.25, | |||
0.5, | |||
1, | |||
1 | |||
], | |||
[ | |||
{ | |||
"id": "ZINC000000900729", | |||
"qryMappedSmiles": "[CH:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1", | |||
"hitMappedSmiles": "Br[C:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1", | |||
"anonIdx": "B7R1.3", | |||
"mf": "C<sub>6</sub>H<sub>5</sub>Br", | |||
"mw": "157.008", | |||
"atomMap": [ | |||
1, | |||
2, | |||
3, | |||
4, | |||
5, | |||
6 | |||
], | |||
"atomScore": [ | |||
6, | |||
2, | |||
1, | |||
1, | |||
1, | |||
1, | |||
1 | |||
], | |||
"hitSmiles": "Brc1ccccc1 ZINC000000900729", | |||
"qrySmiles": "c1ccccc1" | |||
}, | |||
0.25, | |||
0.46153846153846156, | |||
1, | |||
1 | |||
], | |||
[ | |||
{ | |||
"id": "ZINC000000967534", | |||
"qryMappedSmiles": "[CH:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1", | |||
"hitMappedSmiles": "C[C:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1", | |||
"anonIdx": "B7R1.3", | |||
"mf": "C<sub>7</sub>H<sub>8</sub>", | |||
"mw": "92.139", | |||
"atomMap": [ | |||
1, | |||
2, | |||
3, | |||
4, | |||
5, | |||
6 | |||
], | |||
"atomScore": [ | |||
6, | |||
2, | |||
1, | |||
1, | |||
1, | |||
1, | |||
1 | |||
], | |||
"hitSmiles": "Cc1ccccc1 ZINC000000967534", | |||
"qrySmiles": "c1ccccc1" | |||
}, | |||
0.25, | |||
0.5, | |||
1, | |||
1 | |||
] | |||
] | |||
} | |||
</source> | |||
Revision as of 00:43, 23 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
Basic Usage
- 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"
- 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
- 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"
- 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"
Asynchronous Searching
- Search of similar entries to benzene in ZINC-All-22Q2-1.6B. Show 5 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=5&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 ], [ { "id": "ZINC000307159050", "qryMappedSmiles": "[CH:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1", "hitMappedSmiles": "B[C:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1", "anonIdx": "B7R1.3", "mf": "C<sub>6</sub>H<sub>7</sub>B", "mw": "89.931", "atomMap": [ 1, 2, 3, 4, 5, 6 ], "atomScore": [ 6, 2, 1, 1, 1, 1, 1 ], "hitSmiles": "Bc1ccccc1 ZINC000307159050", "qrySmiles": "c1ccccc1" }, 0.25, 0.5, 1, 1 ], [ { "id": "ZINC000000900729", "qryMappedSmiles": "[CH:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1", "hitMappedSmiles": "Br[C:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1", "anonIdx": "B7R1.3", "mf": "C<sub>6</sub>H<sub>5</sub>Br", "mw": "157.008", "atomMap": [ 1, 2, 3, 4, 5, 6 ], "atomScore": [ 6, 2, 1, 1, 1, 1, 1 ], "hitSmiles": "Brc1ccccc1 ZINC000000900729", "qrySmiles": "c1ccccc1" }, 0.25, 0.46153846153846156, 1, 1 ], [ { "id": "ZINC000000967534", "qryMappedSmiles": "[CH:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1", "hitMappedSmiles": "C[C:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1", "anonIdx": "B7R1.3", "mf": "C<sub>7</sub>H<sub>8</sub>", "mw": "92.139", "atomMap": [ 1, 2, 3, 4, 5, 6 ], "atomScore": [ 6, 2, 1, 1, 1, 1, 1 ], "hitSmiles": "Cc1ccccc1 ZINC000000967534", "qrySmiles": "c1ccccc1" }, 0.25, 0.5, 1, 1 ] ] }