Difference between revisions of "Data Services"
(→Annotations results) |
|||
| Line 178: | Line 178: | ||
'''URI''' | '''URI''' | ||
| − | <BASE URI>/phenotypes?subject={subject_id}&entity={entity_id}&quality={quality_id}&pub={publication_id] | + | <BASE URI>/phenotypes?subject={subject_id}&entity={entity_id}&quality={quality_id}&pub={publication_id]&type=[evo|devo] |
This service returns the phenotype annotations involving the given terms. | This service returns the phenotype annotations involving the given terms. | ||
| Line 187: | Line 187: | ||
* '''quality''' - an ID for a quality term - the returned annotations are only those whose phenotype ''is_a'' type of this term | * '''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 | * '''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 | ||
''Returns'' | ''Returns'' | ||
Revision as of 20:22, 27 April 2009
This section details of the data services that query the OBD Phenoscape 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.
Contents
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.",
"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 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
- examples - the number of example terms to include in the output - default is zero
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]
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
Returns
JSON: <javascript> {
"phenotypes" : [
{
"subject" : { "id" : "TTO:34242", "name" : "some taxon" },
"entity" : { "id" : "TAO:34242", "name" : "some entity" },
"quality" : { "id" : "PATO:34242", "name" : "some quality" }
},
{
"subject" : { "id" : "TTO:34242", "name" : "some taxon" },
"entity" : { "id" : "TAO:34242", "name" : "some entity" },
"quality" : { "id" : "PATO:34242", "name" : "some quality" }
},
{
"subject" : { "id" : "TTO:34242", "name" : "some taxon" },
"entity" : { "id" : "TAO:34242", "name" : "some entity" },
"quality" : { "id" : "PATO:34242", "name" : "some quality" }
}
]
} </javascript>
