1. LexEVS 5.0 EVS to LexEVS: A Migration Guide November, 2009

2. Session Details: Migration Guide Course Outline Course Learning Objectives Understand the differences between the new LexEVS 5.0 architecture and previous version of LexEVS (4.2) and EVS 3.x Learn how to change EVS code to LexEVS code via the highlights of our migration guide’s method to method comparison between EVS and LexEVS. Gain detailed knowledge of sample EVS to LexEVS migration by examining some example code Master sample migration examples by doing some exercises in converting EVS code to LexEVS API calls.

3. Session Details: Migration Guide Lesson Syllabus Lesson 1: Overview Lesson 2: Method Comparisons Lesson 3: Migration Exercises

4. Lesson 1: Overview When you complete this lesson you will be able to: Understand the overall architecture changes in in the latest LexGrid and EVS versions Understand the latest naming conventions. See which API’s are replaced and what they are replaced by. Discuss the newly defined definitions of API’s and models. Give an account of what kinds of services are no longer available from EVS.

5. Lesson 1: Overview Release 4.2 vs. 5.0 This slide shows how the new 5.0 release of LexEVS removes the need for the adaptor layer and shows how the LexEVS caCORE services access the LexGrid database directly, where previously the caCORE services had to negotiate three layers of code.

6. Lesson 1: Overview Release Components The convergence of LexEVS 5.0 components has introduced new naming of components: The table on this slide displays the convergence of LexEVS 5.0 components and consequent new naming of components: Design ComponentsRelease 4.2Release 5.0 EVS Model Version3.2No Longer Available EVS API Version3.2No Longer Available LexGrid Model Version2008/012009/01LexBIG API LexBIG API Version2.3.0LexEVS 5.0 Design ComponentsRelease 4.2Release 5.0 EVS Model Version3.2No Longer Available EVS API Version3.2No Longer Available LexGrid Model Version2008/012009/01LexBIG API LexBIG API Version2.3.0LexEVS 5.0

7. Lesson 1: Overview Release Programming Interfaces The supported programming interfaces are now all provided by LexEVS: The table on this slide shows how the supported programming interfaces are now all provided by LexEVS. Supported Programming Interfaces Release 4.2Release 5.0 Direct Java LexBIG LexEVS Distributed Java (RMI) LexBIG LexEVS caCORE SDK Services EVSLexEVS caGRID Service EVS, LexEVSLexEVS Supported ProgrammingInterfaces Release 4.2Release 5.0 Direct JavaLexBIGLexEVS Distributed Java (RMI)LexBIGLexEVS caCORE SDK ServicesEVSLexEVS caGRID ServiceEVS, LexEVSLexEVS

8. Lesson 1: Overview Definitions As a result, definitions have been unified to represent LexEVS. The following definitions are provided for reference In this slide we show how definitions have been unified in a table format: LexGrid LexGrid Vocabulary model underlying the LexBIG API. Sometimes used as a generic reference to work based off this model. LexBIG A new API with rich functionality developed for NCI caBIG® to access LexGrid- based vocabularies. Serves as the internal ‘engine’ for traditional EVS APIs. EVS NCI Enterprise Vocabulary Services model, API, and content. For model and API, references legacy components being replaced by LexGrid (model) and LexBIG (API) LexEVS Adopted as project name to describe merging of LexGrid model and LexBIG API as the mainstream EVS interfaces TermDefinition LexGrid LexGrid Vocabulary model underlying the LexBIG API. Sometimes used as a generic reference to work based off this model. LexBIG A new API with rich functionality developed for NCI caBIG® to access LexGrid-based vocabularies. Serves as the internal ‘engine’ for traditional EVS APIs. EVS NCI Enterprise Vocabulary Services model, API, and content. For model and API, references legacy components being replaced by LexGrid (model) and LexBIG (API) LexEVS Adopted as project name to describe merging of LexGrid model and LexBIG API as the mainstream EVS interfaces

9. Lesson 1: Overview Query By Example Services LexGrid-based QBE services LexEVS 5.0 brings the addition of QBE/Data Services. Detailed information about the Data Services can be found in the LexEVS 5.0 Programmer's Guide.LexEVS 5.0 Programmer's Guide

10. Lesson 1: Overview Class changes EVS API to LexEVS API Migration The transition from EVS API to LexEVS API will require the use of different methods to accomplish the same function as was previously provided in EVS API. This section will identify each deprecated class and provide the alternative LexEVS API. As a result of the deprecation of the EVS API, the following classes are no longer available: EVSQuery and EVSQueryImpl EVSQueryDAOImpl - Not a public API. EVSWSDAOImpl - Not a public API. EVSWSQuery - Not a public API. DLBAdapter - Not a public API. DLBWrapper (DLBWrapper is extended by DLBAdapter and it is not been used anywhere else) - Not a public API. EVSApplicationService and EVSApplicationServiceImpl

11. Lesson 1: Overview Class changes As a result of the deprecation of the EVS API, the following classes are no longer available: EVSApplicationService and LexEVS Counterparts EVSApplicationService evsSearch and search These methods are replaced either by the LexEVS API or the LexEVS caCORE SDK Data Service 'search' method. This uses the standard caCORE SDK API. More information about the caCORE SDK can be obtained on the caCORE SDK site.caCORE SDK site EVSQuery Methods and LexEVS Counterparts EVSQuery

12. Lesson 1: Overview Review 1  Describe the major difference in the new architecture implemented with LexEVS.

13. Lesson 1: Overview Answer 1  Describe the major difference in the new architecture implemented with LexEVS Legacy caCORE API’s and a layer of adaptor code have been removed.

14. Lesson 1: Overview Review 2  How have the EVS naming conventions changed?

15. Lesson 1: Overview Answer 2  How have the EVS naming conventions changed? EVS and LexBIG now combined to be called LexEVS.

16. Lesson 1: Overview Review 3  What API’s have been replaced? – and by what.

17. Lesson 1: Overview Answer 3  What API’s have been replaced? – and by what. EVS, LexBIG and caGrid services are all replaced by LexEVS

18. Lesson 1: Overview Review 4  Discuss the newly defined API’s and models.

19. Lesson 1: Overview Answer 4  Discuss the newly defined API’s and models. LexGrid – the data model for LexEVS LexBIG – the engine and underlying middle ware for EVS EVS – NCI Vocabulary and services LexEVS – describes the combined LexGrid and LexBIG.

20. Lesson 1: Overview Review 5  Name a few EVS services that no longer exist.

21. Lesson 1: Overview Answer 5  Name a few EVS services that no longer exist. EVSQuery, EVSApplicationService, EVSSearch.

22. Lesson 2: Method Comparisons When you complete this lesson you will be able to: Use LexEVS API calls to replace EVS calls for description logic concepts. Replace EVS method calls retrieving wholes trees and well as parent and child concepts with LexEVS coded node graph calls Use the more generic LexEVS calls to retrieve concepts from the NCI MetaThesaurus. Understand where to look for more possible migration solutions.

23. Lesson 2: Method Comparisons getTree getTree all 'getTree' functionality is replaced by the LexEVS CodedNodeGraph API. For example: public void getTree(String vocabularyName, String rootCode, boolean direction, boolean isaFlag, int attributes, int levels, Vector roles); is replaced by: CodedNodeGraph cng = lexevsService.getNodeGraph(String codingScheme, CodingSchemeVersionOrTag, versionOrTag, String relationContainerName); ResolvedConceptReference[] rcr = cng.resolveAsList(ConceptReference graphFocus, boolean resolveForward, boolean resolveBackward, int resolveCodedEntryDepth, int resolveAssociationDepth, LocalNameList propertyNames, PropertyType[] propertyTypes, SortOptionList sortOptions, int maxToReturn).getResolvedConceptReference();

24. Lesson 2: Method Comparisons getTree getTree: Also, various methods in LexBIGServiceConvenienceMethods can be used to show hierarchies. See methods getHierarchyRoots getHierarchyRootSet getHierarchyLevelNext getHierarchyLevelPrev getHierarchyPathToRoot For examples, see the LexEVS Example classes org.LexGrid.LexBIG.example.BuildTreeForCode org.LexGrid.LexBIG.example.ListHierarchy org.LexGrid.LexBIG.example.ListHierarchyByCode org.LexGrid.LexBIG.example.ListHierarchyPathToRoot

25. Lesson 2: Method Comparisons searchDescLogicConcepts searchDescLogicConcepts LexEVS provides many ways to restrict the result of a query. The method 'searchDescLogicConcepts' searches for matches based on a text String. To conduct similar queries using LexEVS, use the CodedNodeSet API. Obtain a CodedNodeSet from LexEVS: CodedNodeSet nodes = lexevsService.getNodeSet(String codingScheme, CodingSchemeVersionOrTag versionOrTag, LocalNameList entityTypes); Once established, the CodedNodeSet can be further restricted using the various 'restrict' methods in the CodedNodeSet API. For examples, see the LexEVS Example classes org.LexGrid.LexBIG.example.SoundsLike org.LexGrid.LexBIG.example.FindCodesForDescription

26. Lesson 2: Method Comparisons getConceptWithPropertyMatching getConceptWithPropertyMatching For Property-specific matching, see the following method in the CodedNodeSet API restrictToProperties This will ensure that each of the results will have at least one Property that matches the supplied criteria.

27. Lesson 2: Method Comparisons getDescLogicConcept getDescLogicConcept A 'DescLogicConcept' can be thought of as an 'Entity' in LexEVS. To obtain an Entity, use the CodedNodeSet API, restricting the query as necessary. For instance, a 'DescLogicConcept' with a code of 'C1234' can be queried for by the following example. The example will return a ResolvedConceptReference and ultimately an Entity, but is functionally the same as searching for a DescLogicConcept.

28. Lesson 2: Method Comparisons getDescLogicConcept getDescLogicConcept To 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): First create a ConceptReferenceList to describe the Concept to search for – as demonstrated in the following slide:

29. Lesson 2: Method Comparisons getDescLogicConcept getDescLogicConcept To create the ConceptReferenceList we use the helper class 'Convenience Methods'. ConceptReferenceList crefs = ConvenienceMethods.createConceptReferenceList(new String[] { "C1234"}, "NCI Thesaurus"); Next, restrict the CodedNodeSet. cns.restrictToCodes(crefs); Lastly, resolve the match. ResolvedConceptReferenceList matches = cns.resolveToList(null, null, null, 1);

30. Lesson 2: Method Comparisons get SubConcepts/ get SuperConcepts getSubConcepts/getSuperConcepts Use the CodedNodeGraph API to find the immediate relations of a Concept. For instance: CodedNodeGraph cng = lexevsService.getNodeGraph(String codingScheme, CodingSchemeVersionOrTag versionOrTag, String relationContainerName); ResolvedConceptReference[] rcr = cng.resolveAsList(ConceptReference graphFocus, boolean resolveForward, boolean resolveBackward, int resolveCodedEntryDepth, int resolveAssociationDepth, LocalNameList propertyNames, PropertyType[] propertyTypes, SortOptionList sortOptions, int maxToReturn).getResolvedConceptReference();

31. Lesson 2: Method Comparisons getSubConcepts/ getSuperConcepts getSubConcepts/getSuperConcepts Focus the 'graphFocus' on the desired Concept to see relationships from a given Concept. For examples, see the LexEVS Example classes org.LexGrid.LexBIG.example.FindRelatedCodes org.LexGrid.LexBIG.example.FindPropsAndAssocForCode

32. Lesson 2: Method Comparisons getRelatedConcepts getRelatedConcepts Use the CodedNodeGraph API to find the immediate relations of a Concept. For examples, see the LexEVS Example classes org.LexGrid.LexBIG.example.FindRelatedCodes org.LexGrid.LexBIG.example.FindPropsAndAssocForCode getAllVocabularies Use the 'LexBIGService' API method 'getSupportedCodingSchemes'.

33. Lesson 2: Method Comparisons getRootConcepts getRootConcepts Use 'LexBIGServiceConvenienceMethods' API method 'getHierarchyRoots' or 'getHierarchyRootSet'

34. Lesson 2: Method Comparisons getMetaConceptNameByCode getMetaConceptNameByCode To find the Properties of a given code, for example, code 'C1234567' in the 'NCI MetaThesaurus' ontology - first obtain a 'CodedNodeSet' from the 'NCI MetaThesaurus' ontology: ResolvedConceptReferenceList cns = lbSvc.getCodingSchemeConcepts("NCI MetaThesaurus", null); Next, restrict that to the desired Code ('C1234567' in this example): First create a ConceptReferenceList to describe the Concept to search for. In this example we use the helper class 'ConvenienceMethods'. ConceptReferenceList crefs = ConvenienceMethods.createConceptReferenceList(new String[] { "C1234567"}, "NCI MetaThesaurus");

35. Lesson 2: Method Comparisons getMetaConceptNameByCode getMetaConceptNameByCode Next, restrict the CodedNodeSet. cns.restrictToCodes(crefs); Lastly, resolve the match. ResolvedConceptReferenceList matches = cns.resolveToList(null, null, null, 1); To see the name of the code, use 'getEntityDescription' on the resulting ResolvedConceptReference. matches.getEntityDescription(); The 'EntityDescription' will always be equal to the Preferred Presentation in the Default Language.

36. Lesson 2: Method Comparisons getMetaSources getMetaSources Use the 'LexBIGService' API method 'getMappings'. Extract for this the Supported Association Qualifiers using the 'getSupportedSource' method. Note: This can be applied to any Coding Scheme, not just the NCI MetaThesaurus.

37. Lesson 2: Method Comparisons getSemanticTypeCollectionbyCui getSemanticTypeCollectionbyCui Use 'CodedNodeSet' API - adding a 'restrictToCodes' restriction. Note that a CUI is simply a reference to a Code in the NCI MetaThesaurus ontology. To 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, you’ll want to restrict that to the desired Code ('C1234' in this example):

38. Lesson 2: Method Comparisons getSemanticTypeCollectionbyCui getSemanticTypeCollectionbyCui But first, create a ConceptReferenceList to describe the Concept to search for. In this example we use the helper class 'ConvenienceMethods'. ConceptReferenceList crefs = ConvenienceMethods.createConceptReferenceList(new String[] { "C1234"}, "NCI Thesaurus"); //Next, restrice the CodedNodeSet. cns.restrictToCodes(crefs); Lastly, resolve the match. ResolvedConceptReferenceList matches = cns.resolveToList(null, null, null, 1); Once the ResolvedConceptReference has been obtained, extract the desired Properties and inspect the Semantic Types. Semantic Types are held as Qualifiers to the Properties of an Entity.

39. Lesson 2: Method Comparisons Review 1 Review:  EVS used to have a method for getting a description logic concept. What LexEVS API accomplishes this now?

40. Lesson 2: Method Comparisons Answer 1 Review:  EVS used to have a method for getting a description logic concept. What LexEVS API accomplishes this now? CodedNodeSet using restriction and resolution techniques supplies this to the user

41. Lesson 2: Method Comparisons Review 2 Review:  EVS could retrieve tree structures of concepts as well as direct parents and children of a concept. Does LexEVS have an API for this? If so what is it called.

42. Lesson 2: Method Comparisons Answer 2 Review:  EVS could retrieve tree structures of concepts as well as direct parents and children of a concept. Does LexEVS have an API for this? If so what is it called. This is the CodedNodeGraph API, for which usage examples can be found in the LexBIGServiceConvenienceMethodsImpl and the org.LexGrid.LexBIG.examples package..

43. Lesson 2: Method Comparisons Review 3 Review:  MetaThesaurus calls required special methods for retrieving concepts. Does LexEVS have a separate API for this terminology as well?

44. Lesson 2: Method Comparisons Answer 3 Review:  MetaThesaurus calls required special methods for retrieving concepts. Does LexEVS have a separate API for this terminology as well? LexEVS can query the Metathesaurus from the same API is queries other terminologies. It is also rich enough to provide for the special needs of the Metathesaurus without a special API.

45. Lesson 2: Method Comparisons Review 4 Review:  I don’t see an example of the way I call EVS in these methods – where should I look to solve my problem?

46. Lesson 2: Method Comparisons Answer 4 Review:  I don’t see an example of the way I call EVS in these methods – where should I look to solve my problem? Example code can be found in the admin and example directories of the LexEVS installation. Also users can study the workings of code from the convenience method implementations and the underpinnings of the lbGUI.

47. Lesson 3: Migration Exercises When you complete this lesson you will be able to: Instantiate a terminology service in LexEVS compared to EVS. Master making basic API calls for individual concepts. Master simple node parent and child graph walking LexEVS calls and compare them to similar actions in EVS.

48. Lesson 3: Migration Exercises Example 1 Application Service Examples: Navigate to lexevs.bootcamp.migration.examples Getting an EVS application service– open for editing BaseMigrationExample. this demonstrates how to get the base application service in both EVS and LexEVS. This is not a run-able application, but is a utility class for other parts of the examples and exercises.

49. Lesson 3: Migration Exercises Example 2 Get Child, Get Parent Examples: Navigate to lexevs.bootcamp.migration.examples.relationshipbasedque ries Getting the parents or children of a concept – open for editing GetChildren. this demonstrates how to get the children of a concept in both EVS and LexEVS If you like you can right click and run the example as a java application.

50. Lesson 3: Migration Exercises Exercise 2 Navigate to: lexevs.bootcamp.migration.exercises.relationshipbasedqu eries Open the class GetChildrenExercise and review the code. Modify the method getChildren() so that it uses the CodedNodeGraph API to get the children of this code. When finished, right click on the class in the package explorer and choose Run as -> JUnit Test from the resulting menu. Review the JUnit results in the JUnit window to ensure successful completion The solution is provided at: lexevs.bootcamp.migration.solutions.relationshipbasedqu eries

51. Lesson 3: Migration Exercises Example 3 Get Child, Get Parent Examples: You should already be in lexevs.bootcamp.migration.examples.relationshipbasedque ries Getting the parents or children of a concept – open for editing GetParents. this demonstrates how to get the parents of a concept in both EVS and LexEVS If you like you can right click and run the example as a java application.

52. Lesson 3: Migration Exercises Exercise 3 You should already be in lexevs.bootcamp.migration.examples.relationshipbasedque ries Open the class GetParentsExercise and review the code. Modify the method getParents() so that it uses the CodedNodeGraph API to get the parents of this code. When finished, right click on the class in the package explorer and choose Run as -> JUnit Test from the resulting menu. Review the JUnit results in the JUnit window to ensure successful completion The solution is provided at: lexevs.bootcamp.migration.solutions.relationshipbasedqu eries

53. Lesson 3: Migration Exercises Example 4 Text Based Queries Examples: Navigate to lexevs.bootcamp.migration.examples.textbasedqueries Query a terminology based on a text match -- open for editing QueryByDesignation This demonstrates how to make a text based search using both EVS and LexEVS. If you like you can right click and run the example as a java application.

54. Lesson 3: Migration Exercises Exercise 4 Navigate to: lexevs.bootcamp.migration.exercises.textbasedqueries Open the class QueryByDesignationExercise and review the code. Modify the method searchByMatchingDesignations() so that it gets a reference to the coded nodes in the sample OWL terminology. When finished, right click on the class in the package explorer and choose Run as -> JUnit Test from the resulting menu. Review the JUnit results in the JUnit window to ensure successful completion The solution is provided at: lexevs.bootcamp.migration.solutions.textbasedqueries

55. Lesson 3: Migration Exercises Review 1  How do we instantiate a service in LexEVS?

56. Lesson 3: Migration Exercises Answer 1  How do we instantiate a service in LexEVS? We make a call to instantiate a service from the ApplicationServiceProvider class and cast that class to a LexBIGService.

57. Lesson 3: Migration Exercises Review 2  How do we construct a query in LexEVS to retrieve a single concept?

58. Lesson 3: Migration Exercises Answer 2  How do we construct a query in LexEVS to retrieve a single concept? We retrieve a CodedNodeSet from the LexBIGService and restrict it to the code for the given concept.

59. Lesson 3: Migration Exercises Review 3  How do we construct a query in LexEVS to retrieve a hierarchy of concepts (concepts and their relationships.)

60. Lesson 3: Migration Exercises Answer 3  How do we construct a query in LexEVS to retrieve a hierarchy of concepts (concepts and their relationships.) We retrieve a CodedNodeGraph and resolve it to a ResolvedConceptReferenceList with intact associations within the returned concept references. (Resolving the coded entity is still optional)

61. Questions?