Difference between revisions of "Data Services"

From phenoscape
Line 99: Line 99:
  
 
If there are no terms matching the given input, a document should still be returned, containing an empty results list.
 
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=XXXX&entity=XXXX&quality=XXXX&pub=XXXX&examples=####
 +
 +
''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>
  
 
==Anatomy search summary==
 
==Anatomy search summary==

Revision as of 14:54, 1 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.

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=XXXX&entity=XXXX&quality=XXXX&pub=XXXX&examples=####

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>

Anatomy search summary

URI 

<BASE URI>/phenotypes/summary/anatomy/{term_id}

term_id is an anatomy search term. This service returns a summary of all the phenotype annotations involving that anatomy term (or its descendants, via reasoning). The summary is grouped by quality attribute term - all annotations with qualities descending from the same closest attribute should be grouped into the same count.

Returns

JSON: <javascript> { 

   "term" : { "id" : "TAO:xxxxx", "name" : "some anatomical part"},
   "qualities" : [
       {
           "id" : "PATO:000xxxxx",
           "name" : "shape",
           "taxon_annotations" : {
               "annotation_count": 5,
               "taxon_count" : 3
           },
           "genotype_annotations" : {
               "annotation_count" : 3,
               "genotype_count" : 2
           }
       },
       {
           // another quality attribute
       } // etc.
   ]

} </javascript>

Anatomy taxon annotations results

URI 

<BASE URI>/phenotypes/anatomy/{anatomy_term_id}/taxa/{quality_term_id}?attribute=[true|false]

anatomy_term_id is an anatomy search term. This service returns all of the phenotype annotations involving that anatomy term (or its descendants, via reasoning) and the given quality term (or its descendants, via reasoning). In the result, the values of the outer "entity" and "quality" keys are the search inputs.

The "attribute" query parameter is optional - if "true", the service should first find the corresponding attribute for the given quality, and use that in the search instead of the given quality. The default should be "false".

Returns

JSON: <javascript> { 

   "entity" : { "id" : "TAO:34242", "name" : "some anatomical part" },
   "quality" : { "id" : "PATO:1234", "name" : "some attribute quality"},
   "annotations" : [
   {
       "taxon" : { "id" : "TTO:34242", "name" : "some species" },
       "entity" : { "id" : "TAO:34242", "name" : "some anatomical part" },
       "quality" : { "id" : "PATO:34242", "name" : "some quality" }
   },
   {
       "taxon" : { "id" : "TTO:34242", "name" : "some species" },
       "entity" : { "id" : "TAO:34242", "name" : "some anatomical part" },
       "quality" : { "id" : "PATO:34242", "name" : "some quality" }
   },
   {
       "taxon" : { "id" : "TTO:34242", "name" : "some species" },
       "entity" : { "id" : "TAO:34242", "name" : "some anatomical part" },
       "quality" : { "id" : "PATO:34242", "name" : "some quality" }
   }
   ]

} </javascript>

Anatomy genotypes annotations results

URI 

<BASE URI>/phenotypes/anatomy/{anatomy_term_id}/genes/{quality_term_id}

anatomy_term_id is an anatomy search term. This service returns all of the phenotype annotations for genotypes involving that anatomy term (or its descendants, via reasoning) and the given quality term (or its descendants, via reasoning). In the result, the values of the outer "entity" and "quality" keys are the search inputs.

The "attribute" query parameter is optional - if "true", the service should first find the corresponding attribute for the given quality, and use that in the search instead of the given quality. The default should be "false".

Returns

JSON: <javascript> { 

   "entity" : { "id" : "TAO:34242", "name" : "some anatomical part" },
   "quality" : { "id" : "PATO:1234", "name" : "some attribute quality"},
   "annotations" : [
         {
           "genotype" : { "id" : "ZFIN:34242", "name" : "some genotype" },
           "entity" : { "id" : "TAO:34242", "name" : "some anatomical part" },
           "quality" : { "id" : "PATO:34242", "name" : "some quality" }
       },
       {
           "genotype" : { "id" : "ZFIN:34242", "name" : "some genotype" },
           "entity" : { "id" : "TAO:34242", "name" : "some anatomical part" },
           "quality" : { "id" : "PATO:34242", "name" : "some quality" }
       },
       {
           "genotype" : { "id" : "ZFIN:34242", "name" : "some genotype" },
           "entity" : { "id" : "TAO:34242", "name" : "some anatomical part" },
           "quality" : { "id" : "PATO:34242", "name" : "some quality" }
       }
   ]

} </javascript>

Gene search summary

URI 

<BASE URI>/phenotypes/summary/gene/{term_id}

term_id is an gene symbol search id. This service returns all the phenotype annotations involving that gene. Identical annotations from different genotypes are lumped together. Each annotation has a list of all the genotypes which exhibited it. Each annotation includes the term from TAO matching the ZFA term in "teleost_entity".

Returns

JSON: <javascript> { 

   "gene" : { "id" : "ZFIN:xxxxx", "name" : "some gene name"},
   "annotations" : [
       {
           "entity" : { "id" : "ZFA:34242", "name" : "some anatomical part" },
           "quality" : { "id" : "PATO:34242", "name" : "some quality" },
           "teleost_entity" : { "id" : "TAO:34242", "name" : "some anatomical part" }
           "genotypes" : [
               { "id" : "ZFIN:xxxxx", "name" : "some genotype" },
               { "id" : "ZFIN:xxxxx", "name" : "some genotype" },
               { "id" : "ZFIN:xxxxx", "name" : "some genotype" }
           ]
       },
       {
           "entity" : { "id" : "ZFA:34242", "name" : "some anatomical part" },
           "quality" : { "id" : "PATO:34242", "name" : "some quality" },
           "teleost_entity" : { "id" : "TAO:34242", "name" : "some anatomical part" }
           "genotypes" : [
               { "id" : "ZFIN:xxxxx", "name" : "some genotype" },
               { "id" : "ZFIN:xxxxx", "name" : "some genotype" },
               { "id" : "ZFIN:xxxxx", "name" : "some genotype" }
           ]
       }
   ]

} </javascript>

Retrieved from "https://wiki.phenoscape.org/wg/phenoscape/index.php?title=Data_Services&oldid=5755"