Page History

...

Service Metadata Retrieval

...

Combinatorial Queries

One of the most powerful features of the LexEVS architecture is the ability to define multiple search and sort criteria without intermediate retrieval of data from the LexEVS service. Consider the following code snippet:

...

This example shows a simple yet powerful query to search a code system based on a 'sounds like' match algorithm (the list of all available match algorithms can be listed using the 'ListExtensions -m' admin script).<u>

Declaring the

...

Target Concept Space

The coded node set (variable 'cns') is initially declared to query the NCI Thesaurus vocabulary. At this point the concept space included by the set can be thought of as unrestricted, addressing every defined coded entry (the 'false' value on the declaration indicates to also include inactive concepts). However, it important to note that no search is performed by the LexEVS service at this time.<u>Applying filter criteria</u>

Applying Filter Criteria

Similarly, no computation is performed (to realize query results) during invocation of the <tt>restrictToMatchingDesignationsrestrictToMatchingDesignations()</tt> and <tt>restrictToMatchingPropertiesrestrictToMatchingProperties()</tt> methods. However, these calls effectively narrow the target space even further, indicating that filters should be applied to the information returned by the LexEVS query service.<u>

Using the Lucene Query Syntax and

...

Other Text Matching Functions

The text criteria applied in methods such as restrictToMatchingDesignations() uses one of a number of powerful text processing applications to provide the user with broad capability for text based searches. Text matches can be simple applications of exactMatch, startsWith or contains algorithms as well as powerful regular expressions and Lucene Query syntax (used in the LuceneQuery function.) As shown above these options are passed into the restrictToMatchingDesignations() Method as parameters.

Lucene Queries are well documented and can be very powerful. The uninitiated user may need some background on their use however. The user should start here with the official Lucene Query Parser documentation.

...

Likewise you should not expect to see a Lucene Query narrow down search results as you progressively enter a longer substring more closely matching your term of interest. Instead use the contains method.<u>Applying sorting criteria</u>

Applying Sorting Criteria

Multiple sort algorithms can be applied to control the order of items returned. In this case, we indicate that results are to be sorted based on primary and secondary criteria. The "matchToQuery" algorithm indicates to sort the result according to best match as determined by the search engine. The "code" item indicates to perform a secondary sort based on concept code.

...

...

Restricting the

...

Information Returned for Matching Items

The LexEVS API also allows the programmer to restrict the values returned for each matching concept. In this example, we chose to return only the UMLS CUI and assigned text presentations.<u>

Retrieving the

...

Result

A query is finally performed during the 'resolve' step, with results returned to the declared list. It is at this point that the LexEVS service does the heavy lifting. By declaring the full extent of the request up front (namespace, match criteria, sort criteria, and returned values), the service then has the opportunity to optimize the query path. In addition, in this example we restrict the number of items returned to a maximum of 6. This combined approach has the benefit of reducing server-side processing while minimizing the volume and frequency of traffic between the client program and the LexEVS service.

...

...

Additional Resources

The examples and automated test programs provided by the LexEVS installation (see the file breakdown in VKC:the section, Overview of the Software) are available as additional reference materials.

LexEVS GUI

The LexEVS Graphical User Interface, or GUI, is an optional component of the LexEVS install which will be in the /gui folder of the base LexEVS installation (see file breakdown in VKC:the section, Overview of the Software). The GUI is meant to provide a simple tool to test LexEVS API methods and quickly view the results; almost all public methods defined by the LexEVS API are supported. This guide provides a brief overview of how the GUI can aid programmers in writing code to the LexEVS API.

...

Launching the GUI

Depending on the operating systems that you selected at installation time, you should have one or more of the following programs in the <tt>/gui</tt> gui folder:

Linux_64-lbGUI.sh		Linux-lbGUI.sh	
OSX-lbGUI.command		Windows-lbGUI.bat

Launch the GUI by executing the appropriate script for your platform. You will be presented with an application that looks like this:
Image Modified

Overview

The upper section of the GUI shows all of the code systems currently loaded, along with corresponding metadata. The lower section of the GUI is used to combine, restrict and resolve Code Sets and Code Graphs.

The lower left section is where you can perform Boolean logic on Code Sets and Code Graphs. The lower right section is where you can introduce restrictions on Code Sets and Code Graphs and browse results.

...

Creating New Queries

There are four buttons on the top half that are of interest for creating queries. *

• Refresh - This button causes the LexEVS GUI to reread the available terminologies and their respective metadata. This can be useful when using the GUI to view a LexEVS environment that is being modified by another process.

...

• Get History - If a terminology with available history data is selected, this button opens a history browser to view it via the NCI history API. This option is currently only applicable when working with the NCI Thesaurus terminology.

...

• Get Code Set - This button causes the selected terminology to be added to the lower left section of the GUI as a code set - which is noted by a 'CS' prefix.

...

• Get Code Graph - This button causes the selected terminology to be added to the lower left section of the GUI as a code graph - which is noted by a 'CG' prefix.

Customizing Queries

After selecting a code system and clicking on Get Code Set or Get Code Graph, a row will be added to the lower left section of the GUI for each click. There are seven buttons in the lower left section that allow combinatorial logic between the code sets in the lower left. *

• Union - This button is enabled if two Code Sets or two Code Graphs are selected in the lower left. Clicking the button creates a new virtual Code Set or Code Graph which represents the Boolean union of the two selected items. All restrictions applied to the individual items still apply.

...

• Intersection - This button is enabled if two Code Sets or two Code Graphs are selected in the lower left. Clicking the button creates a new virtual Code Set or Code Graph which represents the Boolean intersection of the two selected items. All restrictions applied to the individual items still apply.

...

• Difference - This button is enabled if two Code Sets or two Code Graphs are selected in the lower left. Clicking the button creates a new virtual Code Set which represents the Boolean difference of the two selected Code Sets. All restrictions applied to the individual items still apply.

...

• Restrict to Codes - This button is enabled if a Code Set and a Code Graph are selected in the lower left. Clicking the button creates a new virtual Code Graph which will be restricted to concept codes occurring in the selected Code Set.

...

• Restrict to Source Codes - This button is enabled if a Code Set and a Code Graph are selected in the lower left. Clicking the button creates a new virtual Code Graph which will have its source codes restricted to codes occurring in the selected Code Set.

...

• Restrict to Target Codes - This button is enabled if a Code Set and a Code Graph are selected in the lower left. Clicking the button creates a new virtual Code Graph which will have its target codes restricted to codes occurring in the selected Code Set.

...

• Remove - This button is enabled if any Code Set or Code Graph (or virtual Code Set or Code Graph) is selected in the lower left. Clicking the button will remove the selected item from the list.

The lower right section of the GUI is used to apply restrictions to Code Sets or Code Graphs, and set the variables that need to be passed into the resolve method.

Working with Code Sets

If a Code Set is selected in the lower left, then the lower right section will look like this:

Image Modified

In the lower right section, there are two halves - the top half and the bottom half. The top half is used to apply restrictions. The bottom half provides query options and resolution. *

• Add - This button introduces a new restriction to the Coded Node Set. Clicking it will bring up the following dialog box for creating restrictions:
  

...

• Image Modified
  The top drop down list indicates the type of restriction to add. The rest of the dialog box will change depending on the type of restriction selected. All required parameters for the selected restriction type will be presented.

...

• Edit - This button is enabled when a restriction is selected. Clicking it allows revision of an existing restriction.

...

• Remove -This button is enabled when a restriction is selected. Clicking it removes the selected restriction.

...

• Only Include Active Codes - This check box indicates whether or not to include inactive codes when resolving the selected code set.

...

• Set Sort Options - This button will bring up a dialog box to choose the desired sort order of the results.

...

• Resolve Code Set - This button will bring up a result window where the Code Set will be resolved and displayed.

Working with Code Graphs

If you select a Coded Node Graph in the lower left section of the LexEVS GUI, the lower right section will look like thisthe following figure, which is described in the text after the graphic:

Image Modified

Again, there are two halves to the lower right section. The top half allows restrictions to be applied to the selected Code Graph, and it works the same as it does for a Coded Node Set. Please see the section above on applying restrictions to a Coded Node Set.

The lower half provides additional variables applicable when resolving a Coded Node Graph. For further explanation of these options, refer to the LexEVS API documentation. *

• Relation Container (Optional) - Indicates the CodingScheme Relations container to query. The drop down list is populated with allowable selections.

...

• Focus Code (Optional) - Provides the code used as a starting point when resolving graph relations. This value is required for some queries, depending on the nature of requested associations.

...

• Focus Code System (Optional) - Indicates the code system containing the Focus Code. The drop down list is populated with allowable selections.

...

• Max Resolve Depth - How many levels deep should the graph be resolved? -1 is the default, which does not limit the depth.

...

• Resolve Forward - Populate codes downstream from the focus node (based on directionality defined by each association).

...

• Resolve Backward - Populate codes upstream from the focus node (based on directionality defined by each association).

...

• Set Sort Options - This button will bring up a dialog box to choose the desired sort order of the results.

...

• Resolve As Set - Resolves and displays the graph results as a coded node set.

...

• Resolve As Graph -Resolves and displays the graph results.

Viewing Query Results

Clicking on the Resolve buttons for either a Coded Node Set or a Coded Node Graph will bring up the Result Browser window:

Image Modified

The left side shows a list of all the concept codes returned. When a concept code is selected on the left, the upper right will show a full description of the selected code. The lower right will show a graph view of the neighboring concepts.

When a Coded Node Graph is resolved, the result viewing window will look like this (this is the same Code System as above):

Image Modified

The left side still has a list of all of the concepts in the graph. The upper right will give a description of the selected concept. The lower right shows the entire graph.

The lower right section is adjustable, and dynamic. It responds to mouse clicks, dragging, and numerous key combinations. Beyond a depth of 3, the graph may "collapse" and not show all of the nodes until you click on a node. Clicking on a node will cause it to expand out and display its children. Here are a list of key combinations recognized by the graph viewer:

• <span style="font-variant: small-caps;"> Left Click + Mouse Movement</span> Movement - Drags the view.<span style="font
• -variant: small-caps;"> Right Click + Mouse Movement Up Or Down</span> - Zooms in or out.Down - Zooms in or out.
• Right <span style="font-variant: small-caps;">Right Click (on white space) </span> - Zooms the view to fit.
• <span style="font-variant: small-caps;">Ctrl Ctrl + '+' </span> - Expands the graph connection lines<span style="font-variant: small-caps;">Ctrl
• Ctrl + '-' </span> - Contracts the graph connection lines
• <span style="font-variant: small-caps;">Ctrl Ctrl + '1' (or '2' or '3' or '4') </span> - Changes the orientation of the graph.

LexEVS caCORE Data Services API

Interacting with caCORE LexEVS

This chapter describes the components of the caCORE LexEVS and the service interface layer provided by the EVS API architecture. It gives examples of how to use the EVS APIs. It also describes the Distributed LexEVS API and the Distributed LexEVS APIAdapter.

caCORE LexEVS Components

The caCORE LexEVS API is a public domain, open source wrapper that provides full access to the LexEVS Terminology Server. LexEVS hosts the NCI Thesaurus, the NCI Metathesaurus, and several other vocabularies. Java clients accessing the NCI Thesaurus and Metathesaurus vocabularies communicate their requests via the open source caCORE LexEVS APIs, as shown in Overview of the caCORE LexEVS 4.0 release componentsthe following figure.

Image ModifiedFigure 4.1 - Overview of the caCORE LexEVS 4.0 release components

The open source interfaces provided as part of caCORE LexEVS 5.x include Java APIs, a SOAP interface, and an HTTP REST interface. The Java APIs are based on the EVS 3.2 object model and the LexEVS Service object model.

...

The only difference between the EVS 3.2 API exposed as part of the caCORE LexEVS 5.x and the API exposed as part of caCORE 3.2 is the back-end terminology server used to retrieve the vocabulary data. The interface (API calls) are the same and should only require minor adjustments to user applications.

...

...

The LexEVS object model was developed by the Mayo Clinic. In its native form, the associated API assumes a local, non-distributed means of access. With caCORE LexEVS 5.x, a proxy layer enables EVS API clients to access the native LexEVS API from anywhere without having to worry about the underlying data sources. This is called the Distributed LexEVS (DLB) API.

The DLB Adapter is another option for caCORE LexEVS 5.x clients who choose to interface directly with the LexEVS API. This is essentially a set of convenience methods intended to simplify the use of the LexEVS API. For example, a series of method calls against the DLB API might equate to a single method call to the DLB Adapter.

...

LexEVS Data Sources

The LexEVS data source is the open source LexEVS terminology server. EVS clients interface with the LexEVS API to retrieve desired vocabulary data. The EVS provides the NCI with services and resources for controlled biomedical vocabularies, including the NCI Thesaurus and the NCI Metathesaurus.

NCI Thesaurus

The NCI Thesaurus is composed of over 27,000 concepts represented by about 78,000 terms. The Thesaurus is organized into 18 hierarchical trees covering areas such as Neoplasms, Drugs, Anatomy, Genes, Proteins, and Techniques. These terms are deployed by the NCI in its automated systems for uses such as key wording and database coding.

NCI Metathesaurus

The NCI Metathesaurus maps terms from one standard vocabulary to another, facilitating collaboration, data sharing, and data pooling for clinical trials and scientific databases. The Metathesaurus is based on the Unified Medical Language System (UMLS) developed by the National Library of Medicine (NLM). It is composed of over 70 biomedical vocabularies.

Interfaces

Main interfaces included in the LexEVSAPI package.

LexEVSDistributed

The Distributed LexEVS Portion of LexEVSAPI. This interface is a framework for calling LexEVS API methods remotely, along with enforcing security measures. JavaDoc

LexEVSDataService

The caCORE-SDK Data Service Portion of LexEVSAPI. This extends on the caCORE ApplicationService to provide additional Query Options. JavaDoc

LexEVSService

The Main LexEVSAPI Interface. This includes support for caCORE-SDK Data Service calls as well as remote LexBIG API calls. JavaDoc

Search Paradigm

The caCORE LexEVS architecture includes a service layer that provides a single, common access paradigm to clients that use any of the provided interfaces. As an object-oriented middleware layer designed for flexible data access, caCORE LexEVS relies heavily on strongly typed objects and an object-in/object-out mechanism.

...

caCORE LexEVS systems use four native application programming interfaces (APIs). Each interface uses the same paradigm to provide access to the caCORE LexEVS domain model, with minor changes specific to the syntax and structure of the clients. The following sections describe each API, identify installation and configuration requirements, and provide code examples.

The sequence diagram in Sequence diagram - caCORE 4.0 LexEVS API search mechanism The sequence diagram that follows illustrates the caCORE LexEVS API search mechanism implemented to access the NCI EVS vocabularies.

Image ModifiedFigure 4.4 - Sequence diagram - caCORE 4.0 LexEVS API search mechanism

Querying the System

LexEVS conforms to the caCORE SDK API - for more information see caCORE SDK 4.1 Programmer's Guide

QueryOptions

QueryOptions are designed to give the user extra control over the query before it is sent to the system. QueryOptions may be used to modify a query in these ways:

1. 'CodingScheme' - Restricts the query to the specified Coding Scheme, instead of querying every available Coding Scheme.
2. CodingSchemeVersionOrTag' - Restricts the query to the specified Version of the Coding Scheme. Note that:
   a.
   • This may NOT be specified without also specifying the 'CodingScheme' attribute.
   b.
   • If left unset, it will default to the version of the Coding Scheme tagged as "PRODUCTION" in the system.
   • 'SecurityTokens' - Security Tokens to use with the specified query. These Security Tokens are scoped to the current query ONLY. An subsequent queries will also need to specify the necessary Query Options.
   • #'LazyLoad' - Some high use-case model Objects have bee 'lazy-load' enabled. This means that some attributes and associations of a model Object may not be fully populated when returned to the user. This allows for faster query times. This defaults to false, meaning that all attributes and associations will be eagerly fetched by the server and model Objects will always be fully populated. To enable this on applicable Objects, set to true.
     NOTE:

     Info
     title Note
     Lazy Loading may only be used in conjunction with specifying a Coding Scheme and Version with the 'CodingScheme' and 'CodingSchemeVersionOrTag' attributes above.

   • 'ResultPageSize' - the page size of results to return. The higher the number, the more results the system will return to the user at once. The client will request the next group of query results transparenly. This parameter is useful for performance tuning. For example, if a query returns a result of10,000 Objects, a 'ResultPageSize' of '1000' would make 10 calls to the server returning a page of 1000 results each time. If left unset, this value will default to the default set Page Size

Examples of Use

*Example 4.1: Query By Example with No Query Options *

...

Explanation of statements in The following table explains specific statements in the code by line number.

...

...

_Table 4.6 - Explanation of statements in : _

*Example 4.2: Query By Example with Query Options*

...

Explanation of statements in The following table explains specific statements in the code by line number.

...

...

_Table 4.7 - Explanation of statements in : _

Web Services API

The caCORE LexEVS Web Services API enables access to caCORE LexEVS data and vocabulary data from development environments where the Java API cannot be used, or where use of XML Web services is more desirable. This includes non-Java platforms and languages such as Perl, C/C++, .NET framework (C#, VB.Net), and Python.

...

On the server side, Apache Axis is used to provide SOAP-based, inter-application communication. Axis provides the appropriate serialization and deserialization methods for the JavaBeans to achieve an application-independent interface. For more information about Axis, visit http://ws.apache.org/axis/.

Configuration

The caCORE/LexEVS WSDL file is located at http://lexevsapi.nci.nih.gov/lexevsapi50/services/lexevsapi50Service?wsdl. In addition to describing the protocols, ports, and operations exposed by the caCORE LexEVS Web service, this file can be used by a number of IDEs and tools to generate stubs for caCORE LexEVS objects. This enables code on different platforms to instantiate native objects for use as parameters and return values for the Web service methods. For more information on how to use the WSDL file to generate class stubs, consult the specific documentation for your platform.

The caCORE LexEVS Web services interface has a single end point called <tt>lexevsapi50Service</tt>, which is located at http://lexevsapi.nci.nih.gov/lexevsapi50/services/lexevsapi50Service. Client applications should use this URL to invoke Web service methods.

Building a Java SOAP Client

LexEVSAPI provides a tool to create a Java SOAP client capable of connecting to a LexEVSAPI SOAP service.

...

To build the client, use the command 'ant all' from the ./webServiceSoapClient directory.

XML-HTTP API

The caCORE LexEVS XML-HTTP API, based on the REST (Representational State Transfer) architectural style, provides a simple interface using the HTTP protocol. In addition to its ability to be invoked from most Internet browsers, developers can use this interface to build applications that do not require any programming overhead other than an HTTP client. This is particularly useful for developing Web applications using AJAX (Asynchronous JavaScript and XML).

Service Location and Syntax

The CORE EVS XML-HTTP interface uses the following URL syntax:

http://{server}/{servlet}?query={returnClass}&{criteria}
	&startIndex={index}
	&codingSchemeName={codingSchemeName}
	&codingSchemeVersion={codingSchemeVersion}

Table 4.12 The following table explains the syntax, indicates whether specific elements are required, and gives examples.

...