Difference between revisions of "Data Services"

From phenoscape
(Bulk term name mapper)
(Gene annotations)
Line 367: Line 367:
 
'''URI'''
 
'''URI'''
  
  <BASE URI>/annotation/gene?query=[url-encoded-json]&sortby=[gene|entity|quality|relatedentity]&limit=[count]&index=[start_index]&desc=[true|false]
+
  <BASE URI>/annotation/gene?query=[url-encoded-json]&sortby=[gene|entity|quality|relatedentity]&limit=[count]&index=[start_index]&desc=[true|false]&postcompositions=[none|structure|simple|semantic]
  
 
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.

Revision as of 14:46, 13 August 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.

Phenoscape Knowledgebase data 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/taxon/{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".

Bulk term name mapper

URI

<BASE URI>/term/names

This service accepts a list of term IDs and returns a JSON mapping of IDs to names. Rank and extinct status are included in the output for taxon terms. The render_postcompositions key is optional, and can take the values "none" (the default), "structure", "semantic_label", or "simple_label".

Accepts via POST

JSON: <javascript> { "ids":["TAO:0000620", "TTO:1380", "TTO:11021", "ZFIN:ZDB-GENE-061116-1"], "render_postcompositions": "none" } </javascript>

Returns

JSON: <javascript> {"terms":[ {"id":"TAO:0000620","name":"autopalatine"}, {"id":"TTO:1380","extinct":false,"rank":{"id":"TAXRANK:0000003","name":"order"},"name":"Siluriformes"}, {"id":"TTO:11021","extinct":false,"rank":{"id":"TAXRANK:0000004","name":"family"},"name":"Erethistidae"}, {"id":"ZFIN:ZDB-GENE-061116-1","name":"foxe1"}]} </javascript>

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

URI

<BASE URI>/annotation/gene?query=[url-encoded-json]&sortby=[gene|entity|quality|relatedentity]&limit=[count]&index=[start_index]&desc=[true|false]&postcompositions=[none|structure|simple|semantic]

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 the query parameter should be an annotation query represented as JSON, following this structure (in practice it should be collapsed as far as possible to shorten the URL):

<javascript> {

   "gene": [
   {
       "id": "ZFIN:XXXX"
   },
   {
       "id": "ZFIN:YYYY"
   }
   ],
   "phenotype": [
   {
       "entity": {
           "id": "TAO:XXXX",
           "including_parts": false
       },
       "quality": {
           "id": "PATO:XXXX"
       },
       "related_entity": {
           "id": "TAO:YYYYY"
       }
   }
   ],
   "include_inferred": false

} </javascript> It should be URL-encoded to include in the request.

Returns

JSON: <javascript> {

   "total": 5478,
   "annotations": [
   {
       "gene": {
           "id": "TAO0001514",
           "name": "brph1"
       },
       "entity": {
           "id": "TAO0001516",
           "name": "basihyal bone"
       },
       "quality": {
           "id": "TAO0001517",
           "name": "fused with"
       },
       "related_entity": {
           "id": "TAO0001518",
           "name": "posterior ceratohyal"
       }
   },
   {
       "gene": {
           "id": "TAO0001522",
           "name": "brph2"
       },
       "entity": {
           "id": "TAO0001524",
           "name": "fossa of basihyal bone"
       },
       "quality": {
           "id": "TAO0001525",
           "name": "decreased width"
       },
       "related_entity": null
   }
   ]

} </javascript>

Gene annotation sources

URI

<BASE URI>/annotation/gene/source?query=[url-encoded-json]

A JSON-formatted query specification must be provided. It must contain entries for one annotation, including gene, entity, quality, and optional related entity. While the gene and phenotype entries are lists, this is just for consistency with the query format used in other services - each list should contain only one entry.

Phenotype query specification

The value of the query parameter should be an annotation query represented as JSON, following this structure (in practice it should be collapsed as far as possible to shorten the URL):

<javascript> {

   "gene": [
   {
       "id": "ZFIN:XXXX"
   }
   ],
   "phenotype": [
   {
       "entity": {
           "id": "TAO:XXXX"
       },
       "quality": {
           "id": "PATO:XXXX"
       },
       "related_entity": {
           "id": "TAO:YYYYY"
       }
   }
   ]

} </javascript> It should be URL-encoded to include in the request.

Returns

JSON: <javascript> {"annotations":[ {"gene":{"id":"ZFIN:ZDB-GENE-040426-731","name":"brpf1"}, "entity":{"id":"TAO:0000316","name":"basihyal bone"}, "quality":{"id":"PATO:0000587","name":"decreased size"}, "genotype":{"id":"ZFIN:ZDB-GENO-080925-12","name":"brpf1b943/b943<\/sup>","type":{"id":"SO:0001027","name":"genotype"}}, "publication":{"id":"ZFIN:ZDB-PUB-080515-4","name":"Laue, K., Daujat, S., Crump, J.G., Plaster, N., Roehl, H.H.; Tübingen 2000 Screen Consortium, Kimmel, C.B., Schneider, R., and Hammerschmidt, M.. 2008. The multidomain protein Brpf1 binds histones and is required for Hox gene expression and segmental identity. Development 135(11):1935-1946."}}, {"gene":{"id":"ZFIN:ZDB-GENE-040426-731","name":"brpf1"}, "entity":{"id":"TAO:0000316","name":"basihyal bone"}, "quality":{"id":"PATO:0000587","name":"decreased size"}, "genotype":{"id":"ZFIN:ZDB-GENO-080925-13","name":"brpf1t20002/t20002<\/sup>","type":{"id":"SO:0001027","name":"genotype"}}, "publication":{"id":"ZFIN:ZDB-PUB-080515-4","name":"Laue, K., Daujat, S., Crump, J.G., Plaster, N., Roehl, H.H.; Tübingen 2000 Screen Consortium, Kimmel, C.B., Schneider, R., and Hammerschmidt, M.. 2008. The multidomain protein Brpf1 binds histones and is required for Hox gene expression and segmental identity. Development 135(11):1935-1946."}} ]} </javascript>

Genes

URI

<BASE URI>/gene/annotated?query=[url-encoded-json]&sortby=[gene|fullname]&limit=[count]&index=[start_index]&desc=[true|false]

All URI parameters are optional. If no JSON-formatted query specification is provided, all annotated genes 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 the query parameter should be an annotation query represented as JSON, following this structure (in practice it should be collapsed as far as possible to shorten the URL):

<javascript> {

   "phenotype": [
   {
       "entity": {
           "id": "TAO:XXXX",
           "including_parts": false
       },
       "quality": {
           "id": "PATO:XXXX"
       },
       "related_entity": {
           "id": "TAO:YYYYY"
       }
   }
   ],
   "match_all_phenotypes": false

} </javascript> It should be URL-encoded to include in the request.

Returns

JSON <javascript> {"total":1690, "genes":[ {"id":"ZFIN:ZDB-GENE-040426-1995","name":"abce1","fullname":"ATP-binding cassette, sub-family E (OABP), member 1"}, {"id":"ZFIN:ZDB-GENE-070117-775","name":"abf","fullname":"about face"}, {"id":"ZFIN:ZDB-GENE-040909-1","name":"abhd11","fullname":"abhydrolase domain containing 11"}, {"id":"ZFIN:ZDB-GENE-030131-55","name":"acta1b","fullname":"actin, alpha 1b, skeletal muscle"}, {"id":"ZFIN:ZDB-GENE-020419-36","name":"actl6a","fullname":"actin-like 6A"}, {"id":"ZFIN:ZDB-GENE-990415-9","name":"acvr1l","fullname":"activin A receptor, type I like"}, {"id":"ZFIN:ZDB-GENE-021003-1","name":"acvrl1","fullname":"activin A receptor type II-like 1"}]} </javascript>

Taxon annotations

URI

<BASE URI>/annotation/taxon/distinct?query=[url-encoded-json]&sortby=[taxon|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 taxon 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 the query parameter should be an annotation query represented as JSON, following this structure (in practice it should be collapsed as far as possible to shorten the URL):

<javascript> {

   "taxon": [
   {
       "id": "TTO:XXXX"
   },
   {
       "id": "TTO:YYYY"
   }
   ],
   "phenotype": [
   {
       "entity": {
           "id": "TAO:XXXX",
           "including_parts": false
       },
       "quality": {
           "id": "PATO:XXXX"
       },
       "related_entity": {
           "id": "TAO:YYYYY"
       }
   }
   ],
   "publication": [
    {
      "id": "PSPUB:1243"
    }
   ],
   "include_inferred": false

} </javascript> It should be URL-encoded to include in the request.

Returns

JSON <javascript> {

   "total": 5478,
   "annotations": [
   {
       "taxon": {
           "id": "TAO0001514",
           "name": "Ictalurus punctatus",
           "rank": {
                "id": "TAXRANK:00000",
                "name": "species"
           },
           "extinct": false
       },
       "entity": {
           "id": "TAO0001516",
           "name": "basihyal bone"
       },
       "quality": {
           "id": "TAO0001517",
           "name": "fused with"
       },
       "related_entity": {
           "id": "TAO0001518",
           "name": "posterior ceratohyal"
       }
   },
   {
       "taxon": {
           "id": "TAO0001522",
           "name": "Danio rerio",
           "rank": {
                "id": "TAXRANK:00000",
                "name": "species"
           },
           "extinct": false
       },
       "entity": {
           "id": "TAO0001524",
           "name": "fossa of basihyal bone"
       },
       "quality": {
           "id": "TAO0001525",
           "name": "decreased width"
       },
       "related_entity": null
   }
   ]

} </javascript>

Taxon annotation sources

URI

<BASE URI>/annotation/taxon/source?query=[url-encoded-json]

A JSON-formatted query specification must be provided. It must contain entries for one annotation, including taxon, entity, quality, and optional related entity. While the taxon and phenotype entries are lists, this is just for consistency with the query format used in other services - each list should contain only one entry. The "publication" list is optional, but may contain multiple publications within which to constrain the results.

Phenotype query specification

The value of the query parameter should be an annotation query represented as JSON, following this structure (in practice it should be collapsed as far as possible to shorten the URL):

<javascript> {

   "taxon": [
   {
       "id": "TTO:XXXX"
   }
   ],
   "phenotype": [
   {
       "entity": {
           "id": "TAO:XXXX"
       },
       "quality": {
           "id": "PATO:XXXX"
       },
       "related_entity": {
           "id": "TAO:YYYYY"
       }
   }
   ],
   "publication": [
    {
      "id": "PSPUB:1243"
    }
   ]

} </javascript> It should be URL-encoded to include in the request.

Returns

JSON: <javascript> {"annotations":[{"otu":"Silurus glanis", "entity":{"id":"TAO:0000316","name":"basihyal bone"}, "state":{"text":"basihyal absent"}, "quality":{"id":"PATO:0000462","name":"absent"}, "taxon":{"id":"TTO:1005466","extinct":false,"rank":{"id":"TAXRANK:0000006","name":"species"},"name":"Silurus glanis"}, "character":{"text":"Basihyal","character_number":"240"}, "publication":{"id":"PSPUB:0000022","name":"de Pinna 1993"}}]} </javascript>

Taxa

URI

<BASE URI>/taxon/annotated?query=[url-encoded-json]&sortby=[taxon|family|order]&limit=[count]&index=[start_index]&desc=[true|false]

All URI parameters are optional. If no JSON-formatted query specification is provided, all annotated taxa 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 the query parameter should be an annotation query represented as JSON, following this structure (in practice it should be collapsed as far as possible to shorten the URL):

<javascript> {

   "taxon": [
   {
       "id": "TTO:XXXX"
   },
   {
       "id": "TTO:YYYY"
   }
   ],
   "phenotype": [
   {
       "entity": {
           "id": "TAO:XXXX",
           "including_parts": false
       },
       "quality": {
           "id": "PATO:XXXX"
       },
       "related_entity": {
           "id": "TAO:YYYYY"
       }
   }
   ],
   "publication": [
    {
      "id": "PSPUB:1243"
    }
   ],
   "match_all_phenotypes": false,
   "match_all_publications": false,
   "include_inferred": false

} </javascript> It should be URL-encoded to include in the request.

Returns

JSON <javascript> {"total":2312, "taxa":[ {"id":"TTO:1068687","extinct":false, "rank":{"id":"TAXRANK:0000006","name":"species"}, "order":{"id":"TTO:1360","extinct":false,"name":"Cypriniformes"}, "family":{"id":"TTO:10760","extinct":false,"name":"Cyprinidae"}, "name":"Abbottina binhi"}, {"id":"TTO:1004289","extinct":false, "rank":{"id":"TAXRANK:0000006","name":"species"}, "order":{"id":"TTO:1370","extinct":false,"name":"Characiformes"}, "family":{"id":"TTO:10856","extinct":false,"name":"Anostomidae"}, "name":"Abramites hypselonotus"} ] } </javascript>

Publications

URI

<BASE URI>/publication/annotated?query=[url-encoded-json]&sortby=[publication]&limit=[count]&index=[start_index]&desc=[true|false]

All URI parameters are optional. If no JSON-formatted query specification is provided, all annotated publications 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 the query parameter should be an annotation query represented as JSON, following this structure (in practice it should be collapsed as far as possible to shorten the URL):

<javascript> {

   "taxon": [
   {
       "id": "TTO:XXXX"
   },
   {
       "id": "TTO:YYYY"
   }
   ],
   "phenotype": [
   {
       "entity": {
           "id": "TAO:XXXX",
           "including_parts": false
       },
       "quality": {
           "id": "PATO:XXXX"
       },
       "related_entity": {
           "id": "TAO:YYYYY"
       }
   }
   ],
   "match_all_phenotypes": false,
   "match_all_taxa": false

} </javascript> It should be URL-encoded to include in the request.

Returns

JSON <javascript> {"total":19, "publications":[ {"id":"PSPUB:0000002","name":"Armbruster 2004"}, {"id":"PSPUB:0000006","name":"Bockmann 1998"}, {"id":"PSPUB:0000009","name":"Bornbusch 1995"}, {"id":"PSPUB:0000011","name":"Britto 2003"}, {"id":"PSPUB:0000018","name":"Chen 1994"}]} </javascript>