1. NCIEVS Metaphrase API Presented to the National Cancer Institute (NCI) Kim Ong 12/07/2001

2. Outline Architecture Documentation Introduction Some API Classes Sample Code

3. Architecture (RMI) EVS Oracle Database Metaphrase Java API Relational to Object mapping Java Client RMI Server cache

4. Two Versions of APIs Remote Method Invocation (RMI) Component Object Model (COM)

5. Documentation

9. Introduction Source –A version of a local or external authority, such as PDQ, SNOMED, ICD-9, or CPT. Concept –A unit of thought, a semantic unit or ‘meaning’ in the thesaurus. Atom –An occurrence of a name in a source, typically associated with a Partition with a code. Term –A set of atoms which belong to the same Concept and the same lexical class (i.e., have the same LUI)

10. Introduction Partition –A collection of meanings identified in a Source. Code –The string which name a partition in a source. Relationship –A directional link between two concepts

11. Introduction CUI –Concept Unique Identifier LUI –Lexical class Unique Identifier Term Group –A subset of atoms in a source; e.g., preferred term (PT), synonym (SY), abbreviation (AB). Preferred Name –The preferred name for a concept Semantic Type –A classification of concepts

12. Thesaurus Structure concept term atom Preferred name of a concept Preferred form of a term Hierarchical relationship associative relationship Each concept is identified by CUI Each term is identified by LUI

13. Example CUI: C0007114 Skin neoplasm malignant NOS (CTEP-DIS) Skin Neoplasms, Malignant (NCI) Malignant Skin Neoplasm (NCIPDQ) Cancer of the Skin (NCIPDQ) Skin Cancer (NCIPDQ) Malignant Skin Tumor (NCIPDQ) Skin Cancer (NCI) Skin Cancer, Including Melanoma (DBS-CODE) MELANOMA AND NON-MELANOMA SKIN CANCER (DCTD-CD) Skin Cancers (NIH) Malignant Neoplasm of the Skin (NCIPDQ) Malignant Tumor of the Skin (NCIPDQ) PT SY Preferred name

14. Some Details NCI SNOMED For every relationship, there is an inverse relationship also. Relationships between two concepts can be specified by multiple sources (e.g. NCI, SNOMED).

15. Some Details NCI DBSDCBOCC DBS-KEYDBS-CODEDCB-BC DCB-BC2DCB-BC1 A source can have multiple sub-sources

16. Some API Classes

17. Metaphrase Class Enumeration matches(String, SearchSpec) –searches database for the input string returning a list of match objects within the specified limit. Concept getConcept(java.lang.String conceptID) –returns the Concept with the given ID. Enumeration getSources() –returns a list of Source objects. These are the sources contained in metathesaurus. SubSources are not included in this list. Enumeration getConcepts(Source source) –returns a list of Concept objects that contain atoms from the specified source. Note: The above list does not describe all the available methods for this class

18. Concept Class Atom[] atoms() –all the atoms that are contained in this concept. Atom[] atoms(Source source) –all the atoms from the specified source that are contained in this concept. Definition[] definitions() –the definitions for this concept. String conceptID() –the ID for this concept. String preferredName() –the preferred name of this concept. Relationship[] relationships() –the links between this concept and other concepts. Source[] sources() –the sources that have an atom in this concept. Term[] synonyms() –the terms that are synonyms for this concept (basically the terms that are not in the PT termgroup). Note: The first element of this list is also the preferred term. Note: The above list does not describe all the available methods for this class

19. Atom Class Concept concept() –the concept that the atom belongs to. String name() –the name of the atom. String termgp() –the term group to which the atom belongs. Source source() –the source that specified this atom. Note: The above list does not describe all the available methods for this class

20. Term Class Concept concept() –the concept that contains this term. String preferredForm() –the string representation of this term. Note: The above list does not describe all the available methods for this class

21. Definition Class String text() –the text of the definition. Source source() –the source that specified this definition. Note: The above list does not describe all the available methods for this class

22. Relationship Class String rel() –the type of relationship: RN or CHD = narrow, RB or PAR = broader, RO or RL = related. String rela() –more details pertaining to the relationship: e.g., ‘is part of’. Concept concept1() –the first concept that is part of the relationship. Concept concept2() –the second concept that is part of the relationship. Source source() –the source that specified this relationship. Note: The above list does not describe all the available methods for this class

23. Source Class String description() –description of the source String SAB() –an abbreviation that representes the source, e.g., NCI represents National Cancer Institute. Subsource[] children() –the subsources of this source. Note: The above list does not describe all the available methods for this class

24. Match Class Atom matched() –the atom that matched the search string. Atom preferred() –the preferred atom for the concept that contains the matched atom. Concept concept() –the concept that contains the matched atom. int score() –the match score. The higher the score the better the match. Term matchedTerm() –the term that matched the search string. Term preferredTerm() –the preferred term for the concept that contains the matched term. Note: The above list does not describe all the available methods for this class

25. Sample Code

26. Example Connect to EVS metaphrase server Perform Search for “Skin Cancer” and identify matched concepts Get synonyms for each matched concept Get relationships for each matched concept Compile & Run

27. Step 1: Connect to EVS - Create an instance of RMIMetaphrase RMIMetaphrase(String serverURL, String DBName, String userName, String passWord) Constructor try { metaphrase = new RMIMetaphrase("//"+"ncievs.nci.nih.gov"+"/RemoteMetaphrase", "NCI", "guest", "NCI-EVS"); } catch (MetaphraseException me) { } Example

28. Step 2: Perform Search - Use the matches function Enumeration Metaphrase.matches(String s, SearchSpec spec ) Atom Match.matched(); Atom Match.preferred() String Atom.name() Methods try { SearchSpec spec = new SearchSpec(); spec.setLimit(10); String s = “Skin Cancer”; Enumeration matches = metaphrase.matches(s, spec); while (matches.hasMoreElements()) { Match match = (Match) matches.nextElement(); Term matched_Term = match.matchedTerm(); int score = match.score(); String matchAtom = matched_Term.preferredForm(); Concept concept = matched_Term.concept(); String CUI = concept.conceptID(); } catch (MetaphraseException me) { } Example

29. Step 3: Get Synonyms - Call on Concept.synonyms for each matched concept Term[] Concept.synonyms() String Term.preferredForm() Methods while (match.hasMoreElements()) { Concept concept = ((Match) match.nextElement()).concept(); try { Term[] syns = concept.synonyms(); for (int I=0;I<syns.length;I++) System.out.println(syns[I].preferredForm()); } catch (MetaphraseException me) { } } Example

30. Step 4: Get Relationships - Call on Concept.relationships for each matched concept Relationship[] Concept.relationships() String Relationship.rel(); Concept Relationship.concept1(); Methods while (match.hasMoreElements()) { Concept concept = ((Match) match.nextElement()).concept(); try { Relationship[] rels = concept.relationships(); for (int I=0;I<rels.length;I++) System.out.println(rels[I].concept1().preferredName() + “ “ rels[I].rel() + “ “ + rels[I].concept2().preferredName()); } catch (MetaphraseException me) { } } Example

31. Step 5: Compile & Run (RMI) javac -deprecation -classpath %classpath%; c:\metaphrase\Metaphrase2.jar test.java Compile java -classpath %classpath%; c:\metaphrase\Metaphrase2.jar test Run

32. Step 5: Compile (COM) javac -deprecation -classpath %CLASSPATH%; c:\Metaphrase\commetaphrase.zip; c:\Metaphrase\xerces.jar; c:\Metaphrase\Tbv5vbjn.zip; c:\metaphrase\metaphrase2.jar; c:\jswdk-1.0.1\lib\servlet.jar test.java

33. Step 5: Run (COM) if "%OS%" == "Windows_NT" setlocal set BASE=%1 set TERM=%2 jview -cp %BASE%commetaphrase.zip; %BASE%xerces.jar test pause