Skip Navigation
National Cancer Institute U.S. National Institutes of Health www.cancer.gov
NCI Wiki New Account Help Tips
Skip to end of metadata
Go to start of metadata

cTAKES 1.2.1 Developer Install Instructions

Contents of this Page

These instructions are for developers. With these instructions you can set up cTAKES within your development environment and then change or extend the code, compile and deploy. If you simply want to be a user of the software then go back to the overview and select the User install instructions desired.

Once you have completed this install you will have all the source code and be able to compile and deploy it as needed. Knowledge of what the components do is not supplied by these install instructions. That is found in the User Guide. There is no training or documentation (except for code comments) on the code itself. You must familiarize yourself with the components and then study the code on your own to be able to extend it.

In order to modify the source code for a cTAKES component, developers must download the code. Then you can utilize either an IDE, such as Eclipse, to do the modification, or another editor of your choice. Compiles are then performed in Eclipse or with Ant (using a command line).

Follow the appropriate sections here depending upon your developer preferences.

Prerequisites

The prerequisites for installing for a developer follow. In order to complete these instructions you will need the following:

  • Java JDK version 1.5+
  • Apache UIMA 2.3.1+ and Eclipse 3.7+
  • Ant 1.7.1+

Step

Example

1. Open a command prompt window.

No example for this step

2. Install the JDK (not the runtime environment) of Java 1.5+.
This software can be downloaded from:

http://www.java.com/en/download/faq/develop.xml



You need two things: the proper version and the SDK, not just the Java Runtime environment.

To check if you have the SDK, look in the lib directory of the Java install and see if the file tools.jar is there. If there is a lib directory and there is a file by that name then you have the SDK.

To check if you have the proper version. Enter the command:
Windows and Linux java -version
on any command line to see what version you have now.

Note

Notice that this is the SDK and not only the Java Runtime Environment.

3. It is possible that some commands and programs can find the Java runtime that you want to be used but it is best to set the JAVA_HOME environment variable. Set the value of JAVA_HOME to the absolute path of the root of the Java Runtime environment that you want UIMA to use.

Windows Right-click on My Computer > Properties > Advanced tab > Environment Variables button > New button for System variables. Keep clicking OK until you are out of the dialog series.

Linux Use the command
set JAVA_HOME<path>

screenshot to illustrate step

4. Navigate to the UIMA Java framework & SDK from Apache UIMA 2.3.1+.

Go to the Apache UIMA Project site.

screenshot to illustrate step

5. Download the UIMA Java framework and SDK.

Select the file to download based on your operating system:

Windows Download the Binary ZIP file.

Linux Download the Binary TAR.GZ file.

Save the file to a temporary location on your machine.

screenshot illustrating step

6. Unzip the compressed file you downloaded.

Windows Launch (double-click) the file and extract the files to a directory like c:\uimaj-2.3.1-bin\apache-uima

Linux Run the tar command and extract the files to a directory like usr/bin/uimaj-2.3.1-bin/apache-uima

screenshot to illustrate step

7. (recommended) Rename the base directory to indicate a cTAKES install. For example:

Windows rename uimaj-2.3.1-bin cTAKES1.2.1
Linux move uimaj-2.3.1-bin cTAKES1.2.1

All of the example commands after this point will use the modified directory name. This root directory we will call <cTAKES_HOME>

screenshot to illustrate steps

8. Set the UIMA_HOME environment variable. UIMA requires a special environment variable for its commands to run.

Use UIMA_HOME for the name of the variable and the absolute path to the <cTAKES_HOME> directory in the previous step as the value.

Windows Right-click on My Computer > Properties > Advanced tab > Environment Variables button > New button for System variables. Keep clicking OK until you are out of the dialog series.

Linux Use the command
set UIMA_HOME<path>

screenshot to illustrate step

Note

Notice the underscore in the name of the variable. You can not have spaces in the variable name nor in the path represented by the variable.

9. An environment variable called PATH already exists. Modify that environment variable to add <cTAKES_HOME>/bin on the end of the value. For example,
Windows ;c:\cTAKES1.2.1\apache-uima\bin
Linux :/usr/bin/cTAKES1.2.1/apache-uima/bin

Note

Notice there is a semi-colon (Windows) or colon (Linux) between the existing value of the PATH and the directory you are placing on the end.

10. Open a new command prompt (in order to pick up the environment variable changes). In your command prompt change to the cTAKES_HOME directory and run the command to set paths.

Windows adjustExamplePaths.bat
Linux .adjustExamplePaths.sh

screenshot to illustrate step

11. (for developers using Eclipse) Install Eclipse and plug-ins. This documentation is not here. You must follow the install instructions provided with UIMA for Eclipse.

Note

There are UIMA plug-ins that need to be installed. Do not skip the installation of these plug-ins.

screenshot to illustrate step

12. (for developers using command line compile) Navigate to the Ant download site.

screenshot to illustrate step

13. (for developers using command line compile) Download Ant 1.7.1 or later.

Unzip the compressed file you downloaded. We will call this <ANT_HOME>. Follow the instructions for installing Ant. This will include changing the PATH and ANT_HOME environment variables.

Tip

If you will not be using Eclipse but still compiling source code from a command line, that is when you would need to install Ant.

screenshot to illustrate step
screenshot to illustrate step

Additional Information

The documents upon which you can run cTAKES will take many forms. An example of doing this is covered in the Testing section.

Download source code

Since cTAKES is an open source tool you can get the version that is currently in development through SVN. This is not recommended unless you know what you are doing. In order to get the latest, stable release you can follow the same instructions for users. Go to the Install cTAKES user instructions now, perform those instructions and then come back here.

SVN

If know what you are doing with the cTAKES code and you must get the latest code currently under development then you need to use an SVN connection to retrieve the code. The pre-release versions are available from SVN code repository here:

Eclipse

Configure Eclipse

These instructions require the UIMA plug-ins. This was part of the prerequisites at the start of these instructions.

Step

Example

1. Open Eclipse to a new workspace.
File > Switch Workspace > Other

For the workspace location navigate to <cTAKES_HOME>

screenshot to illustrate step

2. Add a new user library.

*Window > Preferences > Java > Build Path > User Libraries

Click New...

Type UIMA (this name is required as the pre-build projects link in a library by this name).

Click OK.

screenshot illustrating step

3. Add UIMA JAR files to the library.

Click Add JARs...

Navigate to <cTAKES_HOME>\lib

Select all the JAR files and click Open.

screenshot illustrating step

4. Close the User Libraries dialog.

Click OK.

screenshot illustrating step

Additional Information

Although creating a new workspace is not required, we recommend you create one to separate cTAKES projects from your existing Eclipse projects.

Import and build projects

After this section is complete you will have all the makings of a development environment with the cTAKES code. You'll be able to modify the code, set breakpoints, check variable values in real time, and other fun things that programmers do.

Step

Example

1. In Eclipse use File > Import...

Select Existing Projects into Workspace under General.

Click Next >.

screenshot illustrating step

2. Navigate to <cTAKES_HOME> for select root directory.

All the pre-built cTAKES Eclipse projects will show up in the Projects list. You should notice that there is one for each PEAR file. You may deselect the uimaj-examples project if you wish as it is not needed.

Leave the rest of the projects selected and click Finish.

screenshot illustrating step

3. Change to the Java perspective (if Eclipse is not already there):

Window > Open Perspective > Java

screenshot illustrating step

4. (optional) Each project should already have UIMA linked as a user library. If you want to check:

Right-click on any project. Select Properties. Select the Libraries tab and expand the + sign by UIMA.

screenshot illustrating step

5. Most new workspaces in Eclipse are going to be set to build automatically. Check this by selecting the Project menu item. If Build Automatically has a checkmark by it then you are ready to move on. If not then select Project> Build All.

screenshot to illustrate step

Generate the type system from Eclipse for source files from SVN

If you checked out source files from the SVN repository, you will need to generate the type system from the following type system descriptors:

  • chunker/desc/TypeSystem.xml
  • clinical documents pipeline/desc/analysis_engine/TypeSystem.xml
  • context dependent tokenizer/src/edu/mayo/bmi/uima/cdt/type/CdtTypeSystem.xml
  • core/src/edu/mayo/bmi/uima/core/type/TypeSystem.xml
  • dictionary lookup/src/edu/mayo/bmi/uima/lookup/type/DictionaryLookupTypeSystem.xml
  • document preprocessor/desc/CDAToTextTypeSystem.xml
  • NE contexts/desc/TypeSystem.xml
  • POS tagger/desc/TypeSystem.xml
  • Drug NER/desc/type_system/NERTypeSystem.xml (optional component)
  • dependency parser/type_system/desc/TypeSystem.xml (optional component)

To generate the type system from Eclipse:

  1. Select the file in the Package Explorer or Navigator.
  2. Open the file in Component Descriptor Editor (right click on the file > Open with > Component Descriptor Editor).
  3. Click the tab Type System.
  4. Click the JCasGen button (in the center).
  5. Repeat the above steps for each type system descriptor.
  6. Click Project > Build All to build all the projects unless you have Build automatically already selected in the Projects menu.

Process a sample clinical note from Eclipse

You can now launch or debug the cTAKES components that you have built. You could run commands from a command prompt, as found in the user install instructions, but you can launch them from within Eclipse now instead.

Step

Example

1. Launch the CAS Visual Debugger (CVD).

Run > Run Configurations...

No example for this step

2. Expand Java Applications and select UIMA_CVD--clinical_documents_pipeline
Click Run.

screenshot to illustrate step

3. Load an analysis engine.
Menu > Run > Load AE

screenshot to illustrate step

4. Navigate to and select the file <cTAKES_HOME>/clinical documents pipeline/desc/analysis_engine/AggregatePlaintextProcessor.xml

screenshot to illustrate step

5. Copy the text at the right and paste the contents into the Text section of CVD, replacing the text that is already there.

This example file can also be found in test data:
<cTAKES_HOME>/clinical documents pipeline/test/data/plaintext/testpatient_plaintext_1.txt

6. From the menu bar, click Run -> Run AggregatePlaintextProcessor.

You'll get a list of all the annotations in the Analysis Results frame.

screenshot to illustrate step

7. Named entities are now recognized in this clinical document. To find one, in the Analysis Results frame, click on the key in front of:

  • AnnotationIndex
  • uima.tcas.Annotation
  • edu.mayo.bmi.uima.core.type.IdentifiedAnnotation
  • edu.mayo.bmi.uima.core.type.NamedEntity

    Then select edu.mayo.bmi.uima.core.type.NamedEntity itself.

    This will show an Annotation Index in the lower frame. Select any NamedEntity in that frame and you will see the text discovered in the Text frame on the right.

    Double click the NamedEntity in the lower left frame to see the NamedEntity's attributes

screenshot to illustrate step

Command Line

Even if you are not using Eclipse's GUI, it is recommended that you have a viable Eclipse installation on hand. This section mostly assumes that case.

Prepare the compiling environment

We ship an Apache ant build file and a build.properties file in the stable release. Before using these you will need to modify the build.properties file by supplying your machine's configuration. Although this file is not required, we recommend you create one, which can ease debugging efforts, as environmental variables that may be changed without your being aware. It also helps insert the cTAKES version number to the generated Javadoc files. Here are the steps.

Step

Example

1. Copy the build files into cTAKES_HOME.

copy <temp location>/build* <cTAKES_HOME>, for example

Windows copy c:\stuff\cTAKES-1.2.1-pear\build c:\cTAKES1.2.1\apache-uima*

Linux cp /tmp/cTAKES-1.2.1-pear/build /usr/bin/cTAKES1.2.1*

screenshot illustrating steps

2. Edit the file: <cTAKES_HOME>\build.properties

You must place your path values in for the empty variables. The version variable is per-filled in. Remove the comments in front of the variable names. You should end up with a file similar to the one on the right. This example does have both Windows and Linux examples. The Linux example lines are currently commented out with the # sign.

Additional Information

Windows users: In paths, use escaped backslash:

3. Check or change UIMA jcasgen_merge script.

As of this writing, one utility script from Apache UIMA 2.2.2 calls Eclipse's startup.jar; however, since Eclipse 3.3, this file has been moved to ECLIPSE_HOME/plugins/org.eclipse.equinox.launcher_VERSION.jar.

If you're using Eclipse 3.3 or higher then make the modifications at the right.

Windows Modify cTAKES_HOME/bin/jcasgen_merge.bat

should be changed such that startup.jar is replaced with the file in plugins found to resemble plugins\org.eclipse.equinox.launcher_VERSION.jar, for example:

Linux Modify cTAKES_HOME/bin/jcasgen_merge.sh

should become



Another option, if you're not running Windows, is to create a symbolic link. Otherwise, if you don't use Eclipse or you use an earlier version, please ignore this.

Additional Information

If you are running without Eclipse installed, you will have to manually run cTAKES_HOME/bin/jcasgen.{bat|sh} on the Type System files. This is documented in the SVN section.

Process a sample clinical note using the command line

This is very similar to testing a clinical note above when called from Eclipse. This time, without Eclipse, you must launch the component from a command line or, in this case, calling an ant target that has been provided.

Open a command prompt and change to <cTAKES_HOME>. Run the command:

ant testrun

This will set the Java runtime classpath and bring up the UIMA CAS Visual Debugger (CVD). Once that is up you can proceed just like the section about under Eclipse called Proces a sample clinical note.

Process a collection of documents

Processing text by cutting and pasting into a GUI like the CAS Visual Debugger is not going to be sufficient for real work. The underlying framework, UIMA, provides the Collection Processing Engine (CPE) to process multiple documents at once. Here we take you through a sample of processing a list. For your production work you will need to have access to clinical documents of your own.

Step

Example

1. Launch the Collection Processing Engine (CPE).
Run > Run Configurations...

No example for this step

2. Expand Java Applications and select UIMA_CPE_GUI--clinical_documents_pipeline
Click Run.

(for command line compile) Use the ant target testcpe to launch the CPE, for example:
ant testcpe

screenshot to illustrate step

3. This will bring up the Collection Processing Engine Configurator. In the Menu bar click File > Open CPE Descriptor

!UserWinLaunchCPE.PNG

alt="screenshot to illustrate steps"

4. Navigate to the example file:
<cTAKES_HOME>/clinical documents pipeline/desc/collection_processing_engine/test1.xml
and click the Open button.

screenshot to illustrate step

5. Click the Play button (green/blue play arrow near the bottom).

screenshot to illustrate step

6. You should see that one document was processed. You did process a collection of documents. In this case the collection only contained one just to show how to do it. Close the results window.

screenshot to illustrate step

7. Close the CPE application. You may be prompted to save changes. Since this was just a test you may click the No button.

screenshot to illustrate step

8. Open a new command prompt and change to the <cTAKES_HOME>/utils/bin directory

No example for this step

9. To test the results (which you can not see using the CPE) there is a comparison tool that will help show that the results match expectations with the following syntax:
java edu.mayo.bmi.utils.xcas_comparison.Compare <First File> <Second File> <diff-html>

Where:
<First File> is the first file to compare
<Second File> is the second file to compare
<diff-html> is where the results are written to

Copy and paste the example at the right which has had our example files already substituted into a command prompt to run.

Windows


Linux

10. The resulting file will open for you. Look at the comparison to see the annotations resulting from this pipeline.

Windows c:\stuff\diff-html.html

Linux /tmp/diff-html.html

screenshot to illustrate step.

Optional components may have already been downloaded in the cTAKES install section. If you choose to skip the optional components during the cTAKES install and you want to install them now, please go back to the cTAKES install section for instructions on doing so and then return here.

You can test any of the components now just as we did in the #Process a sample clinical note or #Process a collection of documents section using the CVD or CPE. Follow the same steps as those, but use a test file from any other component. You can launch these from Eclipse or the command line.

Most components will have an analysis engine like to load like:

<cTAKES_HOME>/<component name>/desc/analysis_engine/<CVD file>

and a CPE directory like:

<cTAKES_HOME>/<component name>/desc/collection_processing_engine/<CPE files>

For example:

Test the dependency parser:

<cTAKES_HOME>/dependency parser/desc/analysis_engine/ClearParserPlaintextAggregate.xml

cTAKES_HOME>/dependency parser/desc/collection_processing_engine/ClearParserTestCPE.xml

Test Drug NER:

<cTAKES_HOME>/Drug NER/desc/analysis_engine/DrugAggregatePlaintextProcessor.xml

cTAKES_HOM>/Drug NER/desc/collection_processing_engine/DrugNER_PlainText_CPE.xml

Next steps

Refer to CTAKES 1.2.1 Install Dictionaries.

Labels
  • None