Code Snippets
Supply the OWL manifest file URI
LexBIGService lbs = new LexBIGServiceImpl();
LexBIGServiceManager lbsm = lbs.getServiceManager(null);
OWL_Loader loader = (OWL_Loader) lbsm.getLoader("OWLLoader");
if (toValidateOnly)
{
loader.validate(source, manifest, vl);
System.out.println("VALIDATION SUCCESSFUL");
}
else
{
loader.load(new File("resources/testData/amino-acid.owl").toURI(),
new File("resources/testData/aa-manifest.xml").toURI(),true,true);
}
Supply the non-OWL manifest file URI
// Find the registered extension handling this type of load
LexBIGService lbs = new LexBIGServiceImpl();
LexBIGServiceManager lbsm = lbs.getServiceManager(null);
HL7_Loader loader = (HL7_Loader)lbsm.getLoader (org.LexGrid.LexBIG.Impl.loaders .HL7LoaderImpl.name);
// updated to include manifest
loader.setCodingSchemeManifestURI(manifest);
// updated to include loader preferences
loader.setLoaderPreferences(loaderPrefs);
loader.load(dbPath, stopOnErrors, true);
Find the immediate relations of a Concept
CodedNodeGraph cng = lexevsService.
getNodeGraph(codingScheme, versionOrTag, relationContainerName);
ResolvedConceptReference[] rcr = cng.resolveAsList(graphFocus, resolveForward,
resolveBackward, resolveCodedEntryDepth, resolveAssociationDepth,
propertyNames, propertyTypes, sortOptions, maxToReturn).
getResolvedConceptReference();
Find the a given code, for example, code 'C1234' in the 'NCI Thesaurus' ontology
//first obtain a 'CodedNodeSet' from the 'NCI Thesaurus' ontology:
ResolvedConceptReferenceList cns = lbSvc.getCodingSchemeConcepts("NCI Thesaurus", null);
//Next, restrict that to the desired Code ('C1234' in this example):
ConceptReferenceList crefs = ConvenienceMethods.
createConceptReferenceList(new String[]{"C1234"}, "NCI Thesaurus");
cns.restrictToCodes(crefs);
//Lastly, resolve the match.
ResolvedConceptReferenceList matches = cns.resolveToList(null, null, null, 1);
Concept Resolution
Programmers access coded concepts by acquiring first a node set or graph. After specifying optional restrictions, the nodes in this set or graph can be resolved as a list of ConceptReference objects which in turn contain references to one or more Concept objects. The following example provides a simple query of concept codes:
// Create a basic service object for data retrieval
LexBIGService lbSvc = new LexBIGServiceImpl();
// Create a concept reference list appropriate for this coding scheme and
// this concept code where the parameters are a String array consisting of
// a single value and the name of the coding scheme where this concept resides.
ConceptReferenceList crefs = ConvenienceMethods.createConceptReferenceList(
new String[] {code },SAMPLE_SCHEME);
// Initialize a coding scheme version object with a version number for the
// sample scheme.
CodingSchemeVersionOrTag csvt = new CodingSchemeVersionOrTag();
csvt.setVersion(VERSION);
// Initialize a CodedNodeSet Object with all concepts in our sample coding
// scheme. (We named the scheme we wanted and by using the Boolean value,
// false, retrieved both active and inactive concepts.) This method call
// ignores the version tag using the null parameter. The final
// restrictToCodes(crefs) method call restricts the return to the single
// code in the previously initialized list of one.
CodedNodeSet nodes = lbSvc.getCodingSchemeConcepts(SAMPLE_SCHEME, csvt).
restrictToCodes(crefs);
// Build a list of references from the current (and already restricted) set
// and restrict them further to the single property of NCI_NAME and
// restrict to a single answer (parameter 1)).
ResolvedConceptReferenceList matches = nodes.resolveToList(
null, ConvenienceMethods.createLocalNameList("FULL_SYN"), 1);
// Does our list of one contain the single reference we were looking for?
// If so, then initialize a ResolvedConceptReference with the result and
// initialize a Concept object by calling the getReferencedEntry()
// method. The Concept object is the base information model object and
// contains, among other things, the CONCEPT_NAME value we were seeking.
// We retrieve it with a call to the first element in the properties list,
// getting the text && it's accompanying content.
if(matches.getResolvedConceptReferenceCount() <> 0)
{ ResolvedConceptReference ref = (ResolvedConceptReference)matches.enumerateResolvedConceptReference().nextElement();
Concept entry = ref.getReferencedEntry();
System.out.println("Matching synonym: " +entry.getPresentation(0).getValue() ); }
else
{ System.out.println("No match found"); }
Service Metadata Retrieval
The LexEVS system maintains service metadata which can provide client programs with information about code system content and assigned copyright/licensing information. Below is an brief example showing how to access and print some of this metadata:
// We can get a CodingSchemeRenderingList object directly from LexBigService
LexBIGService lbs = LexBIGServiceImpl.defaultInstance();
CodingSchemeRenderingList schemeList = lbs.getSupportedCodingSchemes();
for (CodingSchemeRendering csr : schemeList.getCodingSchemeRendering())
{
CodingSchemeSummary css = csr.getCodingSchemeSummary();
// Print separator then details from the CodingSchemeSummary
System.out.println("==========================");
System.out.println(ObjectToString.toString(css));
// Set up a coding scheme reference to resolve Copyright
String urn = css.getCodingSchemeURI();
String version = css.getRepresentsVersion();
CodingSchemeVersionOrTag csVorT =
Constructors.createCodingSchemeVersionOrTagFromVersion(version);
CodingScheme cs = lbs.resolveCodingScheme(urn, csVorT);
System.out.println("Copyright: " +cs.getCopyright().getContent());
// Get the final details from the RenderingDetail
RenderingDetail rd = csr.getRenderingDetail();
System.out.println(ObjectToString.toString(rd));
System.out.println();
}
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:
System.out.println("Example double restriction query with additional "
+"application of sort criteria and restricted return values.");
// Declare the service...
LexBIGServiceImpl lbs = LexBIGServiceImpl.defaultInstance();
// Start with an unconstrained set of all codes for the vocabulary
CodingSchemeVersionOrTag csvt = new CodingSchemeVersionOrTag();
csvt.setVersion(VERSION2);
CodedNodeSet cns = lbs.getCodingSchemeConcepts(SAMPLE_SCHEME2, csvt);
// Constrain to concepts with designations (assigned text presentations
// that contain text that sounds like 'Short Saphenous Vein'
cns = cns.restrictToMatchingDesignations(
"Short Safinus Vane",
SearchDesignationOption.ALL,
MatchAlgorithms.DoubleMetaphoneLuceneQuery.toString(),
null);
// Further restrict the results to concepts with a semantic type of
// 'Anatomical Structure'
cns = cns.restrictToMatchingProperties(
Constructors.createLocalNameList("Semantic_Type"),
null, "Anatomical Structure",
"exactMatch",
null);
// Indicate that the resulting list should be sorted with the best
// results first and then sorted by code if there is a tie.
SortOptionList sortCriteria = Constructors.createSortOptionList(
new String[] {"matchToQuery", "code"});
// Indicate to return only the assigned UMLS_CUI and
// textualPresentation properties.
LocalNameList restrictTo =ConvenienceMethods.createLocalNameList(
new String[] {"UMLS_CUI", "textualPresentation"} );
// Still nothing computed yet.
// Perform the query && resolve the sorted/filtered list with a
// maximum of 6 items returned.
ResolvedConceptReferenceList list = cns.resolveToList(
sortCriteria, restrictTo, null, 6);
// Print the results
ResolvedConceptReference[] rcr = list.getResolvedConceptReference();
for (ResolvedConceptReference rc : rcr)
{
System.out.println("Resolved Concept: " + rc.getConceptCode());
}
Coded Node Graph Restriction
cng.restrictToCodeSystem(org.LexGrid.LexBIG.DataModel.cagrid.CodingSchemeIdentification);
Resolved Concept References Iterator
while(itr.hasNext){
ResolvedConceptReference ref = itr.next();
}
Request Filter Match
filter.match(resolvedConceptReference);
Request Filter
Filter filter = lbs.getFilter(org.LexGrid.LexBIG.DataModel.cagrid.ExtensionIdentification);
Request Sort Compare
sort.compare(codedNodeReference1, codedNodeReference2);
Request Sort
Sort sort = lbs.getSortAlgorithm(org.LexGrid.LexBIG.DataModel.cagrid.ExtensionIdentification);
Concept Resolution
// Create a basic service object for data retrieval
LexBIGService lbSvc = LexBIGServiceImpl.defaultInstance();
// Create a concept reference list appropriate for this coding scheme and
// this concept code where the parameters are a String array consisting of
// a single value and the name of the coding scheme where this concept resides.
ConceptReferenceList crefs = ConvenienceMethods.createConceptReferenceList(
new String[], SAMPLE_SCHEME);
// Initialize a coding scheme version object with a version number for the
// sample scheme.
CodingSchemeVersionOrTag csvt = new CodingSchemeVersionOrTag();
csvt.setVersion(VERSION);
// Initialize a CodedNodeSet Object with all concepts in our sample coding
// scheme. (We named the scheme we wanted and by using the Boolean value,
// false, retrieved both active and inactive concepts.) This method call
// ignores the version tag using the null parameter. The final
// restrictToCodes(crefs) method call restricts the return to the single
// code in the previously initialized list of one.
CodedNodeSet nodes = lbSvc.getCodingSchemeConcepts(SAMPLE_SCHEME, csvt).
restrictToCodes(crefs);
// Build a list of references from the current (and already restricted) set
// and restrict them further to the single property of NCI_NAME and
// restrict to a single answer (parameter 1)).
ResolvedConceptReferenceList matches = nodes.resolveToList(
null, ConvenienceMethods.createLocalNameList("FULL_SYN"), 1);
// Does our list of one contain the single reference we were looking for?
// If so, then initialize a ResolvedConceptReference with the result and
// initialize a Concept object by calling the getReferencedEntry()
// method. The Concept object is the base information model object and
// contains, among other things, the CONCEPT_NAME value we were seeking.
// We retrieve it with a call to the first element in the properties list,
// getting the text && it's accompanying content.
if(matches.getResolvedConceptReferenceCount() <> 0)
{ ResolvedConceptReference ref = (ResolvedConceptReference)matches.
enumerateResolvedConceptReference().nextElement();
Concept entry = ref.getReferencedEntry();
System.out.println("Matching synonym: " +
entry.getPresentation(0).getValue() ); }
else
{ System.out.println("No match found"); }
Code Files
BuildTreeForCode
Attempts to provide a tree, based on a focus code, that includes the following information:
- All paths from the hierarchy root to one or more focus codes.
- Immediate children of every node in path to root
- Indicator to show whether any unexpanded node can be further expanded
This example accepts two parameters... The first parameter is required, and must contain at least one code in a comma-delimited list. A tree is produced for each code. Time to produce the tree for each code is printed in milliseconds. In order to factor out costs of startup and shutdown, resolving multiple codes may offer a better overall estimate performance.
The second parameter is optional, and can indicate a hierarchy ID to navigate when resolving child nodes. If not provided, "is a" is assumed.
CodingSchemeSelectionMenu
Displays a list of available coding schemes.
FindCodesForDescription
Example showing how to find codes matching descriptive text. The program accepts up to two parameters...
The first param (required) indicates the text used to search matching descriptions. Matches are determined through a customized match algorithm, which uses a simple heuristic to try and rank returned values by relevance.
The second param (optional) indicates the type of entity to search. Possible values include the LexGrid built-in types "concept" and "instance". Additional supported types can be defined uniquely to a coding scheme. If provided, this should be a comma-delimited list of types. If not provided, all entity types are searched.
Example: FindCodesForDescription "blood" Example: FindCodesForDescription "breast cancer" "concept"
FindDescriptionForCode
Example showing how to find the entity description assigned to a specific code. The program accepts one parameter, the entity code.
FindPropsAndAssocForCode
Example showing how to find concept properties and associations based on a code.
FindRelatedCodes
Example showing how to find all concepts codes related to another code with distance 1.
FindRelatedCodesWithPropertyLinks
Example showing how to find all concepts codes related to another code with distance 1, plus the Property Link relations.
FindRelatedNodesForTermAndAssoc
Example showing how to find all endpoints of a named association for which the given term matches as source or target.
Note: the match algorithm applied to the term is the standard lucene query syntax.
FindUMLSContextsForCUI
Example showing any source-asserted hierarchies (based on import of MRHIER HCD) for a CUI. The program takes a single argument (the UMLS CUI), prompts for the code system to query in the LexGrid repository, and displays the available hierarchical relationships.
ListHierarchy
Example showing how to determine and display an unsorted list of root and subsumed nodes, up to a specified depth, for hierarchical relationships.
This program accepts two parameters:
The first parameter indicates the depth to display for the hierarchy. If 1, nodes immediately subsumed by the root are displayed. If 2, grandchildren are displayed, etc. If absent or < 0, a default depth of 3 is assumed.
The second parameter optionally indicates a specific hierarchy to navigate. If provided, this must match a registered identifier in the coding scheme supported hierarchy metadata. If left unspecified, all hierarchical associations are navigated. If an incorrect value is specified, a list of supported values will be output for future reference.
BACKGROUND: From a database perspective, LexBIG stores relationships internally in a forward direction, source to target. Due to differences in source formats, however, a wide variety of associations may be used ('PAR', 'CHD', 'isa', 'hasSubtype', etc). In addition, the direction of navigation may vary ('isa' expands in a reverse direction whereas 'hasSubtype' expands in a forward direction.
The intent of the getHierarchy* methods on the LexBIGServiceConvenienceMethods interface is to simplify the process of hierarchy discovery and navigation. These methods significantly reduce the need to understand conventions for root nodes, associations, and direction of navigation for a specific source format.
ListHierarchyByCode
Example showing how to determine and display the hierarchical relationships for a specific code, ancestors or descendants, within a fixed distance.
This program accepts two parameters, indicating the code and distance. The first parameter is the code (required). The second parameter is the distance (optional). If 1, immediate children are displayed. If 2, grandchildren are displayed, etc. If absent or < 0, all downstream branches are displayed.
BACKGROUND: From a database perspective, LexBIG stores relationships internally in a forward direction, source to target. Due to differences in source formats, however, a wide variety of associations may be used ('PAR', 'CHD', 'isa', 'hasSubtype', etc). In addition, the direction of navigation may vary ('isa' expands in a reverse direction whereas 'hasSubtype' expands in a forward direction.
The intent of the getHierarchy* methods on the LexBIGServiceConvenienceMethods interface is to simplify the process of hierarchy discovery and navigation. These methods significantly reduce the need to understand conventions for root nodes, associations, and direction of navigation for a specific source format.
ListHierarchyMetaBySource
Example showing how to determine and display an unsorted list of root and subsumed nodes, up to a specified depth, for hierarchical relationships. It is written specifically to handle display of relationships for a designated source within the NCI Metathesaurus.
This program accepts two parameters. The first indicates the depth to display hierarchical relations. If 0, only the root nodes are displayed. If 1, nodes immediately subsumed by the root are also displayed, etc. If < 0, a default depth of 0 is assumed.
The second parameter must provide the source abbreviation (SAB) of the Metathesaurus source to be evaluated (e.g. ICD9CM, MDR, SNOMEDCT).
ListHierarchyPathToRoot
Example showing how to determine and display paths from a given concept back to defined root nodes through any hierarchies registered for the coding scheme.
This program accepts one parameter (required), indicating the code to evaluate.
BACKGROUND: From a database perspective, LexBIG stores relationships internally in a forward direction, source to target. Due to differences in source formats, however, a wide variety of associations may be used ('PAR', 'CHD', 'isa', 'hasSubtype', etc). In addition, the direction of navigation may vary ('isa' expands in a reverse direction whereas 'hasSubtype' expands in a forward direction.
The intent of the getHierarchy* methods on the LexBIGServiceConvenienceMethods interface is to simplify the process of hierarchy discovery and navigation. These methods significantly reduce the need to understand conventions for root nodes, associations, and direction of navigation for a specific source format.
MetaDataSearch
Example how to query stored metadata for a code system. For the example, use the LoadSampleMetaDataData.bat to load the required code system and metadata.
MetaMatch
Example attempting to approximate some characteristics of the Metaphrase search algorithm. However, full Metaphrase compatibility is not anticipated.
ProfileScheme
Requires loading valid scheme (must have root node named @ pointing to top nodes) Profiles a coding scheme based on unique URN, version, relation and scheme name.
Note: If the URN and version values are unspecified, a list of available coding schemes will be presented for user selection.
ScoredIterator
Used to wrap scored results for consumption as a standard ResolvedConceptReferenceIterator.
ScoredTerm
Used to manage and sort search results based on a scoring algorithm.
ScoreTerm
Example showing a simple scoring algorithm that evaluates a provided term against available terms in a code system. A cutoff percentage can optionally be provided.
SoundsLike
Example showing how to list concepts with presentation text that 'sounds like' a specified value.
Util
Utility functions to support the examples.
