home | introduction | examples | features | manual | site map | contact

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

feature example
document selection

When starting, brat will show the collection browser. To open a document, simply double-click on one of the documents (icon) in the document selector.

To open another collection, double-click on a collection (icon). This will update the collection browser to show the contents of that collection.


When a document is selected, the main window area shows a visualization of the text and annotations of that document.

feature example
Annotation visualization

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.

Placing the mouse cursor over the top bar of the window opens the menu, which drops down from the top of the screen.

feature example
brat menu

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 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.

feature example
brat collection browser

Collections can be organized hierarchically: a collection can contain others, similarly to a directory or folder structure on disk.

Other collections (icon) are shown first in the document browser. The entry "../" refers to the collection containing the current one (if any).

Documents (icon) 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.

icon 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.

feature example
Login button

Clicking on the "Login" button brings up the login dialog.

feature example
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.

feature example
Selecting text for annotation

Selection can be performed either by "dragging" over the text or by double-clicking on a word.

icon 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.

icon 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.

feature example
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).

icon 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.

feature example
Connecting existing annotations

Releasing the mouse pointer over another annotation again brings up a dialog for selecting the type of the annotation.

feature example
Relation type dialog

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.

feature example
Double-click on the "box" for a text span annotation to edit it.

feature example
Double-click on the "arc" connecting two annotations to edit the association of those annotations.

This will bring up the same annotation dialog with which the annotation type was originally selected, with some additional options.

feature example
Annotation dialog for previously created entity annotation

feature example
Annotation dialog for previously created relation annotation

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:

(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.)


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.

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.

feature example
Data dialog

The following features are found in the data dialog:

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.

Basic search options

The data dialog, accessible from the menu or by pressing CTRL-F, provides access to search features.

feature example
Search dialog

The four tabs on top allow selection of the thing to search for:

The only option show by default allows the selection of the search scope:

Advanced search options

Clicking on the text "Show advanced" reveals advanced search options.

feature example
Advanced search options

Return to the brat home page to try it out!