Monarch Services
Overview
There are currently three types of service calls:
  • Fetch a data object: fetch all information about a particular entity (disease, phenotype, etc.)
  • Search: fetch matches based on specified search criteria. Search may be:
    • Lexical - e.g. find all diseases for string "renal"
    • Logical - e.g. find all entities relevant for "kidney" or its parts
    • Similarity-based - e.g. find all models that have a close match to a set of phenotypes
  • Compute: perform a computation on a set of phenotypes against data loaded into the owlsim server.
Service calls are implemented via one or more calls to other Monarch/NIF services.
Data Objects
A data object is a json object containing all information about a particular entity. A data object may be constructed via one or more calls to other services (including OntoQuest, Federation and OwlSim).

Data Object URLs

The general schema for data objects is:
                        $BASEURL/:datatype/:id.json
                        
For a sub-part of this object the general schema:
                        $BASEURL/:datatype/:id/:section.json
                        
Each of these is implemented as a call to the JS API. Note that each of these URLs corresponds to a page in the UI. On any page in the Monarch system, suffix .json onto the end of the URL to retrieve data.

Datatypes

The current list of datatypes:

REST API Documentation

To see the full documentation, see: Auto-generated documentation

Data Object JSON specification

The specification for the JSON data objects returned is still unstable. For details, please see the JS API. The following principles are adhered to:
  • JSON-LD is used
  • Each object is uniquely identified by an id: field. This maps to the IRI in the JSON LD context
  • Each object should have a human-readable name identified with a label: field. This maps to rdfs:label in the JSON LD context
  • Each object should be typed using a type: field. This maps to rdf:type in the JSON LD context. Note that the type may be specified as a human-readable string, with this mapped to an IRI in the context object.
  • Nesting is preferred over flat structures

RDF/OWL services

Each data object can be returned as RDF by switching .json for .rdf (or .nt). The mapping from JSON to RDF is specified entirely by the JSON-LD context.
Search

Ontology Search

URLs are of the form
                        /search/:term.json
                        
This wraps a call to OntoQuest - OQ XML is translated to a standard JSON from: searchOverOntologies(:term,:opts)

Profile Search

OwlSim is used for semantic matching. Currently services are only supported for a subset of entities in the system - those with phenotypes.

Search for Entities

Find all entities that instantiate a set of attributes matching an input set of attributes. For example, find all animal models matching a disease phenotype profile.
                        /analyze/phenotypes.json?input=items=a1+a2+...+an
                        
For example:
                        /analyze/phenotypes.json?input=items=/analyze/phenotypes.json/?input_items=MP:0000788+MP:0000914
                        
This wraps a call to findMatches(atts, target) in OwlSim.
Compute

Compare

We use OwlSim for semantic matching when comparing two entities with sets of attributes. Currently services are only supported for a subset of entities in the system - those with phenotypes.

Comparing two entities

URLs are of the form
                        /compare/:x/:y.json
                        
This wraps a call to getGroupwiseSimilarity(x,y) in OwlSim.

Comparing two sets of attributes

Coming soon.

Profile Information

We use Information Content (IC)-based algorithms to compute similarity scores in the Monarch system. You can retrieve the computed IC scores for each ontology class, plus summary statistics for a phenotype profile and the overall system. This will also compute an Annotation Sufficiency score using a set of 20 pre-defined high-level phenotype classes.

URLs are of the form:
					/score?annotation_profile=:profile
					
The profile needs to be supplied as a JSON object with the following minimal structure:
					{ features : [ {id : :id}, ...] }
					
Where the ids are of phenotypes or other classes contained in our Monarch ontology import chain. Non-existent classes will be tossed from the calculation, and reported as unresolvable_classes.

You may supply "not" or "normal" annotations as part of the profile by adding an isPresent : false attribute to each object. These are presently weighted equally to "abnormal" annotations when calculating the sufficiency score.

Here are a few examples of the annotation_profile JSON objects:
  • Example 1: A simple profile with four phenotypes.
         {"features" : [{"id":"HP:0000505"},{"id":"HP:0000479"},{"id":"HP:0001010"},{"id":"HP:0000044"}]}
  • Example 2: You can supply an optional identifier for your own purposes, but it is ignored by our system
         {"id"       : "MONARCH:Example2",
         "features"  : [{"id":"HP:0000505"},{"id":"HP:0000479"},{"id":"HP:0001010"},{"id":"HP:0000044"}]}
  • Example 3: You can provide both normal and abnormal qualifiers
         {"features" : [{"id":"HP:0000505",isPresent : true},{"id":"HP:0000479", isPresent : false},
                        {"id":"HP:0001010",isPresent : true},{"id":"HP:0000044", isPresent : false}]}
    
  • Example 4: An annotation profile with few "abnormal" annotations, but many "normal/not"
There are three scores provided, each with a range of (0..1):
  • simple: A simple measure of amount of information in the profile, with an emphasis on number and depth of annotations.
  • categorical: A score computed similar to the simple score, Annotations are first split into high-level phenotypic categories, a sub-score is computed for each subset/category (similar to the simple score above), which are finally averaged together.
  • scaled: A combined score with weights applied to the simple and categorical scores. This is the score displayed in the Monarch web interface.

Summary statistics for the profile, the system, and for each category are provided for you if you choose to compute your own profile scores.

Implementation
See webapp.js in the source.