Skip to content

Shell Scripts

Jump to bottom
Sean Finan edited this page Feb 9, 2026 · 1 revision

Important

Shell scripts are included in the bin/ directory of a cTAKES installation.
These scripts can ONLY be run in a cTAKES installation.
They cannot be used within a source code project.

Download the cTAKES NER Dictionary

Starts a GUI to fetch the cTAKES umls (snomed, rxnorm) dictionary.
A binary build of cTAKES does not include the cTAKES default dictionary lookup (NER) database. This script will start the cTAKES UMLS Package Fetcher GUI that allows one-click download and installation of the dictionary database.

Linux : getUmlsDictionary.sh
#!/bin/sh# Starts a simple GUI to fetch the cTAKES umls (snomed, rxnorm) dictionary.# Requires Java 17# Sets up environment for cTAKES."$(dirname "$0")/setenv.sh"cd$CTAKES_HOME
java -cp "$CLASS_PATH" -Xms512M -Xmx3g $DICT_DOWNLOADER"$@"
Windows : getUmlsDictionary.bat
@ECHOOFF:: Starts a simple GUI to fetch the cTAKES umls (snomed, rxnorm) dictionary.:: Requires Java 17:: The setenv script sets up the environment needed by cTAKES.@call %~sdp0\setenv.bat
cd%CTAKES_HOME%
java -cp "%CLASS_PATH%"%LOG4J_PARM% -Xms512M -Xmx3g %DICT_DOWNLOADER%%*cd%CURRENT_DIR%
:end

Run the Default Clinical Pipeline

This script runs the default clinical pipeline only.
To run any other pipeline, use the runPiperFile script.

Required parameters are:
-i , --inputDir {inputDirectory}
-o , --outputDir {outputDirectory}
--key {umlsKey}
Optional standard parameters are:
-s , --subDir {subDirectory} (for i/o)
--xmiOut {xmiOutputDirectory} (if different from -o)
-l , --lookupXml {dictionaryConfigFile} (fast only)
-? , --help

Linux : runClinicalPipeline.sh
#!/bin/sh# Runs the default clinical pipeline with provided parameters.# Required parameters are:# -i , --inputDir {inputDirectory}# -o , --outputDir {outputDirectory}# --key {umlsKey}# Optional standard parameters are:# -s , --subDir {subDirectory} (for i/o)# --xmiOut {xmiOutputDirectory} (if different from -o)# -l , --lookupXml {dictionaryConfigFile} (fast only)# -? , --help# Requires Java 17# Sets up environment for cTAKES."$(dirname "$0")/setenv.sh"cd$CTAKES_HOME
java -cp "$CLASS_PATH" -Xms512M -Xmx3g $PIPE_RUNNER -p $FAST_PIPER"$@"
Windows : runClinicalPipeline.bat
@ECHOOFF:: Runs the default clinical pipeline with provided parameters.:: Required parameters are::: -i , --inputDir {inputDirectory}:: -o , --outputDir {outputDirectory}:: --key {umlsKey}:: Optional standard parameters are::: -s , --subDir {subDirectory} (for i/o):: --xmiOut {xmiOutputDirectory} (if different from -o):: -l , --lookupXml {dictionaryConfigFile} (fast only):: -? , --help:: Requires Java 17:: The setenv script sets up the environment needed by cTAKES.@call %~sdp0\setenv.bat
cd%CTAKES_HOME%
java -cp "%CLASS_PATH%" -Xms512M -Xmx3g %PIPE_RUNNER% -p %FAST_PIPER%%*cd%CURRENT_DIR%
:end

Run any Pipeline

Runs any pipeline defined in a piper file, specified by -p {piperfile} with provided parameters. To run the default clinical pipeline, use the runClinicalPipeline script.

Standard parameters are:
-i , --inputDir {inputDirectory}
-o , --outputDir {outputDirectory}
-s , --subDir {subDirectory} (for i/o)
--xmiOut {xmiOutputDirectory} (if different from -o)
-l , --lookupXml {dictionaryConfigFile} (fast only)
--key {umlsKey}
-? , --help

Other parameters may be declared in the piper file using the cli command. See Piper Commands, Allowing Command Line Specification.

Linux : runPiperFile.sh
#!/bin/sh# Runs the pipeline in the piper file specified by -p {piperfile} with provided parameters.# Standard parameters are:# -i , --inputDir {inputDirectory}# -o , --outputDir {outputDirectory}# -s , --subDir {subDirectory} (for i/o)# --xmiOut {xmiOutputDirectory} (if different from -o)# -l , --lookupXml {dictionaryConfigFile} (fast only)# --key {umlsKey}# -? , --help## Other parameters may be declared in the piper file using the cli command:# cli {parameterName}={singleCharacter}# For instance, for declaration of ParagraphAnnotator path to regex file optional parameter PARAGRAPH_TYPES_PATH,# in the custom piper file add the line:# cli PARAGRAPH_TYPES_PATH=t# and when executing this script use:# runPiperFile -p path/to/my/custom.piper -t path/to/my/custom.bsv ...# Requires Java 17# Sets up environment for cTAKES."$(dirname "$0")/setenv.sh"cd$CTAKES_HOME
java -cp "$CLASS_PATH" -Xms512M -Xmx3g $PIPE_RUNNER"$@"
Windows : runPiperFile.bat
@ECHOOFF:: Runs the pipeline in the piper file specified by -p {piperfile} with provided parameters.:: Standard parameters are::: -i , --inputDir {inputDirectory}:: -o , --outputDir {outputDirectory}:: -s , --subDir {subDirectory} (for i/o):: --xmiOut {xmiOutputDirectory} (if different from -o):: -l , --lookupXml {dictionaryConfigFile} (fast only):: --key {umlsKey}:: -? , --help:: Other parameters may be declared in the piper file using the cli command::: cli {parameterName}={singleCharacter}:: For instance, for declaration of ParagraphAnnotator path to regex file optional parameter PARAGRAPH_TYPES_PATH,:: in the custom piper file add the line::: cli PARAGRAPH_TYPES_PATH=t:: and when executing this script use::: runPiperFile -p path/to/my/custom.piper -t path/to/my/custom.bsv ...:: Requires Java 17:: The setenv script sets up the environment needed by cTAKES.@call %~sdp0\setenv.bat
cd%CTAKES_HOME%
java -cp "%CLASS_PATH%" -Xms512M -Xmx3g %PIPE_RUNNER%%*cd%CURRENT_DIR%
:end

Start a Pipeline Runner GUI

Linux : runPiperGUI.sh

Starts the Piper File Submitter GUI, which can run any pipeline defined in a piper file.

#!/bin/sh# Starts a GUI that can run a pipeline.# Requires Java 17# Sets up environment for cTAKES."$(dirname "$0")/setenv.sh"cd$CTAKES_HOME
java -cp "$CLASS_PATH" -Xms512M -Xmx3g $PIPE_RUNNER_GUI"$@"
Windows : runPiperGUI.bat
@ECHOOFF:: Starts a GUI that can run a pipeline.:: Requires Java 17:: The setenv script sets up the environment needed by cTAKES.@call %~sdp0\setenv.bat
cd%CTAKES_HOME%
java -cp "%CLASS_PATH%" -Xms512M -Xmx3g %PIPE_RUNNER_GUI%%*cd%CURRENT_DIR%
:end

Create a Custom NER Dictionary

Starts the Dictionary Creator GUI, which can facilitate creation of a dictionary.
The dictionary created by the Dictionary Creator GUI contains SQL that can be used by the
ctakes-dictionary-lookup-fast module.

Linux : runDictionaryCreator.sh
#!/bin/sh## Starts a GUI that can facilitate creation of a dictionary.# The created dictionary contains SQL that can be used by the# [ctakes-dictionary-lookup-fast](ctakes-dictionary-lookup-fast) module.# Requires Java 17# Sets up environment for cTAKES."$(dirname "$0")/setenv.sh"cd$CTAKES_HOME
java -cp "$CLASS_PATH" -Xms512M -Xmx3g org.apache.ctakes.gui.dictionary.DictionaryCreator
Windows : runDictionaryCreator.bat
:: Starts a GUI that can facilitate creation of a dictionary.:: The created dictionary contains SQL that can be used by the:: [ctakes-dictionary-lookup-fast](ctakes-dictionary-lookup-fast) module.:: Requires Java 17:: The setenv script sets up the environment needed by cTAKES.@call %~sdp0\setenv.bat
cd%CTAKES_HOME%
java -cp "%CLASS_PATH%" -Xms512M -Xmx3g org.apache.ctakes.gui.dictionary.DictionaryCreator
cd%CURRENT_DIR%
:end

Create a Custom Pipeline

Starts the Simple Pipeline Fabricator GUI, which can facilitate creation of a pipeline.

Note

The Simple Pipeline Fabricator GUI is experimental. It is fully functional but has known bugs.

Linux : runPiperCreator.sh
#!/bin/sh# Starts a GUI that can facilitate creation of a pipeline.# Requires Java 17# Sets up environment for cTAKES."$(dirname "$0")/setenv.sh"
ALL_IMPL=""if [ "$1"="-a" ];then
ALL_IMPL="-Dctakes.gui.all-impls=XX"elif [ "$1"="-h" ];thenecho"Adding -h will also add unofficial components"exitficd$CTAKES_HOME
java -cp "$CLASS_PATH"$ALL_IMPL -Xms512M -Xmx3g org.apache.ctakes.gui.pipeline.PiperCreator
Windows : runPiperCreator.bat
:: Starts a GUI that can facilitate creation of a pipeline.:: Requires Java 17:: The setenv script sets up the environment needed by cTAKES.@call %~sdp0\setenv.bat
cd%CTAKES_HOME%
java -cp "%CLASS_PATH%"%ALL_IMPL% -Xms512M -Xmx3g org.apache.ctakes.gui.pipeline.PiperCreator
cd%CURRENT_DIR%
:end

Configure the cTAKES Environment

Sets up the standard environment for cTAKES. This script is called by scripts described above.

Linux : setenv.sh
#!/bin/sh# Sets up the standard environment for cTAKES.# This script is called by cTAKES run scripts.# Requires Java 17
PRG="$0"while [ -h"$PRG" ];do
ls=`ls -ld "$PRG"`
link=`expr "$ls":'.*-> \(.*\)$'`if expr "$link":'/.*'> /dev/null;then
PRG="$link"else
PRG=`dirname "$PRG"`/"$link"fidone
PRGDIR=`dirname "$PRG"`# Only set CTAKES_HOME if not already set
[ -z"$CTAKES_HOME" ] && CTAKES_HOME=`cd "$PRGDIR/..">/dev/null; pwd`
CLASS_PATH=$CTAKES_HOME/desc/:$CTAKES_HOME/resources/:$CTAKES_HOME/config/*:$CTAKES_HOME/lib/*#LOG4J2_PARM=-Dlog4j.configuration=file:$CTAKES_HOME/config/log4j2.xml
PIPE_RUNNER=org.apache.ctakes.core.pipeline.PiperFileRunner
PIPE_RUNNER_GUI=org.apache.ctakes.gui.pipeline.PiperRunnerGui
DICT_DOWNLOADER=org.apache.ctakes.gui.dictionary.DictionaryDownloader
FAST_PIPER=resources/org/apache/ctakes/clinical/pipeline/DefaultFastPipeline.piper
Windows : setenv.bat
@ECHOOFF:: Sets up the standard environment for cTAKES.:: This script is called by cTAKES run scripts.:: Requires Java 17:: Guess CTAKES_HOME if not definedsetCURRENT_DIR=%cd%ifnot"%CTAKES_HOME%"==""goto gotHome
setCTAKES_HOME=%CURRENT_DIR%ifexist"%CTAKES_HOME%\bin\runClinicalPipeline.bat"goto okHome
cd ..
setCTAKES_HOME=%cd%
:gotHomeifexist"%CTAKES_HOME%\bin\runClinicalPipeline.bat"goto okHome
echo The CTAKES_HOME environment variable is not defined correctly
echo This environment variable is needed to run this program
goto end
:okHome@setPATH=%PATH%;%CTAKES_HOME%\lib\auth\x64
@REM use JAVA_HOME if setifexist"%JAVA_HOME%\bin\java.exe"setPATH=%JAVA_HOME%\bin;%PATH%setCLASS_PATH=%CTAKES_HOME%\desc\;%CTAKES_HOME%\resources\;%CTAKES_HOME%\config\*;%CTAKES_HOME%\lib\*
REM set LOG4J_PARM=-Dlog4j.configuration="file:\%CTAKES_HOME%\config\log4j.xml"setPIPE_RUNNER=org.apache.ctakes.core.pipeline.PiperFileRunner
setPIPE_RUNNER_GUI=org.apache.ctakes.gui.pipeline.PiperRunnerGui
setDICT_DOWNLOADER=org.apache.ctakes.gui.dictionary.DictionaryDownloader
setFAST_PIPER=resources\org\apache\ctakes\clinical\pipeline\DefaultFastPipeline.piper

Apache cTAKES

Home

Pipeline Basics

Piper Files

Running Pipelines

Creating Custom Pipelines

Pipeline Components

General

Clone this wiki locally