CAT Services Description
This is the transcript of the initial definition for a core set of CAT/CAF services. They have been created at Kick-Off meeting at Caltch in June 2012
Checks
Annotation Checks
REST method for running Annotation Checks
$BASE_URL/.../checkAnnotation
POST: js representing single annotation or list of annotations PARAMS: rule ID(s) - default: all fail early? BOOL - default: false[open] RETURNS: { status: CODE, valid : BOOL, has_warnings: BOOL, MESSAGE*, SUGGESTED_ANNOT* } MESSAGE = { rule_id: ID, annotation_id : ID (optional if single annotation passed) description : TEXT, contextual_annotations: annot-ID*, taxon_ids: ID* (only for taxon checks) ontology_ids: ID* }, SUGGESTED_ANNOT = { rule_id : ID, is_enforced : BOOL, annotations: js for annotations TBD }
Valid GO IDs
REST method for filtering valid GO IDs (currently used in PAINT)
Filter by Taxon
$BASE_URL/.../filterByTaxon
PARAMs: list of taxon IDs, list of ontology IDs [or slim] RETURNS: list of valid taxon / ontology ID pairs
Ontology IDs for Taxon
$BASE_URL/../getAllValidOntologyIDsForTaxon
PARAMs: list of taxon IDs, ontology IDs [required. value of ‘ontology’ tag in obo file. examples: ‘go’, ‘cl’] RETURNS: list of valid ontology IDs
REST method specifically for checking annotation extension syntax and semantics
$BASE_URL/.../checkAnnotationExtension
PARAMS: genus_id : string (i.e. GO ID in c5 of a GAF) annotation_extension: formatted string (i.e. c16) RETURNS: problems: list of assoc arrays relation [optional] class [optional] type [e.g. “domain”, “syntax_error”] suggestions: list of more specific classes that can be used in c5
Annotation js format
Direct JSON representation of GPAD GPAD
The JSON fields have the same name as the XML attributesThe XML form of an annotation currently used by p2go:
<ann AC="Q4VCS5" ANN_EXT="" CC="1" COMMENTS="0" COPY_FROM="" EVIDENCE="IDA" EXTERNAL_DATE="20051109" EXTRA_TAXID="" GOID="GO:0030027" ID="16668887" QUALIFIER="" REF_COMMENTS="0" REF_DBC="PUBMED" REF_ID="11257124" SOURCE="SWIS" WITH_STR="" category="external" />
Ontology Services
Searching / Autocompletion
Autocomplete
autocomplete
params: term [string, required] ontology [ontology ID, e.g. ‘go’, ‘cl’ - default to all] modes TBD - e.g. prefixes, only max [optional, default 10] subsets [predefined, e.g GO slims] taxon [e.g. NCBITaxon:nnn - used to filter results] returns js assoc list: number_of_matches: int matches: ordered list of terms+scores (minimal representation) id (e.g. GO:nnnn, CL:nnnn) label type of match [e.g. matches exact synonym] matched label [e.g. match may be on synonym] ontology score?
Ontology Class Info
getOntologyClassInfo
params: id (e.g GO:nnnnn) details: one of [“minimal”, “complete”, .. extensible] ontology_model: one of [“tag-value”, “owl-js”] return single js class structure exact structure depends on ontology_model
Class Releationships
getClassDirectRelationships
params: id relationship* [if specified, filters on this list] returns: list of relationship tuples subject: string relation: string target: string
may be extended in future (e.g. owl quantifiers)
Ontology Classes
queryOntologyClasses
params: TBD
advanced queries
passthrough to capabilities of underlying implementation (e.g. SPARQL, SOLR faceted queries)
Representing ontologies in js
two models: simple tag-value (lossy) and owl-js
tag-value model class: associative array with keys: id : string label : string def : string def_xrefs: list of strings synonyms : list of strings is_obsolete : boolean consider_list : list of strings replaced_by: list of strings parents: list of IDs [all relationship types] parent_relationships: list of relation : string [e.g. part_of] filler : string [‘target’ of relationship, e.g. GO:nnnnn] owl-js model : TBD
Gene Product / Entity Queries
mostly similar to ontology queries, TBD
Annotation Queries
getAnnotation
params: id returns annotation js assoc array
getAnnotations params: entity : list [e.g. gene product or complex identifier, UniProtKB:nnnn] class [direct annotations] inferred_class [indirect] reference evidence_type : list date: string [YYYY-MM-DD or YYYY-MM-DD..YYYY-MM-DD for ranges] ... max
notes: any list is treated as a disjunctive query
returns: assoc number_of_annotations: int annotations: list of annotations other metadata TBD
getAnnotationIDs params: --> as getAnnotations returns ID list ID mapping services
getAlternateIDs params id : list [e.g. UniProtKB:nnnnn] db : list [DBs to map to - if empty checks all] returns: list of assocs id : string (source ID) xrefs : list of IDs
Phylogenetic Tree services
getPhylogeneticTree
params: id (e.g. PANTHER:PTHR123, UniProtKB:O12345)
getPhylogeneticTreeIDs
params: id: list (tree IDs e.g panther) entity id: list (e.g UniProtKB:nnnn) returns: ID list
C(R)UD
create / read / update /delete
security model: every user identified by unique email address
Delete
deleteAnnotation
params: id metadata (optional) comments authority TBD (some captured automatically - e.g. date) returns (assoc array): success: boolean annotations_deleted: int message: string (e.g. reason for failure)
Note: annotations are never truly deleted
Create
insertAnnotation
params: annotation (js struct for annotation) returns (assoc array): id : string sucess: boolean annotations_inserted: int message: string (e.g. reason for failure)
Update
updateAnnotation
params: id annotation (js struct for annotation) returns (assoc array): sucess: boolean annotations_inserted: int message: string (e.g. reason for failure)
createAnnotationSet
deleteAnnotationSet
addAnnotationToAnnotationSet
deleteAnnotationFromAnnotationSet