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 
@ECHO OFF

::   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 
@ECHO OFF

::   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 
@ECHO OFF

::   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 
@ECHO OFF

::   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" ]; then
  echo "Adding -h will also add unofficial components"
  exit
fi

cd $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"
  fi
done
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 
@ECHO OFF

::   Sets up the standard environment for cTAKES.
::   This script is called by cTAKES run scripts.
:: Requires Java 17

:: Guess CTAKES_HOME if not defined
set CURRENT_DIR=%cd%
if not "%CTAKES_HOME%" == "" goto gotHome
set CTAKES_HOME=%CURRENT_DIR%
if exist "%CTAKES_HOME%\bin\runClinicalPipeline.bat" goto okHome
cd ..
set CTAKES_HOME=%cd%

:gotHome
if exist "%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
@set PATH=%PATH%;%CTAKES_HOME%\lib\auth\x64
@REM use JAVA_HOME if set
if exist "%JAVA_HOME%\bin\java.exe" set PATH=%JAVA_HOME%\bin;%PATH%

set CLASS_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"
set PIPE_RUNNER=org.apache.ctakes.core.pipeline.PiperFileRunner
set PIPE_RUNNER_GUI=org.apache.ctakes.gui.pipeline.PiperRunnerGui
set DICT_DOWNLOADER=org.apache.ctakes.gui.dictionary.DictionaryDownloader

set FAST_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