brat rapid annotation tool manual
This document provides an introduction into the basic functionality of the brat rapid annotation tool.
(Already familiar with brat but having trouble with the tool? See troubleshooting.)
Selecting a document
When starting, brat will show the
collection browser. To open a
document, simply double-click on one of the documents
(
) in
the document selector.
To open another collection, double-click on a collection
(
).
This will update the collection browser to show the contents of
that collection.
Visualization
When a document is selected, the main window area shows a visualization of the text and annotations of that document.
Placing the mouse cursor over an annotation shows some further information about that annotation, including the full form of the annotation type, the annotation ID, and any attributes or notes attached to the annotation.
Menu
Placing the mouse cursor over the top bar of the window opens the menu, which drops down from the top of the screen.
Once the mouse pointer leaves the menu area the menu will disappear, thus allowing more screen space for the annotations by only appearing when needed.
The menu provides access to the following features:
- Collection: collection browser
- Data: export/import/modify annotation data
- Search: search current document or collection
- Options: system configuration options
- Login: log in for editing
Collection browser
The collection browser, accessible from the menu or by pressing the TAB key, allows you to access the different text collections and individual documents in those collections set up on your installation.
Collections can be organized hierarchically: a collection can contain others, similarly to a directory or folder structure on disk.
Other collections
()
are shown first in the document browser. The
entry "../" refers to the collection containing the
current one (if any).
Documents
() are
shown in the collection browser after collections. For each
document, the last modification time and simple annotation
statistics (the number of entity, relation and even annotations)
is shown.
Documents are sorted by document name by default. It is possible to sort the documents in the collection browser by other criteria by clicking on the labels in the browser header. For example, clicking once on "Entities" will sort the documents so that ones with the largest numbers of entity annotations are shown first. A second click on the same label will invert this sort order, so that for example documents with the fewest entity annotations are shown first.
Names beginning with a dot (".") will not be listed in the
collection browser. This feature can be used to create "hidden"
collections.
Logging in
To log in into the system, first click the "Login" button in the menu.
Clicking on the "Login" button brings up the login dialog.
To log in, enter a valid username and password in the login dialog. User and password settings are specific to the server configuration. If you need a new login or have forgotten your password, you should contact the administrator of your brat installation.
Basic editing
To edit annotations, users first need to log in with an account that has editing permissions.
Adding an annotation for a text span
When logged in, it is possible to add annotations for a text span simply by selecting that span with the mouse.
Selection can be performed either by "dragging" over the text or by double-clicking on a word.
A multi-word span can also be selected by clicking on
the first and last words of the span, as follows: first, hold
CTRL while double-clicking on one of the words, then release CTRL
and hold SHIFT while clicking on the other.
An empty span, i.e. a point in text not containing any characters,
can be selected by holding SHIFT while clicking on the point.
After selecting a span, the system shows the span annotation dialog.
This allows the selection of the type to assign to the newly created annotation, as well as the addition of comments or setting additional aspects of the annotation such as attribute values (if available).
If the annotation dialog fails to open when selecting text,
please first check that you are logged
in into an account with editing permissions.
Another possible reason for failure may be the use of a browser
that does not support selection in SVG text elements. Please
consider testing with a
supported browser.
The types available for annotation and additional aspects that are available for marking depend on the configuration of the current collection.
Adding associations between annotations
Associations between existing annotations can be created by "dragging" the mouse from one annotation to the other.
Releasing the mouse pointer over another annotation again brings up a dialog for selecting the type of the annotation.
The types available for selection in this dialog depend both on the configuration of the collection and the types of the two selected annotations.
(When attempting to associate annotations that do not have any configured annotation types that can connect them, an error message will be shown instead of this dialog.)
Editing existing annotations
Logged-in users can modify or delete existing annotations by double-clicking on the annotation.
This will bring up the same annotation dialog with which the annotation type was originally selected, with some additional options.
In addition to allowing the type of the annotation and additional aspects such as notes to be modified, these dialogs also support the following additional features:
- Link: URL linking directly to the annotation
- Delete: delete the annotation
- Reselect: re-select the span of the annotation or the connected annotations
(Note that once created, the basic category of an annotation cannot be changed: that is, while an entity annotation can be changed into an entity annotation of another type, it cannot be changed into an event or relation annotation.)
Normalization
For information on how to use the normalization features (available from brat v1.3), see the brat normalization page.
Keyboard shortcuts
The following keyboard shortcuts are accessible in normal visualization or annotation state. (When a menu is open, these keyboard shortcuts are disabled.) Note: On Mac, use Cmd instead of Ctrl.
- ESC: clear any open menus (canceling possible modifications) and on-screen messages
- TAB: open the collection browser
- CTRL-F: search
- CTRL-G: next search result (after search)
- CTRL-H: repeat the previous annotation action on the current search result (after search)
- Left arrow: previous document (or search result)
- Right arrow: next document (or search result)
The order in which "previous" and "next" documents are visited when pressing the arrow keys depends on the current sort order selected in the collection browser. This allows documents to be browsed with the keyboard for example in sequence from those with the most entity annotations to those with the fewest. (The default order is by document name.)
When an annotation menu is open, a different set of configurable keyboard shortcuts is available to quick-select annotation types.
Data dialog
The data dialog, accessible from the menu, provides access to data management features.
The following features are found in the data dialog:
- Export document data: export data for the current document.
- txt: raw document text (UTF-8 encoding)
- ann: annotations in brat stand-off format (text-based)
- Export visualization: export visualization of the
current document. The following formats are supported:
- svg: Scalable Vector Graphics (vector format, XML) recommended for further editing of visualization (using tools such as inkscape)
- png: Portable Network Graphics (bitmap format, binary) appropriate for web graphics
- pdf: Portable Document Format (vector format, binary) appropriate for embedding into documents
- eps: Encapsulated PostScript (vector format, binary) appropriate for embedding into documents
- Export collection data: export a tar archive packaged with gzip containing the raw texts and annotations of the entire collection.
- Automatic annotation: automatically annotate the current document using one of the tools configured for the brat installation.
- Import:
- New document: add a single document to the current collection by entering text in a simple dialog
- New collection: add an entire new collection by uploading a tar archive packaged with gzip containing the raw texts and optionally including also annotations (brat .ann files)
- Delete:
- Current document: permanently remove the current document and its annotations the collection
- Current collection: permanently remove the current collection, including all its documents and their annotations
Note that most of these features are only available when logged in, and some are only available to users with administrative rights.
If some necessary features are not accessible in the data dialog, make sure you are logged in. If the issue persists, please contact the administrator of your brat installation.
Search
Basic search options
The data dialog, accessible from the menu or by pressing CTRL-F, provides access to search features.
The four tabs on top allow selection of the thing to search for:
- Text: search for text matching a given string or regular expression
- Entity: search for entity annotations matching given specification
- Event: search for event annotations matching given specification
- Relation: search for relation annotations matching given specification
The only option show by default allows the selection of the search scope:
- Document: search only the current document
- Collection: search all documents in the current collection
Advanced search options
Clicking on the text "Show advanced" reveals advanced search options.
- Concordancing: display search results with surrounding context of the specified size (Context length) in a key word in context format
- Matching: select between matching given text strings as whole words, substrings of words, and regular expression (regex) search. In regular expression mode, the given string is interpreted as a (Python-flavoured) regular expression that is matched against target text.
- Case: whether or not to require character case to agree between the given string and the matched text.
