API for Latent Environment Allocation Global Map
This is a brief specification document for the REST API used in LEA global map.
Resource Group ¶
Search samples ¶
Search samples APIGET/string/{searched_string}/samples{?n_limit}
-
Returns samples relevant to the input searche query.
- The upper limit of the number of samples is specified by n_limit.
- Samples are returned in descending order of their relevance within the upper limit.
- Each sample is returned as an object and has the following values:
- value: Score of relevance to the search query
- sample_id: Sample ID
-
Default value of n_limit is 10.
-
searched_string is a mandatory parameter. Returns Bad Request if not specified.
-
If there is no hit in the search result, return an empty array.
Example URI
- searched_string
string
(required) Example: hot springsearch query
- n_limit
number
(optional) Example: 10upper limit of the number of samples to return
200
Headers
Content-Type: application/json
Body
{
"sample_list": [
{
"sample_id": "DRS000009",
"value": 0.05
},
{
"sample_id": "ERS123456",
"value": 0.045
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"sample_list": {
"type": "array"
}
},
"required": [
"sample_list"
]
}
Semantic suggestion ¶
Semantic suggestion APIGET/string/{searched_string}/topics/semantic{?n_topic_limit,n_element_limit}
-
Returns words and microbes “semantically similar” to the input string, that is, words and microbes belonging to the most relevant topic.
- The upper limit of the number of topics is specified by n_topic_limit.
- The upper limit of the number of elements of each topic is specified by n_element_limit.
- Topics and elements are returned in descending order of their relevance within the upper limit.
-
Default value of n_topic_limit is 1.
-
Default value of n_element_limit is 5.
-
searched_string is a mandatory parameter. Returns Bad Request if not specified.
-
If there is no hit in the search result, return an empty array.
Example URI
- searched_string
string
(required) Example: hot springsearch query
- n_topic_limit
number
(optional) Example: 10upper limit of the number of topics to return
- n_element_limit
number
(optional) Example: 10upper limit of the number of elements of each topic to return
200
Headers
Content-Type: application/json
Body
{
"topic_list": [
{
"word": [
{
"word": "soil",
"value": 0.87
},
{
"word": "dog",
"value": 0.6
},
{
"word": "wood",
"value": 0.55
},
{
"word": "forest",
"value": 0.43
},
{
"word": "leaf",
"value": 0.23
}
],
"taxonomy": [
{
"taxon": "enterococcus",
"value": 0.95
},
{
"taxon": "streptococcus",
"value": 0.44
},
{
"taxon": "betabactor",
"value": 0.39
},
{
"taxon": "proteobacteria",
"value": 0.2
},
{
"taxon": "actinobacteria",
"value": 0.02
}
]
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"topic_list": {
"type": "array"
}
},
"required": [
"topic_list"
]
}
Ecological suggestion ¶
Ecological suggestion APIGET/string/{searched_string}/topics/ecological{?n_topic_limit,n_element_limit}
-
Returns words and microbes “ecologically related” to the input string, that is, words and microbes belonging to the topic close to the “semantically similar” topic on the LEA global map.
- The upper limit of the number of topics is specified by n_topic_limit.
- The upper limit of the number of elements of each topic is specified by n_element_limit.
- Topics and elements are returned in descending order of their relevance within the upper limit.
-
Default value of n_topic_limit is 1.
-
Default value of n_element_limit is 5.
-
searched_string is a mandatory parameter. Returns Bad Request if not specified.
-
If there is no hit in the search result, return an empty array.
Example URI
- searched_string
string
(required) Example: hot springsearch query
- n_topic_limit
number
(optional) Example: 3upper limit of the number of topics to return
- n_element_limit
number
(optional) Example: 5upper limit of the number of elements of each topic to return
200
Headers
Content-Type: application/json
Body
{
"topic_list": [
{
"word": [
{
"word": "soil",
"value": 0.43
},
{
"word": "dog",
"value": 0.22
},
{
"word": "wood",
"value": 0.11
},
{
"word": "forest",
"value": 0.06
},
{
"word": "leaf",
"value": 0.01
}
],
"taxonomy": [
{
"taxon": "enterococcus",
"value": 0.83
},
{
"taxon": "streptococcus",
"value": 0.55
},
{
"taxon": "betabactor",
"value": 0.4
},
{
"taxon": "proteobacteria",
"value": 0.3
},
{
"taxon": "actinobacteria",
"value": 0.23
}
]
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"topic_list": {
"type": "array"
}
},
"required": [
"topic_list"
]
}
Sample locations ¶
Sample locations APIGET/sample/location
- Returns sample coordinates on the LEA global map.
Example URI
200
Headers
Content-Type: application/json
Body
{
"sample_list": [
{
"x": 23.4,
"y": 235.2,
"color": "\"#9428ff\"",
"sample_id": "DRS000009"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"sample_list": {
"type": "array"
}
},
"required": [
"sample_list"
]
}
Sample metadata ¶
Sample metadata APIGET/sample/{sample_id}/metadata
-
Returns metadata of an input sample.
-
sample_id is a mandatory parameter. Returns Bad Request if not specified.
-
If there is no sample_id, return Not Found.
Example URI
- sample_id
string
(required) Example: DRS000009
200
Headers
Content-Type: application/json
Body
{
"metadata": {
"sample_name": "hot spring sample",
"sample_url": "http://example.com/SRS123456"
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"sample_name": {
"type": "string"
},
"sample_url": {
"type": "string"
}
},
"required": [
"sample_name",
"sample_url"
]
}
},
"required": [
"metadata"
]
}
Sample topic composition ¶
Sample topic composition APIGET/sample/{sample_id}/topics
-
Returns topic composition of an input sample.
-
sample_id is a mandatory parameter. Returns Bad Request if not specified.
-
If there is no sample_id, return Not Found.
Example URI
- sample_id
string
(required) Example: DRS000009
200
Headers
Content-Type: application/json
Body
{
"topic_list": [
{
"topic_id": 4,
"value": 0.34
},
{
"topic_id": 42,
"value": 0.29
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"topic_list": {
"type": "array"
}
},
"required": [
"topic_list"
]
}
Sample taxonomic composition ¶
Sample taxonomic composition APIGET/sample/{sample_id}/taxonomies/{taxon_rank}
-
Returns taxonomic composition of an input sample.
-
sample_id and taxon_rank are mandatory parameters. Returns Bad Request if not specified.
-
If there is no sample_id, return Not Found.
-
If invalid taxon_rank is specified, return Bad Request.
Example URI
- sample_id
string
(required) Example: DRS000009- taxon_rank
string
(required) Example: genus
200
Headers
Content-Type: application/json
Body
{
"taxonomy_list": [
{
"taxonomy_name": "firmicutes",
"value": 0.34
},
{
"taxonomy_name": "proteobacteria",
"value": 0.22
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"taxonomy_list": {
"type": "array"
}
},
"required": [
"taxonomy_list"
]
}
Topic locations ¶
Topic locations APIGET/topic/location
- Returns topic coordinates on the LEA global map.
Example URI
200
Headers
Content-Type: application/json
Body
{
"topic_list": [
{
"x": 23.4,
"y": 235.2,
"topic_id": 5
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"topic_list": {
"type": "array"
}
},
"required": [
"topic_list"
]
}
Topic metadata ¶
Topic metadata APIGET/topic/{topic_id}/metadata
-
Returns metadata of an input topic.
-
topic_id is a mandatory parameter. Returns Bad Request if not specified.
-
If there is no topic_id, return Not Found.
Example URI
- topic_id
number
(required) Example: 0
200
Headers
Content-Type: application/json
Body
{
"metadata": {
"Attribution": "No attribution required",
"ImageURL": "https://pixabay.com/en/background",
"License": "CC0 Public Domain"
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"Attribution": {
"type": "string"
},
"ImageURL": {
"type": "string",
"description": "blue-floor-ocean-sand-17520/ (string, required)"
},
"License": {
"type": "string"
}
},
"required": [
"Attribution",
"License"
]
}
},
"required": [
"metadata"
]
}
Topic words composition ¶
Topic words composition APIGET/topic/{topic_id}/words{?n_word_limit}
-
Returns words composition of an input topic.
- The upper limit of the number of words is specified by n_word_limit.
-
Default value of n_word_limit is 5.
-
topic_id is a mandatory parameter. Returns Bad Request if not specified.
-
If there is no topic_id, return Not Found.
Example URI
- topic_id
number
(required) Example: 4- n_word_limit
number
(optional) Example: 5upper limit of the number of words to return
200
Headers
Content-Type: application/json
Body
{
"word_list": [
{
"word": "dog",
"value": 0.34
},
{
"word": "foot",
"value": 0.21
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"word_list": {
"type": "array"
}
},
"required": [
"word_list"
]
}
Topic taxonomic composition ¶
Topic taxonomic composition APIGET/topic/{topic_id}/taxonomies/{taxon_rank}
-
Returns taxonomic composition of an input topic.
-
topic_id and taxon_rank are mandatory parameters. Returns Bad Request if not specified.
-
If there is no topic_id, return Not Found.
-
If invalid taxon_rank is specified, return Bad Request.
Example URI
- topic_id
number
(required) Example: 4- taxon_rank
string
(required) Example: genus
200
Headers
Content-Type: application/json
Body
{
"taxonomy_list": [
{
"taxonomy_name": "firmicutes",
"value": 0.34
},
{
"taxonomy_name": "proteobacteria",
"value": 0.25
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"taxonomy_list": {
"type": "array"
}
},
"required": [
"taxonomy_list"
]
}
Taxonomic color ¶
Taxonomic color APIGET/taxonomy/color
- Returns colors of each genus (same colors for genera belonging to the same phylum)
Example URI
200
Headers
Content-Type: application/json
Body
{
"taxonomy_list": [
{
"color": "#c7869e",
"taxonomy_name": "Methylobacillus"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"taxonomy_list": {
"type": "array"
}
},
"required": [
"taxonomy_list"
]
}
Predict new sample ¶
Predict new sample APIPOST/new_sample
-
Receives the VITCOMIC2 cluster file (for a single sample, or gzip compressed tar archive for multiple samples) and returns their coordinates.
-
cluster_file are mandatory parameters. Returns Bad Request if not specified.
-
Returns Bad Request if cluster_file is neither application/octet-stream (for a single sample) nor application/x-gzip (for multiple samples).
Example URI
Headers
Content-Type: application/octet-stream
Headers
Content-Type: application/x-gzip
200
Headers
Content-Type: application/json
Body
{
"new_sample_list": [
{
"project_id": "20170420051049db365f9fd4982d274d378c79d35fda30",
"sample_id": "Kako",
"x": 149.6,
"y": 3.9,
"color": "#fde724"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"new_sample_list": {
"type": "array"
}
},
"required": [
"new_sample_list"
]
}
Predict new sample by 100 Gibbs sampling chains ¶
Predict new sample 100 Gibbs APIPOST/new_sample_sd
-
Receives the VITCOMIC2 cluster file (for a single sample, or gzip compressed tar archive for multiple samples) and returns their topic proportions.
-
Topic proportions are calculated by drawing 100 samples from 100 independent Gibbs sampling chains with different initial settings and by averaging 100 samples. This also provides standard deviations of each topic proportion estimates.
-
The calculation takes a very long long time, so please be patient.
-
cluster_file are mandatory parameters. Returns Bad Request if not specified.
-
Returns Bad Request if cluster_file is neither application/octet-stream (for a single sample) nor application/x-gzip (for multiple samples).
-
For example, if you run with curl: “curl -X POST http://snail.nig.ac.jp/leaapi/new_sample_sd -F ‘cluster_file=@my_samples.tar.gz;type=application/x-gzip’ > result.json”
Example URI
Headers
Content-Type: application/octet-stream
Headers
Content-Type: application/x-gzip
200
Headers
Content-Type: application/json
Body
{
"new_sample_list": [
{
"project_id": "20170420051049db365f9fd4982d274d378c79d35fda30",
"sample_id": "Kako",
"topic_list": [
{
"topic_id": 0,
"mean": 0.34,
"sd": 0.02
},
{
"topic_id": 1,
"mean": 0.02,
"sd": 0.00018
}
]
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"new_sample_list": {
"type": "array"
}
},
"required": [
"new_sample_list"
]
}
New sample locations ¶
New sample locations APIGET/newsample/{project_id}/location
- Returns new sample coordinates on the LEA global map.
Example URI
- project_id
string
(required) Example: 20170420051049db365f9fd4982d274d378c79d35fda30
200
Headers
Content-Type: application/json
Body
{
"new_sample_list": [
{
"project_id": "20170420051049db365f9fd4982d274d378c79d35fda30",
"sample_id": "Kako",
"x": 149.6,
"y": 3.9,
"color": "#fde724"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"new_sample_list": {
"type": "array"
}
},
"required": [
"new_sample_list"
]
}
New sample topic composition ¶
New sample topic composition APIGET/newsample/{project_id}/{sample_id}/topics
-
Returns topic composition of input project_id and sample_id.
-
If there is no project_id or sample_id, return Not Found.
Example URI
- project_id
string
(required) Example: 20170420051049db365f9fd4982d274d378c79d35fda30- sample_id
string
(required) Example: Kako
200
Headers
Content-Type: application/json
Body
{
"topic_list": [
{
"topic_id": 4,
"value": 0.34
},
{
"topic_id": 42,
"value": 0.29
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"topic_list": {
"type": "array"
}
},
"required": [
"topic_list"
]
}
New sample taxonomic composition ¶
New sample taxonomic composition APIGET/newsample/{project_id}/{sample_id}/taxonomies/{taxon_rank}
-
Returns taxonomic composition of input project_id and sample_id.
-
If there is no project_id or sample_id, return Not Found.
-
If invalid taxon_rank is specified, return Bad Request.
Example URI
- project_id
string
(required) Example: 20170420051049db365f9fd4982d274d378c79d35fda30- sample_id
string
(required) Example: Kako- taxon_rank
string
(required) Example: genus
200
Headers
Content-Type: application/json
Body
{
"taxonomy_list": [
{
"taxonomy_name": "firmicutes",
"value": 0.34
},
{
"taxonomy_name": "proteobacteria",
"value": 0.22
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"taxonomy_list": {
"type": "array"
}
},
"required": [
"taxonomy_list"
]
}