Difference between revisions of "Data Services"
(→Autocomplete) |
(→Gene annotations) |
||
| Line 344: | Line 344: | ||
All URI parameters are optional. If no JSON-formatted query specification is provided, all gene annotations will be returned. The <code>limit</code> parameter limits the number of results to the given integer count. This must be a positive integer. The <code>index</code> parameter can be used for pagination under a given sorting and limit regime. It should be greater than or equal to zero (the default). <code>desc</code> can be used to return the results in descending order (it is false by default). If a value is not provided for <code>sortby</code>, the sort order, limit, and start index are not very useful. | All URI parameters are optional. If no JSON-formatted query specification is provided, all gene annotations will be returned. The <code>limit</code> parameter limits the number of results to the given integer count. This must be a positive integer. The <code>index</code> parameter can be used for pagination under a given sorting and limit regime. It should be greater than or equal to zero (the default). <code>desc</code> can be used to return the results in descending order (it is false by default). If a value is not provided for <code>sortby</code>, the sort order, limit, and start index are not very useful. | ||
| + | |||
| + | '''Phenotype query specification''' | ||
| + | |||
| + | The value of <code>query</code> parameter should be a phenotype query represented as JSON, following this structure: | ||
| + | |||
| + | <javascript> | ||
| + | {} | ||
| + | </javascript> | ||
'''Returns''' | '''Returns''' | ||
Revision as of 17:38, 8 July 2010
This page details the data services that query the Phenoscape OBD database and transfer the retrieved results to the Phenoscape UI. Each service may support multiple media types. The desired media type can be specified by appending ?media=json or similar to the request URL. URI specifications are defined (loosely) using URI Templates.
Current services (under development)
These are currently only available at http://kb-dev.phenoscape.org/OBD-WS/
Timestamp
URI
<BASE URI>/timestamp
This service returns the date on which the Knowledgebase content was refreshed.
Returns
JSON: <javascript> { "refresh_date":"2010-01-09" }
</javascript>
Term info
URI
<BASE URI>/term/{term_id}
This is a generic term info service returning basic properties and relationships of a term, given its ID. The returned relationships are those included in the source ontology for the term, not all links to the term in the Knowledgebase.
Returns
JSON: <javascript> {
"id": "TAO:0000620", "definition": "Endochondral bone that is part of the antero-lateral region of the palate.
Commonly, it articulates with the maxilla anterolaterally and with the ethmoidal region medially. It may also articulate with the dermopalatine ventro-laterally and with the entopterygoid posteriorly. The autopalatine is paired.",
"name": "autopalatine",
"synonyms": [
{
"name": "palatine bone"
}],
"parents": [
{
"relation": {
"id": "OBO_REL:part_of",
"name": "part_of"
},
"target": {
"id": "TAO:0001272",
"name": "palatoquadrate arch"
}
},
{
"relation": {
"id": "develops_from",
"name": "develops from"
},
"target": {
"id": "TAO:0001399",
"name": "palatoquadrate cartilage"
}
},
{
"relation": {
"id": "OBO_REL:is_a",
"name": "is_a"
},
"target": {
"id": "TAO:0001591",
"name": "endochondral bone"
}
},
{
"relation": {
"id": "overlaps",
"name": "overlaps"
},
"target": {
"id": "TAO:0001942",
"name": "autopalatine-maxillary joint"
}
},
{
"relation": {
"id": "overlaps",
"name": "overlaps"
},
"target": {
"id": "TAO:0001784",
"name": "autopalatine-vomer joint"
}
},
{
"relation": {
"id": "overlaps",
"name": "overlaps"
},
"target": {
"id": "TAO:0001608",
"name": "autopalatine-lateral ethmoid joint"
}
}],
"children": [
{
"relation": {
"id": "develops_from",
"name": "develops from"
},
"target": {
"id": "TAO:0002158",
"name": "palatine"
}
},
{
"relation": {
"id": "OBO_REL:part_of",
"name": "part_of"
},
"target": {
"id": "TAO:0001578",
"name": "anterior dorsomedial process of autopalatine"
}
}]
} </javascript>
Error
If there is no term with the given ID, the service should return "404 Not Found".
Taxon term info
URI
<BASE URI>/term/{term_id}
This is a specialized term info service which returns data in a format customized for taxa.
Returns
JSON: <javascript> {
"id": "TTO:101020",
"extinct": false,
"rank": {
"id": "TAXRANK:0000005",
"name": "genus"
},
"name": "Ictalurus",
"synonyms": [{
"name": "Villarius"
},
{
"name": "Haustor"
},
{
"name": "Elliops"
},
{
"name": "Istlarius"
},
{
"name": "Synechoglanis"
}],
"parent": {
"id": "TTO:10930",
"extinct": false,
"rank": {
"id": "TAXRANK:0000004",
"name": "family"
},
"name": "Ictaluridae"
},
"children": [{
"id": "TTO:10000452",
"extinct": false,
"rank": {
"id": "TAXRANK:0000006",
"name": "species"
},
"name": "Ictalurus sp. (Vigliotta 2008)"
},
{
"id": "TTO:1004548",
"extinct": false,
"rank": {
"id": "TAXRANK:0000006",
"name": "species"
},
"name": "Ictalurus lupus"
},
{
"id": "TTO:1049346",
"extinct": false,
"rank": {
"id": "TAXRANK:0000006",
"name": "species"
},
"name": "Ictalurus mexicanus"
},
{
"id": "TTO:1004550",
"extinct": false,
"rank": {
"id": "TAXRANK:0000006",
"name": "species"
},
"name": "Ictalurus meridionalis"
},
{
"id": "TTO:1005781",
"extinct": false,
"rank": {
"id": "TAXRANK:0000006",
"name": "species"
},
"name": "Ictalurus balsanus"
},
{
"id": "TTO:1045587",
"extinct": false,
"rank": {
"id": "TAXRANK:0000006",
"name": "species"
},
"name": "Ictalurus australis"
},
{
"id": "TTO:1005768",
"extinct": false,
"rank": {
"id": "TAXRANK:0000006",
"name": "species"
},
"name": "Ictalurus pricei"
},
{
"id": "TTO:1039419",
"extinct": false,
"rank": {
"id": "TAXRANK:0000006",
"name": "species"
},
"name": "Ictalurus ochoterenai"
},
{
"id": "TTO:1004547",
"extinct": false,
"rank": {
"id": "TAXRANK:0000006",
"name": "species"
},
"name": "Ictalurus furcatus"
},
{
"id": "TTO:1054206",
"extinct": false,
"rank": {
"id": "TAXRANK:0000006",
"name": "species"
},
"name": "Ictalurus punctatus"
},
{
"id": "TTO:10000228",
"extinct": false,
"rank": {
"id": "TAXRANK:0000006",
"name": "species"
},
"name": "Ictalurus sp. (Mo 1991)"
},
{
"id": "TTO:10000044",
"extinct": false,
"rank": {
"id": "TAXRANK:0000006",
"name": "species"
},
"name": "Ictalurus sp. (Fink and Fink 1981)"
},
{
"id": "TTO:1046960",
"extinct": false,
"rank": {
"id": "TAXRANK:0000006",
"name": "species"
},
"name": "Ictalurus dugesii"
}]
} </javascript>
Error
If there is no term with the given ID, the service should return "404 Not Found".
Autocomplete
URI
<BASE URI>/term/search?text=[input]&name=[true|false]&syn=[true|false]&ontology=[ont1,ont2,...]&type=[type1,type2,...]&limit=[count]
All URI parameters are optional except for text. Default values are name=true, syn=false. The ontology parameter should be a comma-separated list of ontology prefixes to search within (any of tao, go, pato, tto, zfin, pspub). The type parameter should be any of: entity, quality, taxon, gene, pub. If no ontology or type is given, the default is to search all ontologies. The limit parameter limits the number of results to the given integer count.
Returns
JSON: <javascript> {
"matches": [{
"match_text": "Brachydanio rerio",
"id": "TTO:1001979",
"match_type": "syn",
"name": "Danio rerio"
},
{
"match_text": "Cyprinus rerio",
"id": "TTO:1001979",
"match_type": "syn",
"name": "Danio rerio"
},
{
"match_text": "Danio rerio",
"id": "TTO:1001979",
"match_type": "name",
"name": "Danio rerio"
}],
"search_term": "rerio"
} </javascript>
Error
If there are no terms matching the given input, a document should still be returned, containing an empty results list.
Gene annotations
This specification is in progress and the service is not yet available.
URI
<BASE URI>/annotation/gene?query=[url-encoded-json]&sortby=[gene|entity|quality|relatedentity]&limit=[count]&index=[start_index]&desc=[true|false]
All URI parameters are optional. If no JSON-formatted query specification is provided, all gene annotations will be returned. The limit parameter limits the number of results to the given integer count. This must be a positive integer. The index parameter can be used for pagination under a given sorting and limit regime. It should be greater than or equal to zero (the default). desc can be used to return the results in descending order (it is false by default). If a value is not provided for sortby, the sort order, limit, and start index are not very useful.
Phenotype query specification
The value of query parameter should be a phenotype query represented as JSON, following this structure:
<javascript> {} </javascript>
Returns
JSON: <javascript> {} </javascript>
Old services (v1)
These are in general deprecated.
Timestamp
URI
<BASE URI>/timestamp
Returns
JSON: <javascript> { "timestamp":"2010-01-09" }
</javascript>
Term info
URI
<BASE URI>/term/{term_id}
Returns
JSON: <javascript> {
"id" : "TAO:0001700",
"name" : "caudal-fin stay",
"definition" : "Bone that is located anterior to the caudal procurrent rays. Caudal fin stays are unpaired bone.",
"comment" : "Some comment text that may be in there."
"parents" :
[
{
"relation" : {
"id" : "OBO_REL:is_a",
"name" : "is_a"
},
"target" : {
"id" : "TAO:0001514",
"name" : "bone"
}
},
{
"relation" : {
"id" : "OBO_REL:part_of",
"name" : "part_of"
},
"target" : {
"id" : "TAO:0000862",
"name" : "caudal fin skeleton"
}
}
],
"children" : [] // if there are children, this content should be in the same format as the parents list
} // how should xrefs, etc. be represented, property_value definitions? </javascript>
OWL-RDF:
Todo...
Error
If there is no term with the given ID, the service should return "404 Not Found".
Handling of anonymous post-compositions
Autocomplete
URI
<BASE URI>/term/search?text=[input]&name=[true|false]&syn=[true|false]&def=[true|false]&ontology=[ont1,ont2,...]&limit=[count]
All URI parameters are optional except for text. Default values are name=true, syn=false, def=false. The "ontology" parameter should be a comma-separated list of ontology prefixes to search within. If not given, the default is to search all ontologies. Specifying "ZFIN" for the ontology should be a search for gene nodes, by gene name. The "limit" parameter limits the number of results to the given integer.
Returns
JSON: <javascript> {
"matches" : [
{ // overall format
"id" : "TAO:0001514",
"name" : "bone",
"match_type" : "name" | "syn" | "def",
"match_text" : "this is the term name, synonym name, or definition that matched"
},
{ // a name example
"id" : "TAO:0001514",
"name" : "bone",
"match_type" : "name",
"match_text" : "bone"
},
{ // a synonym example
"id" : "TAO:0001795",
"name" : "ceratohyal foramen",
"match_type" : "syn",
"match_text" : "bericiform foramen"
},
{ // a definition example
"id" : "TAO:0000488",
"name" : "ceratobranchial bone",
"match_type" : "def",
"match_text" : "Ceratobranchials are bilaterally paired cartilage bones that form part of the ventral branchial arches. They articulate medially
with the hypobranchials and laterally and dorsally with the epibranchials. Ceratobranchials 1-5 ossify in the ceratobranchial cartilages."
}
],
"search_term" : "bone",
"total" : 1859
} </javascript>
Error
If there are no terms matching the given input, a document should still be returned, containing an empty results list.
Annotations summary
URI
<BASE URI>/phenotypes/summary?subject={subject_id}&entity={entity_id}&quality={quality_id}&pub={publication_id]&examples={examples_count}
This service returns a summary of the phenotype annotations involving the given terms. The annotations are grouped by "character", which a unique combination of an entity and the "character quality" to which the quality in the annotation corresponds.
All parameters are optional. If no parameters are specified, the service should return a summary of all the phenotype annotations in the database. Otherwise, any term ID given for the various parameters restricts the annotations to only those concerning those terms (where "concerning" is defined for each type of parameter).
- subject - an ID for a taxon or gene - the summarized characters are only those which this term exhibits
- entity - an ID for an anatomical term - the summarized characters are only those whose phenotype inheres_in this entity (note - maybe we should add another parameter to include phenotypes which inhere_in_part_of the entity)
- quality - an ID for a quality term - the summarized characters are only those whose phenotype is_a type of this term
- pub - an ID for a publication - the summarized characters are only those contributed by the given publication
- examples - the number of example terms to include in the output - default is zero
For each character, find all taxa and genes which exhibit phenotypes corresponding to that character. If "subject" is a taxon, limit the included taxa to those within the given subject taxon. If "pub" is specified, limit the included taxa to those within the given publication.
Returns
JSON: <javascript> {
"characters" : [
{
"entity" : { "id" : "TAO:34242", "name" : "basihyal bone" },
"character_quality" : { "id" : "PATO:34242", "name" : "texture" },
"qualities" : {
"count" : 14,
"examples" : [
{ "id" : "PATO:34242", "name" : "some quality" },
{ "id" : "PATO:34242", "name" : "some quality" }
]
},
"taxa" : {
"count" : 2,
"examples" : [
{ "id" : "TTO:34242", "name" : "some taxon" },
{ "id" : "TTO:34246", "name" : "some taxon" }
]
},
"genes" : {
"count" : 2,
"examples" : [
{ "id" : "ZDB:34242", "name" : "some gene" },
{ "id" : "ZDB:34246", "name" : "some gene" }
]
}
},
{
"entity" : { "id" : "TAO:34242", "name" : "dorsal fin ray" },
"character_quality" : { "id" : "PATO:34242", "name" : "shape" },
"qualities" : {
"count" : 9,
"examples" : [
{ "id" : "PATO:34242", "name" : "some quality" },
{ "id" : "PATO:34242", "name" : "some quality" }
]
},
"taxa" : {
"count" : 5,
"examples" : [
{ "id" : "TTO:34242", "name" : "some taxon" },
{ "id" : "TTO:34246", "name" : "some taxon" }
]
},
"genes" : {
"count" : 7,
"examples" : [
{ "id" : "ZDB:34242", "name" : "some gene" },
{ "id" : "ZDB:34246", "name" : "some gene" }
]
}
}
]
} </javascript>
Annotations results
URI
<BASE URI>/phenotypes?subject={subject_id}&entity={entity_id}&quality={quality_id}&pub={publication_id]&type=[evo|devo]&group=[root|{taxon_id}]
This service returns the phenotype annotations involving the given terms.
All parameters are optional. If no parameters are specified, the service should return all the phenotype annotations in the database. Otherwise, any term ID given for the various parameters restricts the annotations to only those concerning those terms (where "concerning" is defined for each type of parameter).
- subject - an ID for a taxon or gene - the returned annotations are only those which this term exhibits
- entity - an ID for an anatomical term - the returned annotations are only those whose phenotype inheres_in this entity (note - maybe we should add another parameter to include phenotypes which inhere_in_part_of the entity)
- quality - an ID for a quality term - the returned annotations are only those whose phenotype is_a type of this term
- pub - an ID for a publication - the returned annotations are only those contributed by the given publication
- type - either "evo" or "devo" - return either evolutionary data (evo) or model organism data (devo) or both if not specified
- group - if "root", return, as the subject, only the most recent common ancestor taxon for all taxa found in the query, along with the set of phenotypes found in the results. If a taxon id, return the results grouped into immediate children of that taxon (only those that have results). Only include the annotation ID if that phenotype-to-taxon link was actually asserted.
Returns
JSON: <javascript> {
"subjects" : [
{ "id" : "TTO:34242",
"name" : "some taxon",
"leaf" : false, //whether it is useful to query for more specific sub-taxa
"phenotypes" : [
{
"id" : "internal annotation ID",
"entity" : { "id" : "TAO:34242", "name" : "some entity" },
"quality" : { "id" : "PATO:34242", "name" : "some quality" },
"count" : 22
},
{
"id" : "internal annotation ID",
"entity" : { "id" : "TAO:34242", "name" : "some entity" },
"quality" : { "id" : "PATO:34242", "name" : "some quality" },
"count" : ""
},
{
"id" : "internal annotation ID",
"entity" : { "id" : "TAO:34242", "name" : "some entity" },
"quality" : { "id" : "PATO:34242", "name" : "some quality" },
"count" : ""
}
]
},
{ "id" : "TTO:34243",
"name" : "some taxon",
"phenotypes" : [
{
"id" : "internal annotation ID",
"entity" : { "id" : "TAO:34242", "name" : "some entity" },
"quality" : { "id" : "PATO:34242", "name" : "some quality" },
"count" : ""
},
{
"id" : "internal annotation ID",
"entity" : { "id" : "TAO:34242", "name" : "some entity" },
"quality" : { "id" : "PATO:34242", "name" : "some quality" },
"count" : ""
},
{
"id" : "internal annotation ID",
"entity" : { "id" : "TAO:34242", "name" : "some entity" },
"quality" : { "id" : "PATO:34242", "name" : "some quality" },
"count" : ""
}
]
},
{ "id" : "TTO:34244",
"name" : "some taxon",
"phenotypes" : [
{
"id" : "internal annotation ID",
"entity" : { "id" : "TAO:34242", "name" : "some entity" },
"quality" : { "id" : "PATO:34242", "name" : "some quality" },
"count" : ""
},
{
"id" : "internal annotation ID",
"entity" : { "id" : "TAO:34242", "name" : "some entity" },
"quality" : { "id" : "PATO:34242", "name" : "some quality" },
"count" : ""
},
{
"id" : "internal annotation ID",
"entity" : { "id" : "TAO:34242", "name" : "some entity" },
"quality" : { "id" : "PATO:34242", "name" : "some quality" },
"count" : ""
}
]
}
]
} </javascript>
Homology info
Return any homology statements which the given term participates in. Regardless of the direction of the homologous link in the database, the queried term should be returned as the "subject" in the returned data - the homologous term would be the "target".
URI
<BASE URI>/term/{term_id}/homology
Returns
JSON: <javascript> {"homologies" : [
{
"subject" : {
"entity" : {"id" : "TAO:xxxx", "name" : "some anatomical thing"},
"taxon" : {"id" : "TTO:xxxx", "name" : "some taxon"}
},
"target" : {
"entity" : {"id" : "TAO:xxxx", "name" : "some anatomical thing"},
"taxon" : {"id" : "TTO:xxxx", "name" : "some taxon"}
},
"source" : {
"publication" : "citation text", "evidence" : {"id" : "ECO:xxxx", "name" : "some evidence code"} }
},
{
"subject" : {
"entity" : {"id" : "TAO:xxxx", "name" : "some anatomical thing"},
"taxon" : {"id" : "TTO:xxxx", "name" : "some taxon"}
},
"target" : {
"entity" : {"id" : "TAO:xxxx", "name" : "some anatomical thing"},
"taxon" : {"id" : "TTO:xxxx", "name" : "some taxon"}
},
"source" : {
"publication" : "citation text", "evidence" : {"id" : "ECO:xxxx", "name" : "some evidence code"} }
}
] } </javascript>
Annotation source information
URI
<BASE URI>/phenotypes/source/{annotation_id}
Returns
JSON: <javascript> { "phenotype" : {
"subject" : { "id" : "TTO:34242", "name" : "some taxon" },
"entity" : { "id" : "TAO:34242", "name" : "some entity" },
"quality" : { "id" : "PATO:34242", "name" : "some quality" }
},
"sources" : [
{
"publication" : "citation text",
"character_text" : "blah",
"character_comment" : "blah",
"state_text" : "blah",
"curated_by" : "blah"
}
] } </javascript>
