LexBIG/EVS API Overview

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.

LexBIG Architecture 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. Content RRF OBO Protégé OWL Text XML XML OBO Other Import Export Representation LexGrid Vocabulary Access Model File System: Metadata & Data Indexes Repository Programming Interfaces Tools And Services APIs LexBIG/ EVS CTS Embed Apps Application Server Java Web/Grid Services Distributed API

Conceptual Overview LexGrid Model & Storage LexBIG/EVS Java API Browsers and Applications LexBIG/EVS Distributed Service LexBIG/EVS cagrid Service

LexBIG/EVS API LexGrid Model & Storage LexBIG/EVS Java API

LexBIG/EVS API Characteristics API coverage Administrative Functions Query Code Systems and Available Metadata Query Concepts, Concept Properties, and Qualifications Query Concept Relationships and Qualifications API characteristics Conscious separation of service and data classes Deferred query resolution Payload optimization Support iteration Defined extension points (loaders, exporters, sort algorithms, filters, f 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 API - Distributed LexGrid Model & Storage LexBIG/EVS Java API LexBIG/EVS Distributed Service

LexBIG/EVS API Distributed LexBIG on Local System Database Server LexBIG Install JDBC Direct Client System LexBIG Client API Proxy Distributed LexBIG Server LexBIG Install Database Server RMI JDBC Distributed

LexBIG/EVS API Distributed Same API functions; requires change to service declaration only Does not expose administration options // 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);

LexBIG/EVS API - cagrid LexGrid Model & Storage LexBIG/EVS Java API LexBIG/EVS Distributed Service LexBIG/EVS cagrid Service

LexBIG/EVS API - cagrid LexBIG on Local System Database Server LexBIG Install JDBC Direct Client System LexBIG Client API Proxy Distributed LexBIG Server LexBIG Install Database Server RMI JDBC Distributed Client System cagrid Host Server Distributed LexBIG Server Database Server LexBIG Client Proxy LexBIG Proxy LexBIG Install TCP RMI JDBC Grid

LexBIG/EVS API - cagrid Same API Functionality Client cagrid Service Distributed LexBIG Calls cagrid getsupportedcodingschemes() Calls Distributed LexBIG getsupportedcodingschemes() Results are returned to client with all appropriate cagrid security mechanisms Returns result of call to cagrid Service

cacore SDK APIs LexGrid Model & Storage cacore SDK APIs

cacore SDK APIs Query-by-example (QBE) system Based on LexGrid model Java Language Binding Web Services (SOAP) Web Services (REST HTTP / XML) cacore EVS Server Web Web Services XML XML // HTML HTML Java Java QBE QBE Service Layer Cache DAO Hibernate Database Server LexBIG Install JDBC

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)

Browsers and Applications LexGrid Model & Storage LexBIG/EVS Java API Browsers and Applications LexBIG/EVS Distributed Service LexBIG/EVS cagrid Service

User Interfaces - LexBIG GUI

User Interfaces - BioPortal

Project Links LexEVS Project http://gforge.nci.nih.gov/projects/lexevs/ cabig Vocabulary Knowledge Center https://cabig-kc.nci.nih.gov/vocab/kc/index.php/main_page