Adelheid 1.0 Annotation Tool Manual. Introduction

Size: px

Start display at page:

Download "Adelheid 1.0 Annotation Tool Manual. Introduction"

Randolf Williamson
6 years ago
Views:

1 Adelheid 1.0 Annotation Tool Manual Introduction Adelheid is tagger-lemmatizer system for historical Dutch, available through the Clarin infrastructure. Its output is in an XML format, which, although ideal for interchange, is not easily readable by humans. For this reason Adelheid comes accompanied by a visualization and annotation tool, allowing the user to inspect and, in the future, adjust Adelheid s output. NOTE: We have discovered a deep bug in Version 1.0 which seriously damages the data when specific adjustments to the output are attempted. For that reason we advise to use version 1.0 as a visualization tool only. We will report on the Adelheid website when an updated version become available. In this manual we explain how to use the annotation, starting with an explanation of file formats and then going through the process of using the system step by step. The manual is accompanied by several further manuals: The Adelheid 1.0 Tagger-Lemmatizer Manual, explaining how the Adelheid itself can be used to process texts. The Adelheid 1.0 Tagset Manual, explaining how the tags and lemmas added by the system should be interpreted. The Adelheid 1.0 Demonstrator Scenario Manual, showing several examples of the use of the system.

2 Input and Output File Formats Introduction The file format used by the annotation tool, both for input and output, is the same as that of the output of the Adelheid system, i.e. the filename_atl.xml files. For completeness, we duplicate the format description here. File Format An Adelheid document file is an XML file showing the tags and lemmas added to the tokens in the text: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE adelheid-document [... ]> <adelheid-document> <teiheader>... </teiheader> <body> <manuscript name="p065p34101.st.goedele.pet r.hand58" manid="1"> <sep TPos="1/0" MSep="True" MForm="O" TSep="True" ASep="True" Src="sys" Conf="1.0000"></sep> <token TForm="allen" Tag="Num(indef,formn)" Lemma="al" TPos="1/0-4" MForm="Allen" AForm="allen" Src="sys" Conf="0.4816"> <tlp PTag="Num(indef,formn)" PLemma="al" PProb="0.4816"></tlp> <tlp PTag="Pron(rel,formn)" PLemma="al" PProb="0.2511"></tlp> <tlp PTag="Adv(gener)" PLemma="alleen" PProb="0.0959"></tlp> <tlp PTag="N(prop,formn)" PLemma="ale" PProb="0.0510"></tlp> <tlp PTag="Num(card,formn)" PLemma="al" PProb="0.0486"></tlp> <tlp PTag="N(prop)" PLemma="halen" PProb="0.0290"></tlp> <tlp PTag="Pron(indef,formn)" PLemma="al" PProb="0.0183"></tlp> <tlp PTag="Adj(formn)" PLemma="al" PProb="0.0183"></tlp> <tlp PTag="Pron(indef,formn)" PLemma="alles" PProb="0.0061"></tlp> </token> <sep TPos="1/5" MSep="True" MForm=" " TSep="True" ASep="True" Src="sys" Conf="0.9991"></sep> <token TForm="den" Tag="Art(def,formn)" Lemma="de" TPos="1/5-7" MForm="den" AForm="den" Src="sys" Conf="0.4163"> <tlp PTag="Art(def,formn)" PLemma="de" PProb="0.4163"></tlp> <tlp PTag="Adp()+Art(def,formn)" PLemma="dat+de" PProb="0.1247"></tlp> <tlp PTag="Art(def)+Adj()" PLemma="de+een" PProb="0.1182"></tlp> <tlp PTag="Art(def,formn)" PLemma="dat" PProb="0.1003"></tlp> <tlp PTag="N(sing)" PLemma="deken" PProb="0.0956"></tlp> <tlp PTag="Num(ord,formn)" PLemma="d" PProb="0.0537"></tlp> <tlp PTag="Adv(dem)" PLemma="dan" PProb="0.0457"></tlp> <tlp PTag="Pron(dem,formn)" PLemma="die" PProb="0.0327"></tlp> <tlp PTag="Pron(rel,formn)" PLemma="die" PProb="0.0128"></tlp> <tlp PTag="Art(def,formn)" PLemma="die" PProb="0.0001"></tlp> </token>... </manuscript> <manuscript name="p065p34103.st.goedele.pet r.hand52" manid="2">... </manuscript>... </body> </adelheid-document> Following the DTD and the TEI header, we find a number of <manuscript> elements, each marked for its name and consisting of a series of <sep> elements and <token> elements. The <sep> elements represent the separators that were a) in the manuscript (indicated by the attribute MSep), b) proposed by the transcriber (indicated by the attribute TSep) and/or c) proposed by Adelheid (indicated by the attribute ASep). The attribute TPos shows where in the manuscript the separator is placed. The attribute MForm shows which forms the separator takes in the actual

3 manuscript. The value of MForm will be clear in most cases, except for the value O, which represents a position Outside the manuscript, i.e. before the first or after the last token. The attribute Src shows whether the separator element was created by the system (sys) or during postprocessing (man) with the Adelheid annotation tool. The attribute Conf shows, on a scale from 0 to 1, how certain Adelheid was that there should be an actual separator here. The <token> elements represent the tokens that Adelheid assumes constitute the text. Their attributes show the most likely interpretation of what each token s properties are: TForm. The form found in the transcription. Tag. The wordclass tag assigned to the token. See the Adelheid Tagset Manual for an explanation of the value of this attribute. Lemma. The (modern) lemma assigned to the token. TPos. The position in the input, with the number before the slash indicating the manuscript s position within the input file and the number after the slash indicating the token position within the manuscript. MForm. The form actually present in the manuscript. This may differ in e.g. the presence of unreadable characters or the use of abbreviation marks. AForm. The form used by the system for processing. This may differ e.g. because the system maps j to i and v to u for processing. Src. As for separators, Src has the value sys if Adelheid set the attributes and the value man if the attributes were adjusted in manual postprocessing. Conf. Conf indicates, on a scale of 0 to 1, what Adelheid considers to be the probability of the selected tag and lemma. Each <token> element also contains a series of <tlp> elements. These list all tag/lemma alternatives that Adelheid considered in its processing, down to those having an estimated probability of Each <tlp> has the attributes Atag, Alemma and Aprob, representing the alternative tag, alternative lemma and the probability of that tag/lemma combination. The <tlp> elements are used by the Adelheid annotation tool to provide likely alternatives to the annotator to choose from.

4 The Adelheid Annotation Tool Introduction The Adelheid annotation tool is available as a webapplication at In order to get access to this, you must be a user in one of the institutions listed when you attempt to reach this address. If your institution is in the list, you select it and then provide your username and password that you use inside your own institution. Once through authentication, you can use the webapplication to provide input files, view and possibly adjust them with the annotation tool and download the adjusted results. Getting permission for access If your institution is not in the list, you can also apply for a so-called homeless account. An official procedure for obtaining such an account is still being developed. However, for now, we advise you to go to and apply for a Clarin account there (even if you are not part of an institution that is a Clarin member and do not want to join a Working Group). The username and password for that account can also be used to access Clarin services like Adelheid.

5 Uploading, inspecting and downloading your annotated files You enter the annotation tool in your own workspace (Figure 1). 1 Here you can either upload a new document, open a document for viewing/annotation or download adjusted documents. Figure 1: Documents in your work space 1 As of the writing of this manual, authentication was not yet working perfectly. Depending on conditions as yet unknown, users either get their own workspace or a shared workspace. In case you are making use of the shared space, please mark your files clearly, e.g. by including your name in the filename. We will be looking into the problem.

6 Uploading You can upload a document by clicking the Upload button in Figure 1. This will open an additional window (see Figure 2) in which you can choose a document through a file selection dialogue and activate upload. The Adelheid output file that you should choose here is the one of type filename_atl.xml. Afterwards, the uploaded document is in the system s database and visible in your document list. Figure 2: Uploading a new document Viewing and Adjusting In order to access a document through the annotation tool, click on the document name in the document list (Figure 1). This will open the document and give you access to the functionality described in the next sections. Downloading In order to download an adjusted document back to your own machine, click on the download link next to the document s name in the document list (Figure 1).

7 Viewing annotated text The annotation tool allows editing only on one manuscript at a time. Therefore, its presentation is split in two layers: a) the document and its contents and b) an individual manuscript and its full text. Selecting a manuscript When entering a document, you first come to the manuscript list (Figure 3). On the left, you find a list of all manuscripts present in the document; you can open a manuscript for actual viewing by clicking on the link next to the name. On the right, you can search inside the manuscripts in the document; this functionality is described in a separate section below. Figure 3: The manuscripts in your document

Viewing a manuscript After opening a manuscript, you see the situation in Figure 4. The main part of the screen is filled with the text of the manuscript, initially only the tokens.

8 Viewing a manuscript After opening a manuscript, you see the situation in Figure 4. The main part of the screen is filled with the text of the manuscript, initially only the tokens. At the top left, you can see in which document you are. Next to it are navigation options to other manuscripts: previous, next and a drop down menu. 2 Further to the right, you can choose between text view (this screen) and matrix view (see below). On the next line, you can return to your workspace, log out or adjust the view options. 3 Figure 4: Initial view of a manuscript 2 Note that the name shown when entering is not necessarily the name of the manuscript that is currently open. We will be examining whether the menu can be manipulated in such a way that the current manuscript name is being shown. However, we expect the adjustment to become active only in a later version of the tool. 3 We have observed that in some browsers, these links are only visible when the right font size has been selected. If you do not see them, try zooming in or out.

When clicking the latter link (View options), you can select which information elements you wish to see (Figure 5): Show lemmas. Shows most likely lemma next to each token. Show tags.

9 When clicking the latter link (View options), you can select which information elements you wish to see (Figure 5): Show lemmas. Shows most likely lemma next to each token. Show tags. Shows most likely full tag next to each token. Show truncated tags. As Show tags, but leaves out attributes and shows only POS. Show tool tips. Shows full information, including probability, when moving mouse over a token. Precede search matches sign. Marks matches for the currently active search. Note that you can use the full functionality of your browser in the annotation tool views, e.g. search (usually ctrl-f) for specific strings in the window. So searching after a manuscript search will allow you to find all matches in the current manuscript. Figure 5: Selecting view options

10 Selecting the options as shown in Figure 5 will lead you to the situation similar to the one shown in Figure 6. Now each token (here black) is linked on the next two tiers to a lemma (green) and full tag (brownish). You can zoom in and out with your browsers zoom controls until the font size and screen layout is most comfortable for you. Figure 6: Text view with lemmas and tags

In case you would like to see from which potential tags and lemmas Adelheid selected the current combination (and also all their estimated probabilities), click on a token and then drop down the menu

11 In case you would like to see from which potential tags and lemmas Adelheid selected the current combination (and also all their estimated probabilities), click on a token and then drop down the menu marked as apply any of the alternative tags. This will show you a list as in Figure 7. Figure 7: All potential tags/lemmas for a token At this point, please refrain from trying out any of the other buttons. First read the section on adjusting annotation below.you can leave this window by clicking on the top right corner.

The second view provided by the annotation tool is the so-called matrix view (Figure 8). The columns from left to right are: The form as provided by the transcriber. (Token) The most likely tag.

12 The second view provided by the annotation tool is the so-called matrix view (Figure 8). The columns from left to right are: The form as provided by the transcriber. (Token) The most likely tag. (Token) The most likely lemma. (Token) Whether the token separation is actually present in the manuscript. (Separator) Whether the token separation is present according to the transcriber. (Separator) Whether the token separation is present according to Adelheid / the annotator. (Separator) The form as actually present in the manuscript. (Token) The position in the manuscript. (Both) Whether the current annotation has been provided by the system of by a human annotator.(both) The confidence in the current annotation, expressed as a number between 0 and 1. (Both) Whether the current token is a match for the currently active manuscript search, as described below. (Token) Figure 8: Matrix view of annotated text Although the matrix view provides much more information about each token, the text view allows you to see more text at the same time. The Filter box allows you to see only lines containing a specific string. However, as there is no possibility to limit the string match to particular columns, filtering is currently not optimal.

13 Adjusting annotations WARNING: we have observed that Version 1.0 of the annotation tool contains one or more bugs that can seriously damage your documents. They are activated (in a manner as yet unclear) by using the more advanced annotation functions. We therefore advise you strongly to refrain from using these functions. We also will not describe these functions in detail in this version of the manual. What appears to be safe is changing the annotation of a token by selecting an alternative tag/lemma combination from the list provided as in Figure 7. You can adjust the most likely tag/lemma combination for a token by first accessing the list of alternative tags/lemmas, as shown in Figure 7 above. You then select the alternative you prefer from the list by clicking on the corresponding line in the list. Then you close the edit window by clicking in the top right corner of the window. 4 When you return to the normal view, your selected alternative has replaced the previously most likely tag and lemma. Changes are permanent. There is no undo function. Also, the changes are applied immediately in the document as present in the annotation tool database. You do not have to save your document. You can download your adjusted document at any time as described above and we advise you to do so regularly if you are changing the annotation so you have a backup in case of serious mistakes (or further bugs). It is also wise to use some kind of versioning system in your filenames, in case you note a serious mistake only after several downloads. Returning to a previous version is possible by uploading the correct version using the same filename as the corrupted document. 4 The explicit closing is needed as, in principle, multiple changes could be affected. However, as already explained, other changes are not safely possible at the moment.

14 Search The annotation tool also allows you to search for tokens containing or associated through their annotation with specific strings. WARNING: Searching for a pattern which is very frequent, e.g. any token with the tag V, may well lead to so many matches that the annotation tool becomes so slow that it cannot be used sensibly anymore. Please consider this before activating the search function. A search pattern consists of one or more criteria. The system starts with one criterion and a link is present to add more (Figure 9). Figure 9: Specifying a search criterion For each criterion, you can specify Which part of the information for each token should be matched. This can be selected with a drop down menu which gives the options: o Form. The form of the token. o Tag. The most likely tag. o Lemma. The most likely lemma. o Conf. The confidence in the choice for this tag and lemma. o Atag. Other potential tags for this token. (Useful for correcting systematic tagging errors.) o Alemma. Other potential lemmas for the token. Which string should match that information. The interpretation of the string depends on which information is matched: o Conf. The string should be an operator such as < or >, followed by a space and then followed by a number.

o Other than Conf. The string is a regular expression describing part of the information field. The example search is for all tokens for which the most likely lemma ends in huis.

15 o Other than Conf. The string is a regular expression describing part of the information field. The example search is for all tokens for which the most likely lemma ends in huis. After the search is activated, you will be shown how many manuscripts in your document contain matches and all matches found (Figure 10). Figure 10: Search results at document level

16 To see individual matches, you have to open the corresponding manuscripts. In the views there, the matches will be highlighted (Figure 11). Also, if you selected the marking of matches you can use the search-on-page function of your browser to easily jump to each match. Figure 11: Search results inside a manuscript

17 Appendix: DTD In this appendix, we list the DTD for the files that are output by Adelheid and can be used as input for the annotation tool. Note that the TEI header is not described in detail here; the Adelheid software does not need a detailed DTD for this. <!DOCTYPE adelheid-document [ <!ELEMENT adelheid-document (teiheader,body)> <!ELEMENT teiheader (#PCDATA)> <!ELEMENT body (manuscript+)> <!ELEMENT manuscript ((line sep token)*)> <!ATTLIST manuscript name CDATA #IMPLIED> <!ATTLIST manuscript manid CDATA #REQUIRED> <!ELEMENT line (#PCDATA)> <!ELEMENT sep (#PCDATA)> <!ATTLIST sep TPos CDATA #REQUIRED> <!ATTLIST sep MSep (True False) #REQUIRED> <!ATTLIST sep TSep (True False) #REQUIRED> <!ATTLIST sep ASep (True False) #REQUIRED> <!ATTLIST sep Src (sys usr) "sys"> <!ATTLIST sep MForm CDATA #REQUIRED> <!ATTLIST sep Conf CDATA "1.0"> <!ELEMENT token (tlp*)> <!ATTLIST token TPos CDATA #REQUIRED> <!ATTLIST token AForm CDATA #REQUIRED> <!ATTLIST token TForm CDATA #REQUIRED> <!ATTLIST token MForm CDATA #REQUIRED> <!ATTLIST token Tag CDATA "???"> <!ATTLIST token Lemma CDATA "???"> <!ATTLIST token Src (sys usr) "sys"> <!ATTLIST token Conf CDATA "1.0"> <!ELEMENT tlp (#PCDATA)> <!ATTLIST tlp PTag CDATA "???"> <!ATTLIST tlp PLemma CDATA "???"> <!ATTLIST tlp PProb CDATA #REQUIRED> ENTITY LIST INSERTED HERE ]>

Function. Description

Function. Description Function Check In Get / Checkout Description Checking in a file uploads the file from the user s hard drive into the vault and creates a new file version with any changes to the file that have been saved.