ctakes pbj

A Python Bridge to Java (PBJ).

Problem Statement

Solutions start with identifying the problem. Our problem is the lack of a standardized path to move information from cTAKES to a python program (and back again). Having that ability is very important as most modern Machine Learning is done in Python.

Solution

The information that we want to move is stored in an object called a CAS (Common Analysis System). All objects within the CAS are of a Type defined in an extensible Type System. For instance a discovered instance of "cancer" is stored in the CAS as an object of Type "DiseaseDisorderMention".

The next step was for us to choose a method of delivery for our path of information. We were looking for something that could handle multiple sub-pipelines, allow for parallel sub-pipelines, and a method that is fast, reusable, and easy to use.

Apache ActiveMQ Message Broker combined with dkpro-cassis became apparent as the ideal solution to our problem, allowing what we hoped for above and more.

How it Works

Other Configurations

Annotation Engines
Utilities
Piper Files

---

Annotation Engines

PbjReceiverAE

Annotation Engine wrapper for the PbjReceiver.

Source class: PbjReceiverAE
Source package: org.apache.ctakes.pbj.ae
Parent class: org.apache.uima.fit.component.JCasAnnotator_ImplBase

Parameter	Description	Class	Required	Default
ReceiveQueue	The Artemis Queue from which this pipeline receives information.	String	Yes
AcceptStop	Yes to shut down when this pipeline receives a stop signal.	String	No	yes
ReceiveHost	The Artemis Host from which this pipeline receives information.	String	No	localhost
ReceiveName	Your Artemis Username.	String	No	guest
ReceivePass	Your Artemis Password.	String	No	guest
ReceivePort	The Artemis Port from which this pipeline receives information.	int	No

---

Utilities

ArtemisStarter

Starts an Apache Artemis broker.

Source class: ArtemisStarter
Source package: org.apache.ctakes.pbj.ae
Parent class: org.apache.ctakes.pbj.util.ArtemisController

Parameter	Description	Class	Required	Default
ArtemisBroker	Your Artemis broker's root directory.	String	Yes
OutputDirectory	Directory for all output files.	File	Yes
LogFile	File to which cTAKES output should be sent.	String	No
Pause	Pause for some seconds. Default is 0	int	No
Wait	Wait for the process to finish. Default is no.	String	No	no

ArtemisStopper

Stops an Apache Artemis broker.

Source class: ArtemisStopper
Source package: org.apache.ctakes.pbj.ae
Parent class: org.apache.ctakes.pbj.util.ArtemisController

Parameter	Description	Class	Required	Default
ArtemisBroker	Your Artemis broker's root directory.	String	Yes
OutputDirectory	Directory for all output files.	File	Yes
LogFile	File to which cTAKES output should be sent.	String	No
Pause	Pause for some seconds. Default is 0	int	No
Wait	Wait for the process to finish. Default is no.	String	No	no

PbjJmsSender

Sends jcas to Artemis Queue using JMS

Source class: PbjJmsSender
Source package: org.apache.ctakes.pbj.ae
Parent class: org.apache.ctakes.pbj.ae.PbjSender

Parameter	Description	Class	Required	Default
SendQueue	The Artemis Queue to which this pipeline sends information.	String	Yes
QueueSize	The size of the message queue. Default is 5 messages.	int	No
SendHost	The Artemis Host to which this pipeline sends information.	String	No	localhost
SendName	Your Artemis Username.	String	No	guest
SendPass	Your Artemis Password.	String	No	guest
SendPort	The Artemis Port to which this pipeline sends information.	int	No
SendStop	Yes to send a stop signal to receiving pipelines.	String	No	yes

PbjPipper

Will pip PBJ based upon user request.

Source class: PbjPipper
Source package: org.apache.ctakes.pbj.ae
Parent class: org.apache.ctakes.core.ae.PythonRunner

Parameter	Description	Class	Required	Default
OutputDirectory	Directory for all output files.	File	Yes
Command	A full command line to be executed. Make sure to quote.	String	No
CommandDir	The Command Executable's directory.	String	No
Log	A name for the streaming logger. Default is the Command.	String	No
LogFile	File to which cTAKES output should be sent.	String	No
Pause	Pause for some seconds. Default is 0	int	No
PerDoc	yes to run the command once per document. Default is no.	String	No	no
PipPbj	pip or do not pip PBJ python code. Default is yes.	String	No	yes
VirtualEnv	Path to Python virtual environment.	String	No
Wait	Wait for the process to finish. Default is no.	String	No	no
WorkingDir	The Working Directory directory.	String	No

PbjReceiver

Populates JCas based upon XMI content read from an Artemis Queue.

Source class: PbjReceiver
Source package: org.apache.ctakes.pbj.cr
Parent class: org.apache.uima.fit.component.JCasCollectionReader_ImplBase

Parameter	Description	Class	Required	Default
ReceiveQueue	The Artemis Queue from which this pipeline receives information.	String	Yes
AcceptStop	Yes to shut down when this pipeline receives a stop signal.	String	No	yes
ReceiveHost	The Artemis Host from which this pipeline receives information.	String	No	localhost
ReceiveName	Your Artemis Username.	String	No	guest
ReceivePass	Your Artemis Password.	String	No	guest
ReceivePort	The Artemis Port from which this pipeline receives information.	int	No

PbjStompSender

Sends jcas to Artemis Queue using Stomp

Source class: PbjStompSender
Source package: org.apache.ctakes.pbj.ae
Parent class: org.apache.ctakes.pbj.ae.PbjSender

Parameter	Description	Class	Required	Default
SendQueue	The Artemis Queue to which this pipeline sends information.	String	Yes
QueueSize	The size of the message queue. Default is 5 messages.	int	No
SendHost	The Artemis Host to which this pipeline sends information.	String	No	localhost
SendName	Your Artemis Username.	String	No	guest
SendPass	Your Artemis Password.	String	No	guest
SendPort	The Artemis Port to which this pipeline sends information.	int	No
SendStop	Yes to send a stop signal to receiving pipelines.	String	No	yes

---

Piper Files

Pbj Starter

This is a piper file that will perform initial steps required for running a ctakes-pbj pipeline.

Pbj Starter

$\textcolor{gray}{\textsf{// This is a piper file that will perform initial steps required for running a ctakes-pbj pipeline. }}$
$\textcolor{gray}{\textsf{// }}$
$\textcolor{gray}{\textsf{// Add "load PbjStarter" to the beginning of your piper file. }}$
$\textcolor{gray}{\textsf{// }}$
$\textcolor{gray}{\textsf{// This piper will start the Apache Artemis broker pointed to by the -a parameter on the command line. }}$
$\textcolor{gray}{\textsf{// It will pause for 5 seconds to allow artemis to fully launch. }}$
$\textcolor{gray}{\textsf{// }}$
$\textcolor{gray}{\textsf{// This piper will then pip the python package requirements for ctakes-pbj }}$
$\textcolor{gray}{\textsf{// in an environment pointed to by the -v parameter on the command line. }}$
$\textcolor{gray}{\textsf{// }}$
$\textcolor{gray}{\textsf{// To skip the step of runnning a pip of ctakes-pbj, set --pipPbj to "no" }}$
$\textcolor{gray}{\textsf{// }}$

$\textcolor{gray}{\textsf{// Set the command line parameter -a to accept the directory of the Artemis broker. }}$
$\textcolor{brown}{\textbf{cli}}$ $\textcolor{purple}{\textbf{ArtemisBroker}}$= $\textcolor{violet}{\textsf{a}}$
$\textcolor{gray}{\textsf{// Set the command line parameter -v to accept the directory of the Python environment. }}$
$\textcolor{brown}{\textbf{cli}}$ $\textcolor{purple}{\textbf{VirtualEnv}}$= $\textcolor{violet}{\textsf{v}}$
$\textcolor{gray}{\textsf{// Set the command line parameter --pipPbj to 'no' to avoid a pip of pbj at the beginning of the run. }}$
$\textcolor{brown}{\textbf{cli}}$ $\textcolor{purple}{\textbf{PipPbj}}$= $\textcolor{violet}{\textsf{pipPbj}}$


$\textcolor{gray}{\textsf{// Write nice big banners when ctakes starts and finishes. }}$
$\textcolor{olive}{\textbf{set}}$ $\textcolor{purple}{\textbf{WriteBanner}}$= $\textcolor{violet}{\textsf{yes}}$

$\textcolor{gray}{\textsf{// }}$
$\textcolor{gray}{\textsf{// Start the Artemis broker and pause 5 seconds. }}$
$\textcolor{gray}{\textsf{// }}$
$\textcolor{gray}{\textsf{// Important: You must create an Artemis Broker before running. }}$
$\textcolor{gray}{\textsf{// See "Creating a Broker Instance" at (http)s://activemq.apache.org/components/artemis/documentation/1.0.0/running-server.html }}$
$\textcolor{gray}{\textsf{// The ArtemisBroker must point to the directory of the broker that you create. }}$
$\textcolor{gray}{\textsf{// }}$

$\textcolor{green}{\textbf{add}}$ ArtemisStarter $\textcolor{purple}{\textbf{Pause}}$= $\textcolor{violet}{\textsf{5}}$

$\textcolor{gray}{\textsf{// }}$
$\textcolor{gray}{\textsf{// pip the dependency packages in case your environment doesn't have them or needs an update. }}$
$\textcolor{gray}{\textsf{// }}$
$\textcolor{green}{\textbf{add}}$ PbjPipper

$\textcolor{gray}{\textsf{// Add the Finished Logger for some run statistics. }}$
$\textcolor{green}{\textbf{addLast}}$ $\textcolor{blue}{\textsf{util.log.FinishedLogger}}$

$\textcolor{gray}{\textsf{// Force a stop, just in case some external process is trying to stay connected. }}$
$\textcolor{gray}{\textsf{// To disable the forced exit, use "set ForceExit=no" }}$
$\textcolor{green}{\textbf{addLast}}$ ExitForcer $\textcolor{purple}{\textbf{Pause}}$= $\textcolor{violet}{\textsf{3}}$

Pbj Stopper

This is a piper file that will perform final steps required for stopping a ctakes-pbj pipeline.

Pbj Stopper

$\textcolor{gray}{\textsf{// This is a piper file that will perform final steps required for stopping a ctakes-pbj pipeline. }}$
$\textcolor{gray}{\textsf{// }}$
$\textcolor{gray}{\textsf{// Add "load PbjStopper" to the end of your piper file. }}$
$\textcolor{gray}{\textsf{// }}$
$\textcolor{gray}{\textsf{// This piper will stop the Apache Artemis broker pointed to by the -a parameter on the command line. }}$
$\textcolor{gray}{\textsf{// }}$

$\textcolor{gray}{\textsf{// Set the command line parameter -a to accept the directory of the Artemis installation. }}$
$\textcolor{brown}{\textbf{cli}}$ $\textcolor{purple}{\textbf{ArtemisBroker}}$= $\textcolor{violet}{\textsf{a}}$

$\textcolor{gray}{\textsf{// Stop the Artemis Broker }}$
$\textcolor{green}{\textbf{add}}$ ArtemisStopper

$\textcolor{gray}{\textsf{// Add the Finished Logger for some run statistics. }}$
$\textcolor{green}{\textbf{add}}$ $\textcolor{blue}{\textsf{util.log.FinishedLogger}}$

$\textcolor{gray}{\textsf{// Force a stop, just in case some external process is trying to stay connected. }}$
$\textcolor{gray}{\textsf{// To disable the forced exit, use "set ForceExit=no" }}$
$\textcolor{green}{\textbf{addLast}}$ ExitForcer $\textcolor{purple}{\textbf{Pause}}$= $\textcolor{violet}{\textsf{3}}$