py TLEX : A Python Library for T ime L ine EX traction (2024)

Abstract: pyTLEX is an implementation of the TimeLine EXtraction algorithm (TLEX; Finlayson et al.,2021) that enables users to work with TimeML annotations and perform advanced temporal analysis, offering a comprehensive suite of features. TimeML is a standardized markup language for temporal information in text. pyTLEX allows users to parse TimeML annotations, construct TimeML graphs, and execute the TLEX algorithm to effect complete timeline extraction. In contrast to previous implementations (i.e., jTLEX for Java), pyTLEX sets itself apart with a range of advanced features. It introduces a React-based visualization system, enhancing the exploration of temporal data and the comprehension of temporal connections within textual information. Furthermore, pyTLEX incorporates an algorithm for increasing connectivity in temporal graphs, which identifies graph disconnectivity and recommends links based on temporal reasoning, thus enhancing the coherence of the graph representation. Additionally, pyTLEX includes a built-in validation algorithm, ensuring compliance with TimeML annotation guidelines, which is essential for maintaining data quality and reliability. pyTLEX equips researchers and developers with an extensive toolkit for temporal analysis, and its testing across various datasets validates its accuracy and reliability.

## introduction temporal information plays a crucial role in natural language processing and text analysis. timeml, an sgml-based markup language, allows the annotation of temporal information in texts, including events, temporal expressions, links, and temporal signals @xcite foot_0 . timeml annotations can be generated using automatic analyzers @xcite , manual annotation @xcite , or some combination of the two. timeml annotations can be used to build temporal graphs, where nodes are events and temporal expressions, and edges are temporal relations. however, they provide only a partial ordering of events and times. meanwhile, the global order (i.e., a timeline) is more useful for various nlp applications, including question-answering systems @xcite , text summarization @xcite , and text visualization @xcite . to effect the extraction of timelines from timeml annotations, we previously developed the tlex algorithm, based on constraint satisfaction problems (csp), which provides an exact solution to the problem (in contrast to machine-learningbased approaches). tlex converts timeml annotations into an exact timeline, and in previous work, we introduced jtlex, an open-source java library, which implemented the tlex algorithm @xcite . jtlex not only parsed timeml annotations but also allowed users to manipulate timeml graphs. like jtlex, pytlex also takes a timeml annotated file as input, then (1) parses the annotations into timeml objects, (2) builds a timeml graph, (3) partitions the timeml graph into temporally connected graphs to separate real-life events and subordinated events, (4) transforms the temporally connected graphs into point algebra (pa) graphs, and (5) solves the pa graphs to extract a timeline. if a timeline cannot be extracted, meaning the graph is temporally inconsistent, (6) it detects the minimum inconsistent subgraph and returns it to the annotator to fix it. finally, if the order of events and times are indeterminant (multiple possible ordering), (7) it calculates the temporal indeterminacy. pytlex goes beyond jtlex and introduces several new features. it includes a react-based application for graph and timeline visualization, making the exploration of temporal data more intuitive and insightful. the library incorporates an algorithm for automatically increasing connectivity, which detects graph disconnectivity and automatically suggests temporal links. additionally, pytlex offers a rule-based system for validating compliance with the annotation guidelines. we have tested pytlex on the timebank corpus @xcite , which contains 183 timeml annotated news articles. in less than 9 minutes on current consumer laptop (3.0 ghz intel core i7-1185g7 with 32gb of ram), pytlex validated the annotations, extracted timelines, and visualized them. we release our demonstration system as well as a screencast video showing its operation 2 . ## use cases a user guide and license information can be found on the pytlex website foot_2 . here, we illustrate an approach for one of the timeml annotations of the timebank corpus, called wsj_0555.tml. this file and the rest of the corpus can be obtained from the ldc website foot_3 . the following text, shown in the example below, is a snippet of the timemlannotated text of wsj_0555.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: moreover, users can actively manipulate their graph by adding or removing nodes and links or even constructing entirely custom graphs. the following code snippet demonstrates the process of creating a customized graph and adding two new nodes along with a link. @xmath1, " future_ref " , true , " next wednesday ") @xmath2, " future_ref " , true , " next thursday " ) @xmath3, " tlink " , " before " , node1 , node2 ) @xmath4. add ( node1 ) timeml_nodes . add ( node2 ) timeml_links . add ( link1 ) @xmath5, timeml_links ) after the timeml graph is created, users can perform timeline extraction. accessing the graph's partitions can be achieved as follows: as can be seen from figure 1 , this timeml graph has disconnectivity. pytlex can automatically propose a link based on the values of t12 (10/30/1989) and t10 (03/15/2007) through the use of the algorithm for increasing connectivity. consequently, pytlex suggests the link "t12 -before-> t10" to the user. users have the option to incorporate this suggested link, thereby achieving a fully connected graph and, by extension, a fully connected timeline: 1 main timeline : { 2 eiid46 -= 1 3 eiid46 + = 2 4 eiid48 -= 3 5 eiid44 -= 3 6 eiid44 + = 4 7 eiid48 + = 4 8 t12 -= 5 9 t12 + = 6 10 eiid45 -= 6 11 t10 -= 7 12 eiid45 + = 8 13 t10 + = 8 14 } 15 attachment points : { eiid46 -> eiid47 , eiid48 -> eiid49 } 16 subordinated timelines : { 17 [ eiid47 -= 1 , eiid47 + = 2] , 18 [ eiid48 -= 1 , eiid48 + = 2]} listing 2: pytlex timeline output for the wsj_0555.tml file. @xmath6. links connectivity_increaser . connect_partitions ( partitions , len ( links ) ) now that we have the fully connected graph, we can extract the timeline. users, can retrieve the exact trunk-and-branch timeline structure using: ## related work as we discussed in section 1, timeml is a standardized temporal markup language. while numerous tools have been created for generating timeml annotations, including @xcite @xcite @xcite @xcite , there are only a small number of tools designed to evaluate timeml annotations. tango, a java-based timeml parser tool, can parse timeml annotated documents and construct timeml graphs @xcite . it offers users the ability to modify the graph and conducts temporal consistency checks using temporal closure. tango was used in the evaluation of the time-bank corpus, although it did not flag any inconsistencies within the timebank files. notably, tango @xmath7, where each segment encompasses @xmath8. however, it does not furnish the global ordering of events. similarly, tbox @xcite can create a timeml graph from timeml annotations but eliminates temporal closure links. tbox presents each event in this simplified graph as a box and positions these boxes based on their temporal relations, arranged according to their temporal order. this approach presents challenges with temporally indeterminate annotations. @xcite evaluated of the initial version of the timebank corpus, denoted as timebank 1.1. they analyzed the distribution of relations, event classes, timex types, and timeml components. notably, their findings revealed that the annotation tool employed in the construction of timebank introduced a consistent shift of a single character. additionally, they identified discrepancies in the types of timex tags or instances of missing timex tags associated with the same timex signal in timebank 1.1. @xcite extended their analysis to timebank 1.2, enabling a comparative assessment. they selected a random document from both corpora and manually evaluated it to ascertain the number of errors in each version. their results suggest that timebank 1.2 represented a notable improvement over 1.1. timeml-strict is a java-based validation tool for timeml @xcite . it implements a range of criteria, including the identification of any missing document creation time (dct), the verification of non-linguistic content, and the confirmation that all links reference existing objects. cavat is a python utility for parsing timeml annotations and providing quantitative insights, including distributions of timeml objects @xcite . it offers functionality to detect self-loops, orphaned nodes, and disconnectivity within timeml graphs. cavat @xmath9, which can result in subordinated events being erroneously identified as orphaned objects and subgraphs being marked as disconnected, despite their connectivity @xmath10. cavat can identify temporal inconsistencies within the graph using closure. when temporal inconsistencies are present, cavat returns the most recently added constraint to the inconsistent cycle, which is important because identifying the complete inconsistent cycle based on a single edge can be particularly challenging for annotators, especially in the context of large graphs. in addition to these timeml tools, nlp researchers have used machine learning-based techniques for timeline extraction from timeml annotations @xcite @xcite . these approaches come with specific constraints, and none of them address all temporal links, covering a maximum of 6 out of the 13 types. additionally, they fail to distinguish between real-life events and subordinated events, and they may not effectively handle temporal indeterminacy within the annotations. in contrast to prior work, pytlex provides an open-source implementation of tlex, a technique for extracting exact timelines from timeml annotations. like its predecessor, jtlex, pytlex incorporates a timeml parser and a graph constructor. it distinguishes subordinated events from realworld events, extracts the global order of events and times in a trunk-and-branch timeline structure, automatically identifies and rectifies inconsistencies, and identifies and gauges indeterminacy. however, pytlex has a number of extended capabilities. it not only detects and resolves disconnectivities within both graphs and timelines but also integrates a validation system for timeml annotations. additionally, it offers a visualization system, enhancing comprehension for users. ## conclusion we present pytlex, an open-source python library that enables the programmatic extraction of exact timelines from timeml-annotated texts via a standard python api. pytlex provides several capabilities, including timeml parsing, graph extraction, timeline generation, inconsistency identification, temporal indeterminacy assessment, disconnectivity detection and resolution, corpus validation, and advanced visualization capabilities. we release pytlex as an open-source library, freely available for non-commercial usage 7 .