LexBIG/EVS API Overview

NCBO Seminar Series

October 2008

What is LexBIG?

• A specific API to serve vocabularies based on the LexGrid model, developed for the Cancer Biomedical Informatics Grid (caBIG®) community.

• Open source implementation.• Underpins current NCI Enterprise Vocabulary Services

(EVS).• Represents the next generation EVS API.• Additional contributions and tuning to meet the needs

of the NCBO community, based on development of NCBO BioPortal services.

OtherOBO

Content

Export

ImportOWL

XML

OBO

Text

Protégé

RRF

XML

Representation

LexGridVocabulary

Model

DataRepository

LexBIG Architecture

Tools And Services

Access

Program

ming Interfaces

APIs

LexBIG/ EVS

…

CTS

Apps

Java

Embed

Web/GridServices

DistributedAPI

ApplicationS

erver• Each LexGrid ‘Node’ provides the software, metadata,

indexes, and backing data store to service one or more vocabularies.

• Each LexBIG Installation represents one LexGrid Node and Java API to administer and query data.

File System:Metadata &

Indexes

LexBIG/EVS caGrid Service

LexBIG/EVS Distributed Service

LexBIG/EVS Java API

Conceptual Overview

LexGridModel & Storage

Browsers and Applications

LexBIG/EVS Java API

LexBIG/EVS API

LexGridModel & Storage

LexBIG/EVS API – Characteristics

• API coverage•• Administrative FunctionsAdministrative Functions•• Query Code Systems and Available MetadataQuery Code Systems and Available Metadata•• Query Concepts, Concept Properties, and QualificationsQuery Concepts, Concept Properties, and Qualifications•• Query Concept Relationships and QualificationsQuery Concept Relationships and Qualifications

• API characteristics•• Conscious separation of service and data classesConscious separation of service and data classes•• Deferred query resolutionDeferred query resolution•• Payload optimizationPayload optimization•• Support iterationSupport iteration•• Defined extension points (loaders, exporters, sort algorithms, fDefined extension points (loaders, exporters, sort algorithms, filters, ilters,

convenience methods)convenience methods)

LexBIG/EVS API – Example

• Prerequisites• ICD-9-CM loaded from UMLS distribution (RRF source files)

LoadUMLSFiles [-s null] [-mf uri] [-v int] [-lp uri] [-nf] -in uri [-t id] [-mh int] [-a]

Example: LoadUMLSFiles -in file:///path/to/directory/ -s “ICD9CM" -nf -a

-s,--sources Comma-delimited list of source vocabularies to load.-mh,--mrhier <int> Process hierarchical relationships stored by the MRHIER file. 0=none, 1=HCD-tagged items (default)-a,--activate ActivateScheme on successful load.-in,--input <uri> URI or path specifying the directory containing the NLM files.-lp,--loadPrefs <uri> URI or path specifying location of the Loader Preferences file.-mf,--manifest <uri> URI or path specifying location of the manifest file.-nf,--noFail If specified, indicates that processing should not stop for recoverable errors.-t,--tag <id> An optional tag ID (e.g. 'PRODUCTION' or 'TEST') to assign.-v,--validate <int> Validation only; no load. If specified, 'nf', 'a' and 't‘ are ignored. 0 to verify files exist.

LexBIG/EVS API – Example

• Let’s query some concepts …

• Target a code system• Define a new LexBIGService as starting point.• Define a concept ‘space’ (a codedNodeSet) for ICD-9-CM, version 2007• Note: Initially unrestricted and unresolved

LexBIGService lbs = new LexBIGServiceImpl();CodedNodeSet cns = lbs.getCodingSchemeConcepts("ICD-9-CM", null);

LexBIG/EVS API – Example

• Prerequisites• ICD-9-CM loaded from UMLS distribution (RRF source files)

• Target a code system• Define a concept ‘space’ (a codedNodeSet) for ICD-9-CM, version 2007• Initially unrestricted and unresolved

• Restrict the space based by adding constraints• Property ‘Semantic Type’ -> exact match -> “Disease or Syndrome”

LexBIGService lbs = new LexBIGServiceImpl();CodedNodeSet cns = lbs.getCodingSchemeConcepts("ICD-9-CM", null);cns.restrictToMatchingProperties( Constructors.createLocalNameList(

"Semantic_Type"), null, "Disease or Syndrome", “exactMatch", null);

LexBIG/EVS API – Example

• Prerequisites• ICD-9-CM loaded from UMLS distribution (RRF source files)

• Target a code system• Define a concept ‘space’ (a codedNodeSet) for ICD-9-CM, version 2007• Initially unrestricted and unresolved

• Restrict the space based by adding constraints• Property ‘Semantic Type’ -> exact match -> “Disease or Syndrome”• Primary text match -> sounds like -> ‘infeksion’

LexBIGService lbs = new LexBIGServiceImpl();CodedNodeSet cns = lbs.getCodingSchemeConcepts("ICD-9-CM", null);cns.restrictToMatchingProperties( Constructors.createLocalNameList(

"Semantic_Type"), null, "Disease or Syndrome", “exactMatch", null);cns.restrictToMatchingDesignations("infeksion", SearchDesignationOption.

PREFERRED_ONLY, “DoubleMetaphoneLuceneQuery”, null);

LexBIG/EVS API – Example

• Prerequisites• ICD-9-CM loaded from UMLS distribution (RRF source files)

• Target a code system• Define a concept ‘space’ (a codedNodeSet) for ICD-9-CM, version 2007• Initially unrestricted and unresolved

• Restrict the space based by adding constraints• Property ‘Semantic Type’ -> exact match -> “Disease or Syndrome”• Primary text match -> sounds like -> ‘infeksion’• Any text stemmed match -> ‘classify’ (to match ‘classified’, ‘classifying’, etc)

LexBIGService lbs = new LexBIGServiceImpl();CodedNodeSet cns = lbs.getCodingSchemeConcepts("ICD-9-CM", null);cns.restrictToMatchingProperties( Constructors.createLocalNameList(

"Semantic_Type"), null, "Disease or Syndrome", “exactMatch", null);cns.restrictToMatchingDesignations("infeksion", SearchDesignationOption.

PREFERRED_ONLY, “DoubleMetaphoneLuceneQuery”, null);cns.restrictToMatchingDesignations("classify", SearchDesignationOption.ALL,

"StemmedLuceneQuery“, null);

LexBIG/EVS API – Example

• Prerequisites• ICD-9-CM loaded from UMLS distribution (RRF source files)

• Target a code system• Define a concept ‘space’ (a codedNodeSet) for ICD-9-CM, version 2007• Initially unrestricted and unresolved

• Restrict the space based by adding constraints• Property ‘Semantic Type’ -> exact match -> “Disease or Syndrome”• Primary text match -> sounds like -> ‘infeksion’• Any text stemmed match -> ‘classify’ (to match ‘classified’, ‘classifying’, etc)• Concept must be active

LexBIGService lbs = new LexBIGServiceImpl();CodedNodeSet cns = lbs.getCodingSchemeConcepts("ICD-9-CM", null);cns.restrictToMatchingProperties( Constructors.createLocalNameList(

"Semantic_Type"), null, "Disease or Syndrome", “exactMatch", null);cns.restrictToMatchingDesignations("infeksion", SearchDesignationOption.

PREFERRED_ONLY, “DoubleMetaphoneLuceneQuery”, null);cns.restrictToMatchingDesignations("classify", SearchDesignationOption.ALL,

"StemmedLuceneQuery“, null);cns.restrictToStatus(ActiveOption.ACTIVE_ONLY, null);

LexBIG/EVS API – Example

• Prerequisites• ICD-9-CM loaded from UMLS distribution (RRF source files)

• Target a code system• Define a concept ‘space’ (a codedNodeSet) for ICD-9-CM, version 2007• Initially unrestricted and unresolved

• Restrict the space based by adding constraints• Property ‘Semantic Type’ -> exact match -> “Disease or Syndrome”• Primary text match -> sounds like -> ‘infeksion’• Any text stemmed match -> ‘classify’ (to match ‘classified’, ‘classifying’, etc)• Must contain a property with name -> ‘UMLS_CUI’• Concept must be active

• Indicate sort preferences and limit number returned• Sort by code, ascending• Limit to top 5

…cns.restrictToStatus(ActiveOption.ACTIVE_ONLY, null);ResolvedConceptReferenceList list = cns.resolveToList(

Constructors.createSortOptionList(new String[] { "matchToQuery", "code" }),null, null, 5);

LexBIG/EVS API – Example

• Prerequisites• ICD-9-CM loaded from UMLS distribution (RRF source files)

• Target a code system• Define a concept ‘space’ (a codedNodeSet) for ICD-9-CM, version 2007• Initially unrestricted and unresolved

• Restrict the space based by adding constraints• Property ‘Semantic Type’ -> exact match -> “Disease or Syndrome”• Primary text match -> sounds like -> ‘infeksion’• Any text stemmed match -> ‘classify’ (to match ‘classified’, ‘classifying’, etc)• Must contain a property with name -> ‘UMLS_CUI’• Concept must be active

• Indicate sort preferences and limit number returned• Sort by code, ascending• Limit to top 5

• Resolve!

LexBIG/EVS API – Example 2

• OK, now find some relationships…

• Target a code system• Define an unrestricted graph for a target ontology (e.g. ICD-9-CM)

CodedNodeGraph cng = lbs.getNodeGraph("ICD-9-CM", null, null);

LexBIG/EVS API – Example 2

• OK, now find some relationships…• Target a code system

• Define an unrestricted graph for a target ontology (e.g. ICD-9-CM)• Restrict by adding constraints

• Restrict to hierarchical relationships (UMLS-defined ‘CHD’ = has child)

CodedNodeGraph cng = lbs.getNodeGraph("ICD-9-CM", null, null);cng.restrictToAssociations(Constructors.createNameAndValueList(“CHD"), null);

LexBIG/EVS API – Example 2

• OK, now find some relationships…• Target a code system

• Define an unrestricted graph for a target ontology (e.g. ICD-9-CM)• Restrict by adding constraints

• Restrict to hierarchical relationships (UMLS-defined ‘CHD’ = has child)• Indicate extent of navigation

• Set focal point (008 = ‘Intestinal infections due to other organisms’)• Maximum 2 levels, full reporting at all levels• Moving only in forward direction• No application of filter extensions, etc• Maximum 50 nodes resolved overall

CodedNodeGraph cng = lbs.getNodeGraph("ICD-9-CM", null, null);cng.restrictToAssociations(Constructors.createNameAndValueList(“CHD"), null);cng.resolveAsList(Constructors.createConceptReference("008", "ICD-9-CM"), true, false, 2, 2, null, null, null, null, 50);

LexBIG/EVS API – Example 2

• OK, now find some relationships…• Target a code system

• Define an unrestricted graph for a target ontology (e.g. ICD-9-CM)• Restrict by adding constraints

• Restrict to parent/child relationships (UMLS-defined ‘PAR’ = has parent)• Restrict to the codedNodeSet defined in the previous example

• Indicate extent of navigation• Set focal point (008 = ‘Intestinal infections due to other organisms’)• Maximum 2 levels, moving in forward direction• Maximum 50 nodes resolved overall

• Resolve!

LexBIG/EVS Distributed Service

LexBIG/EVS Java API

LexBIG API - Distributed

LexGridModel & Storage

Database Server

LexBIG/EVS API – Distributed

Distributed LexBIG Server

RMI

LexBIG on Local System

LexBIG Install

Database Server

LexBIG Install

JDBC

JDBC

Direct

Distributed

LexBIG API Proxy

Client System

LexBIG Client Proxy

LexBIG/EVS API – Distributed

// Set the URL (for distributed access) and establish a remote service …String evsUrl = “http://evsapi.nci.nih.gov/evsapi41/http/remoteService”;LexBIGService lbSvc = EVSApplicationService.getRemoteInstance(evsUrl);

// Additional code is unchanged …CodedNodeSet cns = lbs.getCodingSchemeConcepts("ICD-9-CM", null);cns.restrictToMatchingProperties( Constructors.createLocalNameList(

"Semantic_Type"), null, "Disease or Syndrome", “exactMatch", null);cns.restrictToMatchingDesignations("infeksion", SearchDesignationOption.

PREFERRED_ONLY, “DoubleMetaphoneLuceneQuery”, null);cns.restrictToMatchingDesignations("classify", SearchDesignationOption.ALL,

"StemmedLuceneQuery“, null);…

• Same API functions; requires change to service declaration only• Does not expose administration options

LexBIG/EVS caGrid Service

LexBIG/EVS Distributed Service

LexBIG/EVS Java API

LexBIG/EVS API - caGrid

LexGridModel & Storage

Database Server

LexBIG/EVS API - caGrid

Distributed LexBIG Server

RMI

LexBIG on Local System

LexBIG Install

Database Server

LexBIG Install

JDBC

JDBC

Direct

DistributedDatabase Server

LexBIG API Proxy

Client System

caGrid Host ServerClient System Distributed LexBIG Server

RMI

LexBIG Install

Grid

JDBCTCP

LexBIG Proxy

LexBIG Client Proxy

LexBIG Client Proxy

Same API Functionality

Client caGrid Service Distributed LexBIGCalls caGrid ‘getSupportedCodingSchemes()’

Calls Distributed LexBIG‘getSupportedCodingSchemes()

Returns result of call to caGrid Service

Results are returned to clientwith all appropriate caGrid security mechanisms

LexBIG/EVS API - caGrid

caCORE SDK APIs

caCORE SDK APIs

LexGridModel & Storage

• Query-by-example (QBE) system• Based on LexGrid model

• Java Language Binding• Web Services (SOAP)• Web Services (REST HTTP / XML)

caCORE EVS Server

Web ServicesWeb Services

XML / HTMLXML / HTML

Java QBEJava QBE

LexBIG Install

DAO

CacheService Layer

Database Server

JDBC

caCORE SDK APIs

Hibernate

caCORE SDK APIs - Example

SDK-Generated Query by Example User Interface:

caCORE SDK APIs - Example

Example Restful Request (HTML)…

Example Restful Output (HTML shown, XML also available)…

LexBIG/EVS caGrid Service

LexBIG/EVS Distributed Service

LexBIG/EVS Java API

Browsers and Applications

LexGridModel & Storage

Browsers and Applications

User Interfaces - LexBIG GUI

User Interfaces - BioPortal

Project Links

• LexEVS Projecthttp://gforge.nci.nih.gov/projects/lexevs/• caBIG® Vocabulary Knowledge Centerhttps://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Main_Page