j TLEX : a J ava Library for T ime L ine EX traction (2023)

Abstract: jTLEX is a programming library that provides a Java implementation of the TimeLine EXtraction algorithm (TLEX; Finlayson et al.,2021), along with utilities for programmatic manipulation of TimeML graphs. Timelines are useful for a number of natural language understanding tasks, such as question answering, cross-document event coreference, and summarization & visualization. jTLEX provides functionality for (1) parsing TimeML annotations into Java objects, (2) construction of TimeML graphs from scratch, (3) partitioning of TimeML graphs into temporally connected subgraphs, (4) transforming temporally connected subgraphs into point algebra (PA) graphs, (5) extracting exact timeline of TimeML graphs, (6) detecting inconsistent subgraphs, and (7) calculating indeterminate sections of the timeline. The library has been tested on the entire TimeBank corpus, and comes with a suite of unit tests. We release the software as open source with a free license for non-commercial use.

## introduction timeml is a standardized temporal annotation scheme for annotating temporal information in texts @xcite . timeml annotations can be used to build temporal graphs, where nodes are events and temporal expressions (i.e., times), and edges are temporal relations. timeml annotations can be generated using automatic analyzers @xcite , manual annotation @xcite , or some combination of the two. while temporal graphs derived from texts can be deeply informative, they usually only encode partial orderings of events and times. for many nlp tasks such as text summarization and visualization @xcite , question-answering @xcite , and knowledge representation @xcite , a total order of all events and times (i.e., a timeline) is often more useful. unfortunately, timelines are rarely explicit in texts and usually cannot be read off from texts directly. there have been a few prior attempts to extract timelines from temporal graphs, however, these works have certain limitations: they do not handle all timeml relations, they do not separate "real-life" events and subordinated events, and they do not deal with multiple possible temporal orders. these problems were addressed by an approach called tlex @xcite . tlex presented a csp-based solution that extracts exact timelines from a timeml graph. tlex also detects inconsistent timeml subgraphs as well as temporal indeterminacy. tlex is a formally correct method and the experimental evaluation on four different timeml corpora showed that it has 100% accuracy for extracting timelines @xcite . tlex has been used for several nlp tasks such as corpus validation, evaluating temporal dependency parsers, and narrative representation @xcite . to enable better access to this approach for the community, we have implemented jtlex, an open-source java implementation of tlex for other researchers in the field to use. we present jtlex in this paper. we have tested jtlex on the entire timebank corpus @xcite which is a reference corpus for timeml that contains 183 timeml annotated news articles. for each file, jtlex took no longer than 1 second to extract all timelines on a currently available, standard consumer laptop (3.0 ghz intel core i7-1185g7 with 32gb of ram) our demonstration system as well as a screencast video demonstrating our system is available foot_0 . ## use cases a user guide and license information can be found on the jtlex website foot_1 . here we illustrate an approach for one of the timeml annotations of the timebank corpus, called wsj_0006.tml. this file and the rest of the corpus can be obtained from ldc website foot_2 . the following text shown in example (2), is a snippet of the timeml-annotated text of wsj_0006.tml. the timeml graph corresponding to the snippet text is shown in figure 1 , where we can see that the nodes of the graph are either events or times, and the edges are timeml relations. event instance ids and timeids are given in square brackets (@xmath0. users can read the file and create the timeml graph as follows: here, fname is the path to the file. users can retrieve any information about the graph such as links (all or one by id), nodes (all or one by id), incoming links, outgoing links, json output, number of nodes, number of links, number of link types, etc. using the following code, users can retrieve the information of the first link: system . out . print ( graph . getlinkbyid (1) ); the output will be as shown in listing 1. as can be seen, jtlex provides all the available information in the timeml annotation about the link and its components using the timeml parser. after the timeml graph is created, users can create a tlex object to perform the timeline extraction including partitioning, transforming, solving, inconsistency detection (if the graph is inconsistent), and temporal indeterminacy. creating the tlex object is as follows: users, can retrieve the exact trunk-and-branch timeline structure using: tlex . gettimeline () ; the output will be as shown in listing 2. as can be seen, jtlex returns the main timeline, subordinated timelines, and the attachment points for each subordinated timeline. listing 3: jtlex inconsistent subgraph output for the wsj_1011.tml file. since the graph of wsj_0006.tml is consistent, jtlex's inconsistency detection method returns an empty set. we illustrate the inconsistency detection algorithm using a temporally inconsistent file from the timebank corpus, called wsj_1011.tml. after running the method for graph construction and creating the tlex object, users can simply call the method tlex.getinconsistentsubgraphs() and retrieve the inconsistent cycle. for this file, jtlex returns the output show in listing 3. as can be seen from the output, jtlex returns the inconsistent subgraph along with the information about the subgraph. ## related work as we discussed in section 1, timeml is a standardized temporal markup language in the nlp community. therefore, many tools have been de-veloped for timeml-related tasks. we can classify existing timeml tools into two categories: producing timeml annotations and analyzing timeml annotations. nlp researchers have concentrated tools of the first type, in particular for both full automatic timeml annotation-such as tarsqi @xcite , cleartk @xcite , and caevo @xcite -and tools of the automatic annotation of sub-parts of timemlsuch as evita @xcite and navytime @xcite for event detection, gate-time @xcite and sutime (chang and manning, 2012) for temporal expression recognition, and catena @xcite and lcc-te @xcite for temporal relation extraction. there are only a small number of tools that evaluate timeml annotations. tango is a java timeml parser tool to parse the timeml annotated documents and create a timeml graph @xcite . tango allows users to modify the graph and it checks the temporal consistency of the graph using temporal closure. tango was used to evaluate the timebank corpus, however, tango did not report any inconsistency on the timebank files. using @xmath1, tango displays the graph in a timeline form, where each section contains @xmath2, however, it doesn't provide the global order of events. similarly, tbox @xcite also generates a timeml graph from a timeml annotation, but it further removes the temporal closure links to display a simplified timeml graph. tbox displays each event in a box shape and places each box based on the temporal relation to present the timeline (e.g., if event a is before event b, then box-a would be on the left of box-b). however, this representation could be problematic considering temporal indeterminacy is already high in timeml annotations. timeml-strict is a java validation tool that parses timeml annotations and validates them whether they follow strict timeml annotation guide rules @xcite . it also fixes missing document creation time (dct) @xmath3. cavat is a python tool that parses timeml annotations and prints out the quantitative results such as distributions of the timeml objects @xcite . further, it detects self-loops as well as disconnectivity in the timeml graphs. cavat detects the temporal inconsistency of the graph using inconsistent disclosure. if the graph is inconsistent, it returns the last added constraint to the inconsistent cycle. determining the entire inconsistent cycle based on one edge is very difficult for the annotators considering the graph size. cavat detects 30 inconsistent files in the timebank corpus. however, cavat's inconsistency detection algorithm only deals with tlinks and ignores alinks and slinks. later, @xcite showed that by taking alinks into consideration, the timebank corpus actually has 65 inconsistent files. in addition to these timeml tools, nlp researchers have also developed ml-based approaches to extract timelines from timeml annotations @xcite @xcite . however, these approaches have certain limitations such as they do not deal with all temporal links (at most 6 out of 13), they do not distinguish the real-life events and subordinated events, and they do not handle temporal indeterminacy. unlike other tools and approaches, in this work we provide an open-source implementation of tlex, a method for extracting exact timelines from a timeml annotation. like prior approaches, tlex-and by extension, jtlexoffers a timeml parser and a graph constructor. however, it goes further by separating subordinated events from real-life events, presenting the global order of events and times in a novel trunk-andbranch timeline structure, detecting inconsistencies automatically and helping users to fix them, representing multiple different orders in a single timeline, and measuring the indeterminacy score. ## discussion we perform an extensive evaluation of the tlex algorithm using the jtlex output in our forthcoming paper @xcite . we perform sampling evaluation using simple random sampling @xcite , which allows us to check the correctness of a specific feature of a set of n members randomly selected from a population with size n to obtain an estimate of the correctness of that feature over all the data. sampling evaluation shows that jtlex achieved 100% accuracy on time point ordering and indeterminacy identification with 95% confidence @xcite . because jtlex can detect temporal errors in the annotations and measure temporal indeterminacy, it can be used to evaluate automatic timeml tools and manual timeml annotations. an example of using jtlex to evaluate automatic timeml annotators can be found in @xcite , and for using it to evaluate gold-standard timeml annotations, see @xcite . ## conclusion we presented jtlex, an open-source java library that, for the first time, allows the programmatic extraction of exact timelines from timeml annotated texts using a standard java api. jtlex provides many useful methods for the timeml community such as timeml parsing, graph extraction, timeline extraction, inconsistency detection, and temporal indeterminacy calculation. jtlex can for used on any timeml annotations in any domain of natural language. we release jtlex as an open source library that is free for non-commercial use 4 .