############
Introduction
############

MedTime is an Apache UIMA based temporal information extraction system developed by the Mayo Clinic NLP program. It extracts and normalizes TIMEX3-based temporal expressions from clinical text. MedTime has been adapted from the open-source temporal tagger, HeidelTime (http://code.google.com/p/heideltime/) but reengineered toward the clinical domain.

 ########################################
 Sub directories included in MedTime v1.0
 ########################################
 
 javasrc - source folder includes java source codes distributed
 autosrc - source folder automatically generated by JCas_gen for the centralized type system 
 descsrc - contains types and primitive analysis engines, collection readers, and cas consumers (not recommended to modify if you have limited knowledge with respect to UIMA)
 desc - example descriptors for aggregate analysis engines and collection processing engines
 medtaggerdescsrc -- source folders contains types and primitive analysis engines, collection readers, and cas consumers in MedTagger
 lib - a collection of libraries that MedTagger is based on
 resources - resources required to run MedTime (including those for running MedTagger)
 testdata - shipped test data to run all annotators
 
 
##########################
Installation and Execution
##########################

Java requirement: Java 1.7 minimum
An UIMA is included in the package.

To install, download distribution and unzip the package 

To execute MedTime for a collection of documents, simply go to MedTime installation home 
and run runMedTimeCVD.bat (runMedTimeCVD.sh) or runMedTimeCPE.bat (runMedTimeCPE.sh)
 which will test processable analysis engines and collection processing engines.

In Windows:
>java -Xms512M -Xmx2000M -cp resources;desc;descsrc;medtaggerdescsrc;MedTime-1.0.2.jar org.apache.uima.tools.cvd.CVD
>java -Xms512M -Xmx2000M -cp resources;desc;descsrc;medtaggerdescsrc;MedTime-1.0.2.jar org.apache.uima.tools.cpm.CpmFrame
 
In Unix/Linux:
>java -Xms512M -Xmx2000M -cp resources:desc:descsrc:medtaggerdescsrc:MedTime-1.0.2.jar org.apache.uima.tools.cvd.CVD
>java -Xms512M -Xmx2000M -cp resources:desc:descsrc:medtaggerdescsrc:MedTime-1.0.2.jar org.apache.uima.tools.cpm.CpmFrame

It will fire up UIMA Cas Visual Debugger (CVD) or the collection processing engine (CPE) GUI. 

To visualize a specific aggregate engine through CVD, go to load AE under the Run menu,  choose 
$MedTimeHOME/desc/medtimedesc/aggregate_analysis_engine/MedTimeAggregateTAE.xml. Then click Run MedTimeAggregateTAE. The extracted TIMEX3 expressions can be found under org.ohnlp.medtime.type.MedTimex3.

To process a collection of documents, go to the FILE menu and open the corresponding CPE descriptor file 
available in $MedTimeHOME/desc/collection_processing_engine

#############################
MedTime v1.0 UIMA descriptors
#############################

Primary Annotators
	MedTimeAE.xml: finds temporal expressions and normalizes them according to the TIMEX3 TimeML annotation standard

Cas Consumer
	MedTimeWriter.xml: generates i2b2 Timex3 output format

Aggregate TAE
	MedTimeAggregateTAE.xml 
	
Collection Processing Engine
	MedTimeCPE.xml 

###########################
MedTime v1.0 UIMA resources
###########################

resources/medtimeresources/i2b2/normalization
- normalized forms of time expression

resources/medtimeresources/i2b2/repattern
- regular expressions of time information

resources/medtimeresources/i2b2/rules
- rules to extract date, time, duration, and frequency

resources/medtimeresources/used_resources.txt
- all paths used in resources

The detailed explanation of resource usage can be found in HeidelTime Wiki (http://code.google.com/p/heideltime/wiki/HowToWriteResources)

########
Citation
########

If you use MedTime, please cite the following paper.
Sohn S, Wagholikar KB, Li D, Jonnalagadda SR, Tao C, Komandur Elayavilli R, Liu H. "Comprehensive temporal information detection from clinical text: medical events, time, and TLINK identification" J Am Med Inform Assoc. 2013 Sep 1;20(5):836-42.