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

Outline Architecture Documentation Introduction Some API Classes Sample Code

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

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

Documentation

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)

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

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

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

Example CUI: C 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

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).

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

Some API Classes

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

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

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

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

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

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

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

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

Sample Code

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

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

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

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

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

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

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

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