monarch.api

Summary
monarch.api
Functions
bbop.monarch.Engineconstructor for Engine object
fetchDiseaseInfoRetrieves JSON block providing info about a disease
fetchPhenotypeInfoRetrieves JSON block providing info about a phenotype
fetchGenotypeInfoRetrieves JSON block providing info about a genotype
fetchGeneInfoStatus: PARTIALLY IMPLEMENTED
fetchOmimDiseasePhenotypeAsAssocationsStatus: IMPLEMENTED
fetchOmimDiseaseGeneAsAssocationsStatus: IMPLEMENTED
fetchOmimGeneAllelePhenotypeAsAssociationsStatus: DEPRECATED
makeGenotypeStatus: MOSTLY IMPLEMENTED
searchByDiseaseStatus: Partially Implemented
searchByPhenotypeProfileReturns phenotypically similar entities of a given type.
searchByAttributeSetReturns: ordered list of matches
getAnnotationSufficiencyScoreReturns: ordered list of matches
fetchClassInfoRetrieves JSON blob providing info about an ontology class
keywordSearchOverOntologiesGet list of terms matching keywords.
searchOverOntologiesGet list of classes matching keywords
searchSubstringServices used: NIF vocabulary autocomplete
fetchDataFromResourceServices used: NIF federation call.
fetchUrlGenerate fetch over HTTP
resolveClassIdResolves one of the many identifier styles to a canonical NIF-style class ID

Functions

bbop.monarch.Engine

bbop.monarch.Engine = function(opts)

constructor for Engine object

Example

engine = new bbop.monarch.Engine();

Arguments

opts : associative array.  Keys: ontology_services_url, federation_services_url

fetchDiseaseInfo

bbop.monarch.Engine.prototype.fetchDiseaseInfo = function(id,
opts)

Retrieves JSON block providing info about a disease

The returned object will be the same as that for fetchClassInfo, enhanced with disease-specific information

Known issues

If a DOID is used, similarity scores will not be returned.  This should be resolved when the Federation API makes use of equivalence axioms.

Example

var diseaseInfo = engine.fetchDiseaseInfo(“DOID_1430”);

Status

status: PARTIALLY IMPLEMENTED

Arguments

id : An identifier.  One of: IRI string, OBO-style ID or NIF-style ID

Returns: JSON blob with info about the disease

fetchPhenotypeInfo

bbop.monarch.Engine.prototype.fetchPhenotypeInfo = function(id,
opts)

Retrieves JSON block providing info about a phenotype

Status: STUBjust diseases.  No transitive closure.

Retrieves JSON block providing info about a phenotype

The returned object will be the same as that for fetchClassInfo, enhanced with phenotype-specific information

Arguments

id : An identifier.  One of: IRI string, OBO-style ID or NIF-style ID opts : An associative array (EXTENSIBLE, OPTIONAL)

Returns: JSON blob with info about the phenotype

fetchGenotypeInfo

bbop.monarch.Engine.prototype.fetchGenotypeInfo = function(id,
opts)

Retrieves JSON block providing info about a genotype

The structure follows geno, e.g.

 { id: ZDB-GENO-...?, label:, a<tm1>/a<+>;foo<x>/foo<x>(AB), type: effective_genotype
   has_part : [

     { id: , label:, a<tm1>/a<+>;foo<x>/foo<x>(AB), type: intrinsic_genotype  ## aka SO:genotype
       has_reference_part : {
       id:.., label:AB, type: genomic_background
       }
       has_variant_part : {
         id:.., label:, a<tm1>/a<+>;foo<x>/foo<x>, type: genomic_variation_complement,
         has_variant_part : [
          {
           id:.., label:, a<tm1>/a<+>, type: variation_single_locus_complement,
           has_variant_part : [
            {
             id: ZDB-ALT-, label: a<tm1>, type: variant_locus,
             is_locus_instance_of : {
               id: ZDB-GENE-..., label: a, type: gene_locus,
               has_variant_part : {
                 id:, label: tm1, type: point_mutation
               }
}}]}]}}]}

Arguments

id : An identifier.  One of: IRI string, OBO-style ID or NIF-style ID opts : An associative array (EXTENSIBLE, OPTIONAL)

Returns: JSON blob with info about the genotype

fetchGeneInfo

bbop.monarch.Engine.prototype.fetchGeneInfo = function(id,
opts)

Status: PARTIALLY IMPLEMENTED

TODOdecide whether core gene info should come from ontology or federation

Retrieves JSON block providing info about a gene, currently from MyGene

The returned object will be the same as that for fetchClassInfo, enhanced with gene-specific information

Arguments

id : An identifier.  One of: IRI string, OBO-style ID or NIF-style ID

Returns: JSON blob with info about the gene

fetchOmimDiseasePhenotypeAsAssocations

bbop.monarch.Engine.prototype.fetchOmimDiseasePhenotypeAsAssocations = function(
   id
)

Status: IMPLEMENTED

Given a query term (e.g. an ID, either disease or phenotype), return an association list object, with structure:

{ resultCount : NUM, results: [ASSOC1, ...., ASSOCn] }

Where ASSOC is an associative array representing a disease-phenotype association with the following keys:

  • disease : a disease structure
  • phenotype : a disease structure
  • onset
  • frequency
  • source
  • resource

Both disease and phenotype structures are associative arrays keyed with id and label.

Stability

  • we may change the JSON object returned to be JSON-LD compliant
  • federation query may use ID mapping and OWL equivalence axioms in future

Arguments

  • id : An identifier.  One of: IRI string, OBO-style ID or NIF-style ID

Returns: JSON representing list of D-P associations

fetchOmimDiseaseGeneAsAssocations

Status: IMPLEMENTED

Given a query term (e.g. an ID, either disease or phenotype), return an association list object, with structure:

{ resultCount : NUM, results: [ASSOC1, ...., ASSOCn] }

Where ASSOC is an associative array representing a disease-gene association.

Stability

  • we may change the JSON object returned to be JSON-LD compliant
  • federation query may use ID mapping and OWL equivalence axioms in future

Arguments

  • id : An identifier.  One of: IRI string, OBO-style ID or NIF-style ID.  E.g.  OMIM_105830

Returns: JSON representing list of D-G associations /

fetchOmimGeneAllelePhenotypeAsAssociations

Status: DEPRECATED

makeGenotype

bbop.monarch.Engine.prototype.makeGenotype = function(r)

Status: MOSTLY IMPLEMENTED

This is meant as an internal function to take a row ® from NIF geno or pheno tables, and extract out the parts pertaining to a genotype, and build the JSON genotype object, following the GENO model.  This will probably go away once we are able to get this data from D2R transformed datastore What is presently missing is the aggregation of genotype parts.  So, because the source data is denormalized, one genotype can have multiple rows, and will currently create multiple JSON objects with only partially-overlapping contents.  This will be confusing.

searchByDisease

bbop.monarch.Engine.prototype.searchByDisease = function(id,
target_species,
cutoff,
metric)

Status: Partially Implemented

This function will take some kind of identifier (disease, genotype), and find those “things” that are similar.  First implementation will take a disease or genotype identifier, and find the top “cutoff” things (either diseases or animal models) based on the owlsim precomputed piepline.  These are loaded statically in the NIF/Monarch tables, with a resource identification map to locate the correct precomputed table in NIF.  Defaults are set for cutoff(25) and metric (BMAasymIC), but the query id and target_species should be supplied in order to know what table needs to be fetched This currently does an iterative lookup in order to get all the labels.  Note sure if that is the best strategy.  This wrapping function could easily have precomputed or on-the-fly functions added or swapped.

TODO: this can be extended to apply other kinds of filters to limit the data considered, or only specific classes or whatever.  Lots of possiblities for the future.  TODO: this should really have a target_type filter, and the selection of the precomputed dataset should be based on the combination of source_taxid, target_taxid, a_type, and b_type.

searchByPhenotypeProfile

bbop.monarch.Engine.prototype.searchByPhenotypeProfile = function(
   query,
   target_species,
   target_type,
   cutoff,
   metric
)

Returns phenotypically similar entities of a given type.

This is currently hardcoded to types per species, but will be expanded in the future to be more customizable.

Status: PARTIALLY IMPLEMENTED

Arguments

  • query : a list of phenotype identifiers
  • target_species : numeric fragment of NCBITaxon identifier
  • target_type : genotype | disease | gene | variation (NOT IMPLEMENTED)
  • cutoff :
  • metric :

searchByAttributeSet

bbop.monarch.Engine.prototype.searchByAttributeSet = function(atts,
tf,
limit)

Returns: ordered list of matches

Arguments

  • atts : list of class identifiers
  • target_filter: An ID space (string) [e.g.  ZFIN] OR a query object
  • limit : number of results to return.

Query objects are only partially supported.  An ID space can be used in place of an object, but this usage may be deprecated in future.

Keys

  • target: an ID space
  • species: numeric fragment of NCBITaxon ID or IRI
  • type: one of gene | genotype | disease (NOT IMPLEMENTED)

getAnnotationSufficiencyScore

bbop.monarch.Engine.prototype.getAnnotationSufficiencyScore = function(atts)

Returns: ordered list of matches

Arguments

  • atts : list of class identifiers
  • target: (optional) e.g.  MGI
  • limit : number of results to return

fetchClassInfo

bbop.monarch.Engine.prototype.fetchClassInfo = function(id,
opts)

Retrieves JSON blob providing info about an ontology class

Data structures

  • Class = { id: ID, label : LABEL, relationships: [Relationship*] OPTIONAL }
  • Relationship = { subject: OBJ, property : OBJ, object : OBJ }
  • Obj = { id : ID, label : LABEL }

Services used

  • OntoQuest

Options

  • level : See OntoQuest docs.  If set, a list of relationships will form a graph with distance=level focused on class

Implementation notes

  • makes use of OntoQuest REST API which returns XML

Arguments

  • id : An identifier.  One of: IRI string, OBO-style ID or NIF-style ID
  • opts : Dictionary parameter

Returns: Class struct as JSON

keywordSearchOverOntologies

Get list of terms matching keywords.  Here a ‘term’ is just a string (TODO: find if there is a way to get OQ return ID+label pairs)

TODO: all ancestors.  E.g.  http://nif-services.neuinfo.org/ontoquest/keyword/glial+c/anc/terms/cell;process

Can be used for auto-complete

Arguments

  • term : keyword
  • opts : Dictionary parameter

Returns: Class struct as JSON

searchOverOntologies

bbop.monarch.Engine.prototype.searchOverOntologies = function(term,
opts)

Get list of classes matching keywords

TODO: all ancestors.  E.g.  http://nif-services.neuinfo.org/ontoquest/keyword/glial+c/anc/terms/cell;process

Arguments

  • term : keyword
  • opts : Dictionary parameter

Returns: Class struct as JSON

searchSubstring

bbop.monarch.Engine.prototype.searchSubstring = function(term)

Services used: NIF vocabulary autocomplete

Arguments

term : search term Returns: JSON structure - as per NIF vocabular services

fetchDataFromResource

bbop.monarch.Engine.prototype.fetchDataFromResource = function(id,
resource_id,
trFunction,
projectCols,
filters,
limit,
sortField,
opts)

Services used: NIF federation call.  See: http://beta.neuinfo.org/services/resource_FederationService.html#path__federation_data_-nifId-.html

This currently relies on OntoQuest magic to ensure that the input ontology class ID is expanded to all relevant https://support.crbs.ucsd.edu/browse/LAMHDI-140

Arguments

q : query.  Arbitrary term or NIF ID resource_id : E.g. nlx_151835-1 trFunction : a function to be applied to each result object which returns a transformed object project : a list of columns to project (select) filters : a list of filters to be applied at fetching time Returns: JSON structure { resultCount : NUM, results: [ TRANSFORMED-OBJECTS ] }

fetchUrl

bbop.monarch.Engine.prototype.fetchUrl = function(url,
params,
method)

Generate fetch over HTTP

In future this will abstract over base implementation: rhino vs jquery

Arguments

url : string params : string OR list OR dict

Returns: stringmay be JSON, XML, who knows

resolveClassId

bbop.monarch.Engine.prototype.resolveClassId = function(id)

Resolves one of the many identifier styles to a canonical NIF-style class ID

Example: resolveClassId(“OMIM:123456”) returns “OMIM_123456”

Arguments

id : string

Returns: NIF-style ID

bbop.monarch.Engine = function(opts)
constructor for Engine object
bbop.monarch.Engine.prototype.fetchDiseaseInfo = function(id,
opts)
Retrieves JSON block providing info about a disease
bbop.monarch.Engine.prototype.fetchPhenotypeInfo = function(id,
opts)
Retrieves JSON block providing info about a phenotype
bbop.monarch.Engine.prototype.fetchGenotypeInfo = function(id,
opts)
Retrieves JSON block providing info about a genotype
bbop.monarch.Engine.prototype.fetchGeneInfo = function(id,
opts)
Status: PARTIALLY IMPLEMENTED
bbop.monarch.Engine.prototype.fetchOmimDiseasePhenotypeAsAssocations = function(
   id
)
Status: IMPLEMENTED
bbop.monarch.Engine.prototype.makeGenotype = function(r)
Status: MOSTLY IMPLEMENTED
bbop.monarch.Engine.prototype.searchByDisease = function(id,
target_species,
cutoff,
metric)
Status: Partially Implemented
bbop.monarch.Engine.prototype.searchByPhenotypeProfile = function(
   query,
   target_species,
   target_type,
   cutoff,
   metric
)
Returns phenotypically similar entities of a given type.
bbop.monarch.Engine.prototype.searchByAttributeSet = function(atts,
tf,
limit)
Returns: ordered list of matches
bbop.monarch.Engine.prototype.getAnnotationSufficiencyScore = function(atts)
Returns: ordered list of matches
bbop.monarch.Engine.prototype.fetchClassInfo = function(id,
opts)
Retrieves JSON blob providing info about an ontology class
bbop.monarch.Engine.prototype.searchOverOntologies = function(term,
opts)
Get list of classes matching keywords
bbop.monarch.Engine.prototype.searchSubstring = function(term)
Services used: NIF vocabulary autocomplete
bbop.monarch.Engine.prototype.fetchDataFromResource = function(id,
resource_id,
trFunction,
projectCols,
filters,
limit,
sortField,
opts)
Services used: NIF federation call.
bbop.monarch.Engine.prototype.fetchUrl = function(url,
params,
method)
Generate fetch over HTTP
bbop.monarch.Engine.prototype.resolveClassId = function(id)
Resolves one of the many identifier styles to a canonical NIF-style class ID
Close