Prerequisites and Notices Download Installation

Overview of What Happens Example Programs How to Compile and Run

Details on Supported Programs Programming Notes Javadoc for SKR API

Whenever you see in the text below, it means that additional information is available by selecting the symbol.

• To access either the Interactive Mode or Batch Mode facilities, you MUST have access to a UMLSKS account. For more information about how we use UMLSKS authentication data, or for information on how to set up a UMLSKS account, please select the Info icon to the right which will take you to the SKR web site:
  
  
• A running version of Java. We have tested and confirmed that the SKR API program compiles and runs under the following versions of Java:
  • 1.4.2_06
  • 1.5.0_08
  • 1.5.0_12
  
  
• We have tested and confirmed that the SKR API program runs on the following operating systems:
  • Sun Solaris 5.8
  • Microsoft Windows XP
  • GNU/Linux 2.4.21
  
  
• Apache's Jakarta Project Ant program is required if you wish to modify and/or compile the SKR API source code using the existing build file:  1.6 or better  
  
  
• Your data in a recognized format. Please see the Supported File Formats section of the SKR Help Information web page for detailed information and examples of valid input formats.

	Version	Notes	Sizes
	1.5	Library, Examples, Documentation, and all Source Code	297KB
	1.5	Library, Examples, and Documentation No Source Code Version	261KB

1. Make a top level directory to store the SKR API program.
   
   
2. Go to the SKR API page from the SKR homepage.
   
   
3. Download the latest version of the SKR API into the directory created in #1.
   
   
4. Change directory to the directory created in #1
   
   
5. Extract the jar files from the downloaded jar file - either SKR_API_V1_5.jar or SKR_API_V1_5_noSource.jar.
   • On Windows:Run winzip, pkzip, or zip on the downloaded file.
     
     
   • On Unix:Run the java jar program on the jar file: java sun.tools.jar.Main xf SKR_API_V1_5.jar
   
   
6. This will create a directory called "SKR_API_V1_5" or "SKR_API_V1_5_noSource" in the directory you created in #1 and fill it with all of the program files needed.
   
   
7. Now, change to this new directory: cd SKR_API_V1_5
   
   
8. You are now ready to run. Look at the example programs in the "Examples" subdirectory for ideas on what to do. There is also a 00Note file located in the "Examples" directory which shows you how to compile and run the example programs.

The SKR API has been designed to allow you to interact with our web-based Scheduler using either our Batch or Interactive facilities.

• Batch Jobs have three main phases:
  1. Request is made for a new batch job and the SKR API submits the job.
     
     
  2. Program waits for job to finish. This is done by monitoring the Scheduler queue to see when the job exits the queue. The program sleeps for 10 seconds after each check of the queue so that it doesn't become a nuisance process.
     
     
  3. Once the job has left the Scheduler queue, the program then checks to see if the "text.out.done" file exists in the job result directory. If it does, then the results file "text.out" is returned as a String to the calling method. If the "text.out.done" file doesn't exist, an error has occurred and the program exits.
  
  
  
• Interactive Jobs only have two main phases:
  1. Request is made for a new interactive job and the SKR API submits the job.
     
     
  2. Program waits for job to finish and returns the result as a String to the calling method. Interactive jobs don't really enter the Scheduler - they are run from the command line. The API simply waits for the command to return a result without having to worry about the Scheduler queue, etc., providing the fastest mechanism for receiving results.
     
     
  3. Note: Interactive jobs will only accept a single item to process - anything larger will cause an error.

There are several example files included to show the various ways to access the SKR Scheduler routines. These are all located in the Examples directory. NOTE: Currently, the SKR Batch and Interactive programs have been removed from the download until changes can be made to the underlying programs to conform to the current MetaMap. You can use the example in the Generic_II_Batch.java to run MetaMap by changing the options. If you need to see what options are available, please look on the MetaMap Interactive or Batch pages to see what options are available. Currently, you can run "metamap" which is the default MetaMap 2009 program using 2009AA data, "metamap08" which is the MetaMap 2008 program using 2008AA data, or "metamap0809" which uses the MetaMap 2008 program and 2008AB data.

GenericBatch.java Example program for submitting a new Generic Batch with Validation job ("GenericObject(true)" turns on validation) request to the Scheduler to run. You will be prompted for your username and password and if they are alright, the job is submitted to the Scheduler and the results are returned in the String "results" below. NOTE: There is no Interactive facility for Generic jobs at this point. This example shows how to setup a basic Generic Batch with Validation job with a small file (medlin25.txt) with ASCII MEDLINE formatted citations as input data. You must set the Email_Address variable and use the UpLoad_File to specify the data to be processed. This example also shows the user setting the silentEmail option which tells the Scheduler to NOT send email upon completing the job. This example is set to run the MTI (Medical Text Indexer) program using the -opt1_DCMS and -E options. You can also setup any environment variables that will be needed by the program by setting the Batch_Env field.

Generic_II_Batch.java Example program for submitting a new Generic Batch with Validation job ("GenericObject(true)" turns on validation) request to the Scheduler to run. You will be prompted for your username and password and if they are alright, the job is submitted to the Scheduler and the results are returned in the String "results" below. NOTE: There is no Interactive facility for Generic jobs at this point. This example shows how to setup a basic Generic Batch with Validation job with a small file (medlin25.txt) with ASCII MEDLINE formatted citations as input data. You must set the Email_Address variable and use the UpLoad_File to specify the data to be processed. This example also shows the user setting the silentEmail option which tells the Scheduler to NOT send email upon completing the job. This example is set to run the MetaMap program using the "-% format -E" options. This will cause MetaMap to generate XML output. You can also setup any environment variables that will be needed by the program by setting the Batch_Env field. NOTE: The "-E" option/argument is very important and should be included with whatever program you decided to run! The reason is that this version of the Generic Batch does validation and the -E option tells the various programs to include a marker denoting when a successful result has been found.

MTIBatch.java: Example program for submitting a new MTI Batch job request to the Scheduler to run. You will be prompted for your username and password and if they are alright, the job is submitted to the Scheduler and the results are returned in the String "results" below. This example shows how to setup a basic MTI Batch job with a small file (medlin25.txt) with ASCII MEDLINE formatted citations as input data. You must set the Email_Address variable and use the UpLoad_File to specify the data to be processed. This example also shows the user setting the silentEmail option which tells the Scheduler to NOT send email upon completing the job. This example also shows one way to setup which arguments you want to use for the MTI program ("myMTIObj.setArgs("-opt1_DCMS");". This tells MTI to use the opt1 variant of our DCMS processing options to process our data. The results that come back from MTI are then just printed to the standard output.

MTIInteractive.java: Example program for submitting a new MTI Interactive job request to the Scheduler to run. You will be prompted for your username and password and if they are alright, the job is submitted to the Scheduler and the results are returned in the String "results" below. This example shows how to setup a basic MTI Interactive job with a short sentence of free text as input data. You must set the Email_Address variable and use the APIText variable to specify the data to be processed. This example also shows one way to setup which arguments you want to use for the MTI program ("myMTIObj.setArgs("-opt1_DCMS -display_full");". This tells MTI to use the opt1 variant of our DCMS processing options to process our data and then to display all of the possible terms (-display_full) inorder instead of the default max of 25. The result that comes back from MTI is then just printed to the standard output.

SemRepBatch.java: Example program for submitting a new SemRep Batch job request to the Scheduler to run. You will be prompted for your username and password and if they are alright, the job is submitted to the Scheduler and the results are returned in the String "results" below. This example shows how to setup a basic SemRep Batch job with a small file (medlin25.txt) with ASCII MEDLINE formatted citations as input data. You must set the Email_Address variable and use the UpLoad_File to specify the data to be processed. This example also shows the user setting the silentEmail option which tells the Scheduler to NOT send email upon completing the job. This example also shows one way to setup which arguments you want to use for the SemRep program ("mySemRepObj.setArgs("-D");". This tells SemRep to use the "Full Fielded Output" when processing the data. The results that come back from SemRep are then just printed to the standard output.

SemGenBatch.java Example program for submitting a new SemGen Batch job request to the Scheduler to run. You will be prompted for your username and password and if they are alright, the job is submitted to the Scheduler and the results are returned in the String "results" below. This example shows an alternate method to specifying which file to upload. This example reads in the small file (medlin25.txt) with ASCII MEDLINE formatted citations as input data and builds a String with the data which is then sent to the Scheduler instead of the file reference. You must set the Email_Address variable and use the APIText variable to specify the data to be processed. This example also shows that the user did not specify the silentEmail option, so they will have a notification email sent to the address in the Email_Address specification. This example also has SemGen using just the default setup when processing the data. The results that come back from SemGen are then just printed to the standard output.

• To compile the jar file - from the top-level directory run "ant jar".
  
  
• To compile or run any of the examples you will need to change to the Examples directory first:
  
  cd Examples
  
  
• To compile any of the examples:
  
  Unix: javac -classpath .:../lib/skrAPI.jar SKR_Batch.java
  
  Windows: javac -classpath .;..\lib\skrAPI.jar SKR_Batch.java
  
  
  
• To run any of the examples:
  
  Unix: java -cp .:../lib/skrAPI.jar SKRBatch
  
  Windows: java -cp .;..\lib\skrAPI.jar SKRBatch
  

• MetaMap
• Medical Text Indexer (MTI)
• SemGen
• SemRep
• Generic/Generic with Validation

Required Fields		Batch Specific Optional Fields
General Description Short Name Form Name Type Email Address Email_Address Email_Address String Internal Text field APIText APIText String File to Upload UpLoad_File UpLoad_File String You must specify either the APIText or the UpLoad_File. * Interactive Mode will ONLY accept the APIText field. * Batch Mode will accept either field being specified.		General Description Short Name Form Name Type Silent on Errors ESilent ESilent Boolean Single Line Delimited Input   SingLine SingLine Boolean Single Line Delimited Input w/ID SingLinePMID SingLinePMID Boolean Requested Run Priority Level RPriority RPriority String No Completion Email SilentEmail SilentEmail Boolean

• You "should" catch "RuntimeException" exceptions in your program since this is what the SKR API throws internally when it encounters an error. See example below for try/catch sample.
  
  
• You must specify an Email Address. This is used for logging as well as notification when Batch jobs finish, or if there are problems with a job.
  
  
• You must specify either the APIText or UpLoad_File field. For Interactive jobs, you must use the APIText field. For Batch jobs, you can specify either.
  
  
• Valid Batch job priorities are "0", "1", or "2". Where "0" represents Normal priority, "1" represents Medium, and "2" represents High priority. Medium and High priorities are reserved and you must have the proper permissions to use them.
  
  
• At the moment, only the Generic program is restricted to Batch jobs. All of the other programs allow both Interactive and Batch jobs.
  
  
• Explanation of setting up a basic SKR API program. The following description details the steps to setting up a simple SKR API job to send a small file to the Scheduler and receive a result back. See the SKRBatch.java program file in the Examples directory for the full program.
  
  
  1. The first thing you need to do is create a job object for the type of program you want to run.
     
     
     SKRObject mySKRObj = new SKRObject();
     
     This creates a job object for the MetaMap program. The same job object is used for either Interactive or Batch jobs.
     
     
  2. The next thing to do is setup any of the required or batch specific fields.
     
     
     mySKRObj.setField("Email_Address", "yourEmailAddress");
mySKRObj.setField("silentEmail", true);
mySKRObj.setField("UpLoad_File", "./medlin25.txt");
     
     This tells the job object what your email address is (required), tells the Scheduler that we don't want to be notified after the job completes (silentEmail), and that we want to use the local file "medlin25.txt" as the input data to be processed (UpLoad_File). This also tells us that we are going to be submitting a Batch job request since the "UpLoad_File" field is specified and that field is not allowed for Interactive jobs.
     
     
  3. Next we want to specify any program specific options or arguments. This can be done in two different ways as the example below shows.
     a)
     
     mySKRObj.setArgs("-Ir 980 -n");
     
     b)
     
     mySKRObj.setField("show_cuis", true);
mySKRObj.setField("threshold", "980");
mySKRObj.setField("number_the_candidates", true);
     
     Both of these tell the job object to set the same fields. The first example (a) mimics the command line arguments, while the second example (b) allows you to set the fields using the argument name, short name, or the form name to specify the field. So, for the "-I" option, we have "-I" (argument name), "show_cuis" (short name), or "CB100" (form name) to identify the same field. Please see the options/fields list for each of the identified programs to find what is available for each field.
     
     
  4. Now we are finally ready to actually submit the Batch job and receive our results back. We surround this submission code with a try/catch for any "RuntimeException" exceptions that might be thrown back to us from the SKR API program.
     
     
     try
{
   String results = mySKRObj.handleSubmission();
   System.out.print(results);
} catch (RuntimeException ex) {
   System.err.println("");
   System.err.print("An ERROR has occurred while processing your");
   System.err.println(" request, please review any");
   System.err.print("lines beginning with \"Error:\" above and the");
   System.err.println(" trace below for indications of");
   System.err.println("what may have gone wrong.");
   System.err.println("");
   System.err.println("Trace:");
   ex.printStackTrace();
} // catch

     
     This calls the job object routine that takes care of the job from submission, monitoring, cleaning up, and returning a result.

Last Modified: July 30, 2009							ii-public
Links to Our Sites MetaMap Public Release NEW: Distributable version of the actual MetaMap program. Indexing Initiative (II) Investigating computer-assisted and fully automatic methodologies for indexing biomedical text. Includes the NLM Medical Text Indexer (MTI). Semantic Knowledge Representation (SKR) Develop programs to provide usable semantic representation of biomedical text. Includes the MetaMap and SemRep programs. MetaMap Transfer (MMTx) Java-Based distributable version of the MetaMap program. Word Sense Disambiguation (WSD) Test collection of manually curated MetaMap ambiguity resolution in support of word sense disambiguation research. Medline Baseline Repository (MBR) Static MEDLINE Baselines for use in research involving biomedical citations. Allows for query searches and test collection creation.
	Lister Hill National Center for Biomedical Communications			U.S. National Library of Medicine			National Institutes of Health
							Department of Health and Human Services
Contact Us    |   Copyright    |   Privacy    |   Accessibility    |   Freedom of Information Act    |   USA.gov