UMLS-Query: A Perl module to query a UMLS mysql installation

Download UMLS-Query

Download a report describing UMLS-Query

      use UMLSQuery;
      my $U = new UMLSQuery;
      $U->init( u => 'username',
                        p => 'password',
                        h => 'hostname',
                        dbname => 'umls');
      $U->getCUI(string/aui/sui/lui, sab=>)
      $U->getAUI(string/cui/sui/lui, sab=>)
      $U->getSTR(string/cui/aui/sui/lui, sab=>)
      $U->getSAB(string/cui/aui/sui/lui)
      $U->mapToId(phrase, idtype=>cui/lui/sui/aui, sab=>)
      $U->getParents(aui/cui, rela=>, sab=>)
      $U->getCommonParent(aui/cui, aui/cui, rela=>, sab=>)
      $U->getChildren(aui/cui, rela=> sab=>)
      $U->getCommonChild(aui/cui, aui/cui, rela=>, sab=>)
      $U->getDistBF(cui_1, cui_2,rela=>)
      $U->getAvailableSAB()
      $U->finish()

Current version 0.3

0.2 sab can take multiple dictionaries as value e.g. “RXNORM, SNOMEDCT”

0.3 getParents only returned a single path to the root even if multiple paths existed. That is now fixed. This leads to a change in the output of that funtion. The output hash now has paths as key and the immediate parent node as value.

This module will allow you to connect to a mysql UMLS installation and run common queries. If you have a query that you want, contact me at nigam.AT.stanford.edu.

Provide a username, password, host and dbname of a valid UMLS mysql database. You can optionally provide a port⇒ if your mysql is not on port 3306

This function accepts any text string, an aui (Atom Unique Identifier), sui (String Unique Identifier) or lui (Lexical Unique Identifer) and gets its cui (Concept Unique Identifier). The search is for an exact match. To restrict the search to a particular dictionary provide the sab value. The following searches for 'prostate' in the SNOMED-CT vocabulary.

         $U->getCUI('prostate', sab=>'SNOMEDCT')

This function accepts any text string, a cui (Concept Unique Identifier), sui (String Unique Identifier) or lui (Lexical Unique Identifier) and gets its aui (Atom Unique Identifer). The search is for an exact match. To restrict the search to a particular dictionary provide the sab value. The following searches for 'prostate' in the SNOMED-CT vocabulary.

          $U->getAUI('prostate', sab=>'SNOMEDCT')

This function accepts a cui (Concept Unique Identifier), aui (Atom Unique Identifer) sui (String Unique Identifier) or lui (Lexical Unique Identifier) and gets its string. The search is for an exact match. To restrict the search to a particular dictionary provide the sab value. The following searches for 'A0812060' in the SNOMED-CT vocabulary.

          $U->getSTR('A0812060', sab=>'SNOMEDCT')

This function accepts a cui (Concept Unique Identifier), aui (Atom Unique Identifer) sui (String Unique Identifier) or lui (Lexical Unique Identifier) and gets the dictionary/s it belongs to. The search is for an exact match (if a string is provided).

          $U->getSAB('prostate')

This function accepts a phrase (upto 10 words) and maps it to the chosen idtype (can be restricted by sab if desired. The function first looks for an exact match for the phrase, if none is found, then will generate all possible permutations and attempt an exact match for each one (with right truncation of words to look for partial matches). The following tries to find a CUI belonging to the SNOMED-CT for 'intraductal carcinoma of prostate'.

          $U->mapToId('intraductal carcinoma of prostate',
                       idtype=>'cui', sab=>'SNOMEDCT');

          The function returns a hash which has a particular
          permutation as its key and the value is an array of 
          pairs of id - string. The above examle returns:

          key             id      string
          ------------------------------
          carcinoma       C0007097 Carcinoma
          intraductal     C1644197 Intraductal
          prostate        C0033572 Prostate
          carcinoma prostate      C0600139 Carcinoma prostate
          intraductal carcinoma   C0007124 Intraductal carcinoma
          prostate carcinoma      C0600139 Prostate carcinoma
          carcinoma of prostate   C0600139 Carcinoma of prostate

          in case of mutliple matches, the id - string pair will be
          pushed onto the array.

This function accepts a cui or aui and returns all its parents (optionally restricted along a particular relationship type (rela, 188 posible values) and a vocabulary). The example below finds all isa parents of 'C0600139'.

          $U->getParents('C0600139', rela=>'isa');

          The function returns a hash, where the keys are the string 
          of ids forming the path to the root node and the values are 
          the direct parents of the id. The ids are always reported as
          aui. The example above returns:

          direct parent   Path to the root (key)
          ---------------------------------------------------
          A3407646        A3684559.A3713095.A3506985.A3407646

This function accepts a pair of cuis or auis and returns the common parent (optionally restricted along a particular relationship type (rela, 188 posible values) and a vocabulary). The example below finds common parents of 'C0600139','C0007124' along any rela type.

          $U->getCommonParent('C0600139','C0007124');

          The function returns the common parent (aui) and the 
          distance (dist) from the query nodes. 
          The above example returns:

          aui             dist
          -------------------------------------------------------
          A0689089        4 links from C0600139 3 links from C0007124

This function accepts a cui or aui and returns all its direct children (optionally restricted along a particular relationship type (rela, 188 posible values) and a vocabulary). The example below finds all isa children of 'C0376358'.

          $U->getChildren('C0376358',rela=>'isa');

          The function returns a hash, where the keys are the direct
          children of the id and the values is the query id. The ids
          are reported in the form of the query id. 
          The example above returns:

          child   	parent
          ------------------------
          C0347001        C0376358
          C1330959        C0376358
          C1302530        C0376358
          C1282482        C0376358

This function accepts a pair of cuis or auis and returns the common child (optionally restricted along a particular relationship type (rela, 188 posible values) and a vocabulary). The example below finds common parents of 'C0376358','C0346554' along any rela type.

          $U->getCommonChild('C0376358','C0346554');

          The function returns the common child and the ids of the
          query nodes. The example above returns

          C0600139        common child of C0376358 and C0346554

This function accepts two cuis and performs a breadth first search from cui_1 to find cui_2 and reports the number of links at which cui_2 is found. The search is aborted if cui_2 is not found in a radius of maxR links. (maxR is set to 3 if it is not provided)

          $U->getDistBF('C0600139','C0007124');
          The above example returns 2.

This function returns a hash where the keys are the 'sab' and the values are the descriptions of those sab that contain the 'search string'. The example below searches for sab that have SNOMED in their description.

          $U->getAvailableSAB('SNOMED');

          It returns:
          sab             description
          -------------------------------------------------
          SNOMEDCT        SNOMED Clinical Terms, 2006_01_31
          SCTSPA  SNOMED Clinical Terms, Spanish Language Edition, 2005_10_31
          SNM     SNOMED-2, 2
          SNMI    SNOMED International, 1998

Disconnect and end the querying.