If you cannot install Annotald locally (or otherwise feel motivated to do so), you can use Annotald on a server to which you have ssh access. In order to do so, you will need to follow these instructions:

The instance of Annotald you start on the remote server will be accessible to other users on the server, who can (in principle) connect to the running server using their own SSH tunnel just as you can. If you do not trust the other users on the SSH server, you should not be running Annotald on it. Accidents are also a danger. Be careful that you do not inadvertently connect to someone else’s instance of Annotald! You may inadvertently save over their work.

It is recommended that Annotald users have a full-sized mouse with at least two buttons. Because of Annotald’s heavy reliance on mousing, neither a laptop trackpad nor a single-button mouse will prove satisfactory from an ergonomic point of view.

The mouse serves to select nodes in the UI. Click anywhere in the box corresponding to a node in order to select it. The horizontal mouse motion necessary can be reduced by clicking on the left edge of the node; the left side of each node’s box is padded in order to facilitate this. An example of a selected node is shown here, notice that the selected node has been highlighted in blue:

Up to two nodes may be selected at a time. If a node is selected, clicking another node will also highlight that node:

Further clicks after two nodes are selected will de-highlight the previous second selection, and highlight the clicked node. To clear any selection in effect, use the space bar.

Selected nodes form the basis for many keyboard commands. Node selection is also the basis of movement commands, of a certain type. The mouse is used for movement commands that edit the structure of the tree. In order to annotate movement in the sense of linguistic movement (wh-movement, etc.), see the leafAfter and leafBefore functions.

In order to move a selected node, right click on the desired destination. Movements must satisfy certain structural conditions (e.g. a node cannot be moved into its own daughter) as well as extrinsic conditions (no movement operation may change the text of the sentence, e.g. by reordering two words). Assuming these conditions are met, the movement operation will take place. Right clicking with two selected nodes will move those nodes, as well as any intervening material, to the desired destination. The two selected nodes must be sisters of each other.

Moving an empty category (for example a trace) behaves interestingly, since it is not treated as part of the file’s text by Annotald. This allows some interesting and confusing movement possibilities. Thus, moving empty categories (traces beginning with *, empty nodes which are 0, and CODE nodes) by default is not allowed. However, moving a non-terminal dominating only such a node(s) is. So if you need to move an empty node in a pinch, just create an XP dominating it, do your movement operation, and delete the XP. Do not be upset though if this procedure results in interesting behavior (you can always use undo to get back to a sensible structure).

Control-clicking on a node will create and select a new XP dominating that node.

Right-clicking a node when no selection is present will summon the context menu, which is illustrated here:

The context menu has three columns. The first has suggested label changes for the node; clicking any of these will change the node’s label to the chosen option. The second contains options for adding a sister before the node; clicking any of these will insert a node with the given label and text. The third column contains options for toggling certain dash tags.

The context menu can be dismissed by left-clicking outside of it.

Annotald operations other than movement are controlled by the keyboard. Annotald users should keep their right hand on the mouse at all times; thus, only keys on the left hand side of the keyboard are used as key shortcuts (with a small number of exceptions for commands which require full keyboard use).^[3]

Generally speaking, Annotald key commands perform annotation operations related to a single goal. One key, for example, toggles between the tags for different kinds of argument NPs. For more on the default keybindings, including their organizing principles, or on customizing the key commands to fit your annotation needs, see the linked sections.

When invoked via the command line, there are several options which can be passed to Annotald to affect its behavior. These are:

There are two files which are relavant to the customization of Annotald: settings.js and settings.py. The former is written in Javascript, and contains the bulk of Annotald’s user interface settings. The latter is written in Python, and (generally speaking) contains customizations that are very pervasive or advanced. A basic version of both files is included in the Annotald package.

In order to customize these files, the user should first extract a copy thereof. An auxiliary script is provided for this purpose. Execute the following commands in your OS shell to obtain copies of each of these files:

$ annotald-aux cat-settings-js > my-settings.js
$ annotald-aux cat-settings-py > my-settings.py

You can now edit the files my-settings.js and my-settings.py, using the instructions given below. These files may be placed anywhere on your hard drive, as long as you provide the correct path to the customized file(s) using the -s and -S command line options.

Javascript customization options

In this section, the options in settings.js will be discussed.

logDetail

This variable should be a Boolean value (true or false). It controls the operation of the time logging function.

displayCaseMenu

Whether or not to display options for changing the case of items in the context menu. See the discussion of this feature below

caseTags

A list of the labels which can receive a tag indicating their case. Generally speaking, these will be leaf nodes. Although an entire NP (for example) might be said to have case, the only surface reflexes of case are the marking of individual words. Furthermore, within a single NP it is possible for some constituents to not express the phrase’s features.^[4]

Therefore, the minimal annotation that captures the linguistic facts places case on the leaf nodes; phrasal case can be calculated based on that information. However, Annotald provides functions to make this less tedious – to allow the annotator to mark a whole NP for case, and have that information updated on all the relevant subconstituents of that NP.

casePhrases

A list of phrasal categories that bear case. These will provide an option in the context menu to set their case (which actually sets the case of their subconstituents).

caseMarkers

A list of case markers. Each of these is a dash tag (given in the Javascript file without surrounding dashes) that may be attachedto a member of caseTags to indicate its case.

caseBarriers

A list of phrases which should form barriers to recursive case assignment. When case is assigned to an NP, Annotald looks (recursively) for all its daughters which are case-marker-bearing, and changes their case. But, this process should not recurse into e.g. a relative clause, or a genitive possessor. Thus, any node in this list will block further case-setting traversal.

	The variables caseTags, casePhrases, and caseBarriers cannot contain dashes; they must be genuine top-level category labels.

testValidPhraseLabel/testValidLeafLabel

See the discussion of these options below

extensions

Specify the list and order of dash tags available in the corpus. There are three variants of this variable:

• leaf_extensions: Dash tags applicable to leaf (terminal) nodes
• clause_extensions: Dash tags applicable to clausal nodes (of category CP or IP)
• extensions: Dash tags applicable to non-clausal non-leaf nodes

Not every dash tag needs to appear in this list, only those which need to be toggled on and off in a binary fashion. Thus, for example, the dash tag OB1 (for direct objects) is never toggled in a binary fashion, but rather as part of a cycle that includes setting the category to NP and moving through NP-SBJ, NP-OB2, etc. Thus, it need not appear in this list. However, the SPE dash tag (for reported speech) is toggled on and off – changing an IP-XXX to IP-XXX-SPE, and potentially back to IP-XXX.

ipnodes

A list of categories which are clauses. These are highlighted (with a tan shade) to make it clear where the “floor” of a clause is, for the purpose of rearranging nodes in the user interface.

commentTypes

Types of comments. Comments are nodes of the form (CODE {XXX:words_words_words}) For every value of “XXX” is in this list, when editing the contents of the comment with the editing function, a dialog box will appear allowing the comment to be edited as text, instead of the default editing interface.

customCommands

A Javascript function containing code to configure the keybindings. This should be a series of calls to the addCommand function.

defaultConMenuGroup

The label suggestions to display in the context (right-click) menu, when no suggestion can be deduced from the already-present label.

customConMenuGroups

a Javascript function to configure the context menu suggestions. This should be a series of calls to the addConMenuGroup function.

customConLeafBefore

a Javascript function to configure the new node options in the context menu. This should be a series of calls to the addConLeafBefore and addConLeafAfter functions.

Color schemes

In the javascript settings file, you may also place calls to the styleTag and styleDashTag functions. These allow you to specify alternate colors for certain nodes in the corpus. As their names suggest, styleTag operates on category-level tags, whereas styleDashTag operates on dash tags. The first argument of the function is the tag to apply a style to. The second is a sequence of CSS rules.

A full explanation of CSS is beyond the scope of the present document. Suffice it to say that CSS consists of a sequence of rules of the form key: value;. Two keys relevant for present purposes are color and background-color, which set the text and backgroudn color, respectively. The value for the color can be a color name from this list, or a specification of the form #RRGGBB. RR here represents a 2-digit hexadecimal (i.e. base 16) number giving the intensity of the red component of the color; GG and BB give green and blue intensities respectively. The following Javascript will, when placed in the settings.js file, give all verbal tags a green background, and make all -SBJ elements appear in red text:

styleDashTag("SBJ", "color:red;");

_.each(["BE","DO","HV","VB"], function (tag) {
    styleTag(tag,       "background-color:green;");
    styleTag(tag + "D", "background-color:green;");
    styleTag(tag + "P", "background-color:green;");
})

Note the use of a looping construct to decrease the amount of boilerplate needed when styling all the forms of the verbal tag. The results of inserting this snippet in a settings file are shown here:

Users who know how to write their own CSS rules may do so using the colorCSS functionality. Annotald maintains the label of a node as part of the CSS class attribute. You will probably need to write fairly complex selectors for this; see the source for the style(Dash)Tag functions for inspiration.

The Annotald keybindings provided by default are adapted from those used by the IcePaHC project. It is highly recommended that users make a copy of this file in the working directory for their corpus, and customize it to their needs. The procedure to do so is described in the following section. The default keybindings are as follows (from left to right and top to bottom of a US keyboard layout):^[5]

It is virtually certain that users will want to adapt the default key bindings, to adapt the tags used and the most common use patterns of the annotators. It is possible to merely change the specific tags used while maintaining the default conceptual categories (argumental NP, non-sentential IP, etc.); it is also possible to come up with an entirely new scheme. The default bindings do not use the shift or control modifiers, which opens up a large space of additional keys for user customization.

The keybindings of Annotald are customized by placing calls to the addCommand function inside the customCommands block. This function has 2 required arguments; any further arguments are determined by the command being bound. The first argument to the function should be a Javascript dictionary (also known as an object). This has the format {key: value, key2: value2}. The following keys are recognized:

The ctrl and shift options are mutually exclusive.

The second argument to the addCommand function is the name of the function which the key will be bound to. Any further arguments will be passed to the function given. A list of functions provided by Annotald follows:

Annotald supports showing only a limited number of trees at a time in the browser interface. Some people find that annotating in this manner feels more natural. In order to activate this feature, pass the -n command line option to Annotald, followed by a number indicating how many trees to show at a time. As a shortcut for -n 1, you can also use -1 (in both cases, the last character is the numeral one).

When this mode is active, Annotald will have a “previous tree,” “next tree,” and “goto tree” button; the latter of which operates based on the index shown in the left-hand menu. This appears as in the following screenshot:^[6]

Annotald supports keeping a log of actions that you take in the program. This log is stored in a non-user-readable file called annotaldLog.shelve in the directory from which Annotald is invoked.^[7] There are three levels of logging possible:

The “major event logging” setting records when the program is opened and closed, as well as when the file is validated or saved. That is, it records events visible to the Annotald server. It does not record any actions taken in the browser. Full logging, on the other hand, records clicks.

Each event has associated with it a timestamp, which is recorded as seconds since the Unix epoch. Currently, the only way to analyze this data is by converting it to CSV format and importing it into another analysis program such as R. In the future, Annotald will offer built-in ways of generating reports from this data, such as how much annotation time has been spent on each file, or (with full logging enabled) which keys are most often pressed.

Annotald includes support for manipulating case marking information in corpora which store that information in a supported format. In order to be supported, the case must:^[8]

Then, some options need to be set in the configuration file. Once this is done, the context menu will contain options for setting case:

Invoking the context menu on an individual case-bearing node (one of caseTags) will allow that node’s case to be changed individually. Invoking it on a case-bearing phrase (one of casePhrases) will change the case of all that node’s case-bearing daughters, without recursing too deeply.

Annotald has a structural search engine built in. While it cannot replicate the flexibility or (perhaps especially) speed of a dedicated search program such as CorpusSearch, it is useful to be able to search within the Annotald interface itself. The search dialog is accessed by clicking the “Search” button in the Tools menu, or by pressing the forward slash (/) key. Within the dialog box, you will construct a visual representation of your query, similar to the representation of trees in the Annotald interface.

The simplest query tree contains only one leaf node. The leaf has a text box, into which the search string can be entered. The string is interpreted as a case-insensitive Javascript regular expression. The Javascript regular expression format is very similar to that used by many programming languages. A full description of the format is outside the scope of this document, but is available via this reference manual. The leaf also has a drop-down box, which indicates whether the search string is to match against the node labels, the text of the corpus, or the lemmata. The search string is additionally left-anchored – that is, the beginning of the regular expression is constrained to match the beginning of a node label or word. Pressing the “Search” button will execute the search. Matches will be highlighted with a yellow box, and the document will be scrolled to display the next match. A very simple query and its result is illustrated in the following screenshots:

Once the search has completed, two buttons will appear below the “Search” button. The first of these scrolls the document down to display the next match. The second removes teh hithlighting from serach matches.

In addition to the search node where text can be entered, there is a node consisting only of a plus sign (“+”). Clicking this node adds a sister to the search node. Search nodes which are sisters are interpreted as the (unordered) sisterhood relation. An example of such a search is given in the following two screenshots:

Each search node has some buttons in the upper-right hand corner. From left to right, these are:

The hierarchy of a node may be collapsed, for example to facilitate the editing of the clause-level structure in the presence of large amounts of structure inside NPs. When collapsed, a node’s text (including traces and empty categories) is displayed in the node, separated by spaces. The syntactic labels inside the node are not displayed. The usual blue and grey colors of the node’s border are replaced by purple, to indicate that collapsing is in effect.

By default, Annotald does not contain a mechanism to ensure that tags created through editing conform to any sort of schema. At the same time, there are various parts of Annotald’s code that would benefit from knowing whether a node corresponds to a leaf or not, which is not always a purely structural decision (for example, a node of the form (NP-SBJ *pro*) is structurally a leaf, but in fact corresponds to a phrasal node, an NP). Supplying this information to Annotald improves its functioning, as well as preventing nonsense tags from being added to the corpus during editing.

You can do this however you like – the only requirement that Annotald imposes is that you assign to the configuration variables testValidLeafLabel and testValidPhraseLabel Javascript functions that return true iff its argument is a valid label for a leaf node or phrase node (respectively). One useful way of doing this is described below.

It is possible to write a grammar to validate tags. Just as the grammar of a natrual language accepts only those sentences which are well-formed in that language, this grammar should accept only the tags which are valid in a particular corpus. In particular, this manual will describe how to use the Waxeye Parser Generator to do so. In addition to being Free Software, this program uses a relatively intuitive notation for its grammars. Additionally, it can generate grammars not only in Javascript, but also in Python and several other computer languages. This allows the same grammar specification to be used in Annotald as well as in a validation script for the corpus.

Grammars written in waxeys consist of a series of rules. The first rule in the file constitutes the grammar – it must match. A rule has the form name <- content. The name of a rule can consist of letters, numbers, and underscores. The content of the rule can be as follows:

Comments are enclosed in /* ... */.

Using these rules, it is possible to build up a grammar. As an illustration, here is a grammar that matches the tagset from the PPCEME (without, for simplicity, the numbered word splitting).

word_tag <-
/*  */
 ( verbal | nominal | punct | other_word | fn_cat )

nominal <-
/*              */
 ('NUM' ?'$') | ('N' ?'PR' ?'S' ?'$') | ('ADJ' ?('R' | 'S')) | 'D' |
 ('PRO' ?'$') | ('Q' ?('R' | 'S' | '$'))

verbal <-
 verb | verb_modifier

verb <-
/*  */
 (('DO' | 'BE' | 'HV' | 'VB') ?('D' | 'P' | 'N' | 'I')) |
 (('D' | 'B' | 'H' | 'V') 'A' ('G' | 'N')) |
 ('MD' ?'0')

verb_modifier <-
 ('ADV' ?('R' | 'S')) | 'NEG'

punct <-
/*  */
 '\'' | '"' |',' | '.' | '`'

fn_cat <-
 'C' | 'CONJ' | 'P' | ('W' ('ADV' | 'D' | ('PRO' ?'$'))) |
 'INTJ' | 'ALSO' | 'ELSE' | 'EX' | 'FP' | 'RP' | 'LB' | 'LS' |
 'MAN' | 'ONE' | ('OTHER' ?'S' ?'$') | 'SUCH' | 'TO' | 'WARD'

other_word <-
 'CODE' | 'FW' | 'X' | 'FP' | 'META'

Annotald includes a feature that allows the user to interactively submit the contents of a file to a separate program, and receive feedback from that program. This system is (intentionally) very powerful – the external program can be any Python function,^[10] and the feedback comes in the form of that function modifying the file contents; these modified file contents replace the original file in the Annotald interface. It is hoped that this flexibility will facilitate a wide variety of automated workflows.

	This feature presently causes all undo history to be erased when the file is sent for validation.

One conventionalized way of using this facility is to perform validation queries on the file – queries that will find anomalous structures, and flag them for annotator attnetion.^[11] In this section, we will discuss setting up such a system, using CorpusSearch queries.

The specification of validation queries involves customizing the Python settings file. An annotated example of such a file is given immediately below.

import os.path
current_dir = os.path.dirname(os.path.abspath(__file__)) # 

from collections import OrderedDict # 

validators = OrderedDict([
    ("Example 1", corpusSearchValidate(current_dir + "/example1.q")), # 
    ("Example 2", corpusSearchValidate(current_dir + "/example2.q"))
])

The corpusSearchValidate function takes one argument, giving the path to a CorpusSearch query file. It then arranges to run this query on the file, and return the modified output. The CorpusSearch program is distributed with Annotald; however, this facility relies on a Java executable being installed on your machine. You can test this by opening a command prompt and typing java followed by a carriage return. You should see a usage message from the java program; if you instead receive an error message the java program is not installed and/or accessible.

By convention, the validator should add the -FLAG dash tag to trees which are anomalous. The “Next Error” button in the Annotald interface will allow you to jump to the next flagged tree in the file. You can also attach a keybinding to the nextValidationError function, if you would like to use the keyboard for this purpose. The program removes any =-FLAG=s when the file is saved and when submitting it to the validator.

When validators are specified, the Annotald interface shows the “Validate” and “Next Error” buttons as well as the validator selection menu in the “Tools” section of the left-hand column, as shown in the below image:

The example given above assumes that two CorpusSearch query functions are present in the same directory as the Python file. For more information about writing CorpusSearch queries, consult the user’s guide, esepcially (for present purposes) the section on automated corpus revision which tells how to make changes to the input. As an example, the following CorpusSearch revision query adds a -FLAG to all NPs:

node: $ROOT

query: {1}NP* exists

append_label{1}: -FLAG

If run in the Annotald interface, it produces this result:

Because the settings.js file is interpreted as unrestricted Javascript in the Annotald UI, it can be the vehicle for powerful customizations. Annotald includes the jQuery and Underscore.js libraries, meaning that you can use functions from either of these libraries in customization code. The details of these libraries are beyond the scope of the current document. As an overview, Annotald maps nodes in a parsed file to nodes in the DOM. Using jQuery’s DOM manipulation functions (which are what Annotald itself uses internally), it is possible to create custom functions that are powerful and mnemonic.

For more information on Annotald’s API, consult the API documentation.

What follows is an annotated example of a custom function. It forms a CONJP semi-automatically. Specifically:

function autoConjoin() {
    if (!startnode) return; // 
    if (!endnode) { // 
        var savestartnode = startnode;
        var selnode = $(startnode); // 
        var label = getLabel(selnode);
        if (!label.startsWith("IP") &&
            !label.startsWith("CP")) { // 
            label = label.split("-")[0];
        }
        var conjnode = selnode.children(".CONJ").first(); // 
        if (conjnode) {
            startnode = selnode.children().first().get(0); // 
            endnode = conjnode.prev().get(0);
            makeNode(label);
            startnode = conjnode.get(0);
            endnode = selnode.children().last().get(0);
            makeNode("CONJP");
            var conjpnode = $(startnode);
            startnode = conjpnode.children().get(1);
            endnode = conjpnode.children().last().get(0);
            makeNode(label);
            startnode = savestartnode; // 
            endnode = undefined;
            updateSelection();
        }
    } else { // 
        var s = $(startnode);
        var l = getLabel(s);
        if (s.nextUntil(endnode).filter(".CONJ").size() > 0 && // 
            s.end().children().filter(function () {
                return !guessLeafNode($(this));
            }).size() == 0) {
            makeNode(l);
        }
    }
}