Finding Time Expressions


ClarityNLP includes a module that locates time expressions in clinical text. By ‘time expression’ we mean a string such as 9:41 AM, 05:12:24.12345, or something similar. The TimeFinder module scans sentences for time expressions, extracts them, and generates output in JSON format.

Source Code

The source code for the time finder module is located in nlp/algorithms/finder/


A single string, the sentence to be scanned for time expressions.


A JSON array containing these fields for each time expression found:

Field Name Explanation
text string, text of the complete time expression
start integer, offset of the first character in the matching text
end integer, offset of the final character in the matching text plus 1
hours integer hours
minutes integer minutes
seconds integer seconds
fractional_seconds string, contains digits after decimal point, including any leading zeros
am_pm string, either STR_AM or STR_PM (see values below)
timezone string, timezone code
gmt_delta_sign sign of the UTC offset, either ‘+’ or ‘-’
gmt_delta_hours integer, UTC hour offset
gmt_delta_minutes integer, UTC minute offset

All JSON results contain an identical number of fields. Any fields that are not valid for a given time expression will have a value of EMPTY_FIELD and should be ignored.


ClarityNLP uses a set of regular expressions to recognize time expressions. The time_finder module scans a sentence with each time-finding regex and keeps track of any matches. If any matches overlap, an overlap resolution process is used to select a winniner. Each winning match is converted to a TimeValue namedtuple. This object is defined at the top of the source code module and can be imported by other Python code. Each namedtuple is appended to a list as the sentence is scanned. After scanning completes, the list of TimeValue namedtuples is converted to JSON and returned to the caller.

Time Expression Formats

Using notation similar to that used by the PHP time reference, as well as the Wikipedia article on ISO 8601 formats, we define the following quantities:

Shorthand Meaning
h hour digit, 0-9
h12 12 hr. clock, hours only, 0-9
h24 24 hr. clock, hours only, zero-padded, 00-24
m minutes digit, 0-9
mm minutes, zero-padded, 00-59
ss seconds, zero-padded 00-60 (60 means leap second)
am_pm am or pm designator, can be am or pm, either lower or upper case, with each letter optionally followed by a . symbol
t either t or T
f fractional seconds digit
? optional
utc_time hh, hh:mm, hhmm, hh:mm:ss, hhmmss, hh:mm:ss.ffffff, hhmmss.ffffff

With these definitions, the time expression formats that ClarityNLP recognizes are:

Time Expression Format Examples
utc-timeZ 10:14:03Z
utc_time+-hh:mm 10:14:03+01:30, 10:14:03-01:30
utc_time+-hhmm 10:14:03+0130, 10:14:03-0130
utc_time+-hh 10:14:03+01, 10:14:03-01
YYYY-MM-DDTHH:MM:SS(.ffffff)? 1969-07-20T10:14:03.123456
(here MM:SS means minutes and seconds)  
h12 am_pm 4 am, 5PM, 10a.m., 9 pm.
h12m am_pm 5:09 am, 9:41 P.M., 10:02 AM.
h12ms am_pm 06:10:37 am, 10:19:36P.M., 1:02:03AM
h12msf 7:11:39:012345 am, 11:41:22.22334 p.m.
h12m 4:08, 10:14, and 11:59
t?h24m 14:12, 01:27, 10:27, T23:43
t?h24ms 01:03:24, T14:15:16
t?h24msf 04:08:37.81412, 19:20:21.532453, 08:11:40:123456
t?hhmm 0613, t0613
t?hhmmss 232120, 120000
t?h24ms with timezone abbreviation 040837CEST, 112345 PST, T093000 Z
t?h24ms with GMT offset T192021-0700, 14:45:15+03:30

A list of world time zone abbreviations can be found here. ClarityNLP supports this list as well as Z, meaning “Zulu” or UTC time.