The Stanford Natural Language Processing Group home · people · teaching · research · publications · software · events · local

About

SUTime is a library for recognizing and normalizing time expressions. SUTime is available as part of the Stanford CoreNLP pipeline and can be used to annotate documents with temporal information. It is a deterministic rule-based system designed for extensibility.

SUTime was developed using TokensRegex, a generic framework for definining patterns over text and mapping to semantic objects. An included set of powerpoint slides and the javadoc for SUTime provide an overview of this package.

SUTime was written by Angel Chang. These programs also rely on classes developed by others as part of the Stanford JavaNLP project.

There is a paper describing SUTime. You're encouraged to cite it if you use SUTime.

Angel X. Chang and Christopher D. Manning. 2012. SUTIME: A Library for Recognizing and Normalizing Time Expressions. 8th International Conference on Language Resources and Evaluation (LREC 2012).

Usage

SUTime annotations are provided automatically with the StanfordCoreNLP pipeline by including the ner annotator. When a time expression is identified, the NamedEntityTagAnnotation is set with the temporal type (DATE, TIME, DURATION) and the NormalizedNamedEntityTagAnnotation is set to the value of the normalized temporal expression. The temporal type and value corresponds to the TIMEX3 type and value.

SUTime also sets the TimexAnnotation key to an edu.stanford.nlp.time.Timex object, which contains the complete list of TIMEX3 fields for the corresponding expressions, such as "val", "alt_val", "type", "tid". This might be useful to developers interested in recovering complete TIMEX3 expressions.

There is also a stand-alone SUTimeMain class for invoking SUTime. It can read certain temporal text data sets and can annotate text files. It is mainly intended for validating the performance of SUTime.

SUTime Rules

1. Create rules file (see SequenceMatchRules for format of the rule file).
   Example: Sample English rules for SUTime are included in the distribution (sutime/defs.sutime.txt, sutime/english.sutime.txt)
   
2. Configure the rules to be used by SUTime:

   sutime.rules = [path to rules file] 

   Example:
   

   sutime.rules = sutime/defs.sutime.txt, sutime/english.sutime.txt 

SUTime Annotator

1. Create rules file (see SequenceMatchRules for format of the rule file).
   Example: Sample English rules for SUTime are included in the distribution (sutime/defs.sutime.txt, sutime/english.sutime.txt)
   
2. Configure the TimeAnnotator

   customAnnotatorClass.[name]=edu.stanford.nlp.time.TimeAnnotator
   [name].rules = [path to rules file] 

   Example:
   

   customAnnotatorClass.sutime=edu.stanford.nlp.time.TimeAnnotator
   sutime.rules = sutime/defs.sutime.txt, sutime/english.sutime.txt 

3. Add the annotator to the pipeline
   Example: java -cp stanford-corenlp-2012-05-22.jar:stanford-corenlp-2012-05-22-models.jar:xom.jar:joda-time.jar -Xmx3g edu.stanford.nlp.pipeline.StanfordCoreNLP -annotators tokenize,ssplit,pos,lemma,ner,sutime -properties sutime.properties -file input.txt

Using SUTime to annotate a file with TIMEX3 tag

Download

SUTime is integrated in the Stanford suite of NLP tools, StanfordCoreNLP. Please download the entire suite from this page.

Questions

Questions, feedback, and bug reports/fixes can be sent to our mailing lists.

Mailing Lists

We have 3 mailing lists for SUTime, all of which are shared with other JavaNLP tools (with the exclusion of the parser). Each address is at @lists.stanford.edu:

1. java-nlp-user This is the best list to post to in order to ask questions, make announcements, or for discussion among JavaNLP users. You have to subscribe to be able to use it. Join the list via this webpage or by emailing java-nlp-user-join@lists.stanford.edu. (Leave the subject and message body empty.) You can also look at the list archives.
2. java-nlp-announce This list will be used only to announce new versions of Stanford JavaNLP tools. So it will be very low volume (expect 1-3 messages a year). Join the list via this webpage or by emailing java-nlp-announce-join@lists.stanford.edu. (Leave the subject and message body empty.)
3. java-nlp-support This list goes only to the software maintainers. It's a good address for licensing questions, etc. For general use and support questions, you're better off joining and using java-nlp-user. You cannot join java-nlp-support, but you can mail questions to java-nlp-support@lists.stanford.edu.

Online Demo

We have an online demo of SUTime.

Release History