Annotate texts with Annotator

Annotator is a component of the InkVisitor software adapted to the annotation of full-texts. Unlike most annotation tools, it is connected to a robust and historically informed entity–relationship data model, which allows you to smoothly create entities and build your ontology as you go.

After you have uploaded the full-text, linked it to a Resource, and added a Territory's anchor in the full-text, you will need to understand the Annotator component and start using it efficiently.

Annotator's function is annotation, i.e. adding entity anchors into full texts uploaded to InkVisitor. You can delimit the span and add anchors such as specific Persons, Places, Concepts, Events etc. in full-text documents.

Annotator has three modes: highlight mode, which serves to add and remove anchors, text edit mode, which serves to edit the text, and XML mode, which allows more advanced users knowledgeable of HTML or XML markup to view the raw text file and manually edit both the text and its markup.

Search text

In all its modes, Annotator offers the search function, with the possibility of setting whether the search should be case sensitive or insensitive. In addition, in text edit mode and XML mode, you can select whether you are searching only for the whole word.

InkVisitor allows to use regular expressions (regexes) in the searches. The regex set used is JavaScript regexes.

Add anchor

Terminology and principles

Terminology. Annotating in InkVisitor is done by pinning an entity into a text in Annotator. This entity pin an "anchor". Adding Territory anchors is also a way how to declare that a full-text document is a representation of a Territory, and to segment the text into Subterritories, e.g. chapters and subchapters, or to individual documents within a register.

What to anchor? Depending on your project and your needs, it can be enough to only anchor, for instance, Persons and Locations. If you are doing CASTEMO data collection, it is very useful to add Statement anchors - where does the Statement text start and end.

Add anchors one by one

Anchors are added by selecting text in Annotator (highlight mode) and selecting an entity in the empty suggester, or creating a new one from this suggester if the correct entity does not yet exist. You can also quite conveniently drag and drop the entity from other parts of the screen (e.g. Search or Territory tree) into the empty suggester. There are two special cases: adding Territory anchor for text identification, and adding Statement anchor. For existing Territories, you do it in the way just described. However, for not yet existing Territories, you select the appropriate span (you can use Ctrl+A, Shift+PgDn and other cursor keys) and create a new territory either as a child, or sibling of the current territory. This way you can save time, because you both create the new Subterritory and also add it to the Territory tree at a proper level of the structure (as child or sibling of the current one).

With Statement anchors, the most practical workflow is actually to create Statements from Annotator: you select the span, and press the button new statement. This will do two things at a time: add a new Statement to the Statement list, and anchor it in the text, which is the most economic way. However, you can also anchor statements created before.

When adding the anchor, always remember to select the epistemic level. You might already know the epistemic level attribute from other contexts in InkVisitor.  If the expression is exactly in the text, set level to textual. If you are slightly changing the wording, e.g. from verbal to nominal, use the interpretive epistemic level. If you are annotating at a higher level of generalisation, departing from the text or anchor an entity with a different label language than the language your text is in (e.g. you use the English Concept "hate speech" to annotate Latin text), use inferential epistemic level.

Add more anchors through search

If you want to add the same anchor more than once, going through search results and choosing whether the anchor should be added or not, e.g. adding the anchor of a Location (e.g., Paris) throughout the document, then follow these steps:

1. select the entity you want to anchor to more places in the document in the empty suggester on the right from the search box;
2. fill in the text you want to find into the search box,
3. move between hits by the up and down buttons next to the search box and if you want to add the anchor here, click on the anchor button: this will wrap this search result with the start and end anchor; if you don't want to add it, just press the down button to go to the next hit.

The settings "extend to whole word(s)" is often very useful here.

Regexes are often very handy too. Use your favourite AI to help you with building more complex regexes.

Locate anchor

Obviously, you often want to locate already added anchors. You can locate any anchor of any entity from this entity's Detail: you open the entity in the Detail, look at the list of its anchors in texts, and by clicking on the icon of the appropriate anchor, you navigate to Annotator view of the specific anchor in the given full text.

For Territories, there is also an alternative way, usually more at hand: you open the Territory in the Territory tree (leftmost column of the application) and click on the Locate anchor button.

Remove anchor

If you need to remove an anchor, you can do it either from the Detail of the given entity (see above), or from Annotator in the highlight mode. Here is how: select a span encompassing the anchor you want to remove; the anchor modal window will appear, and here you will see all anchors in this span, and you can click on the unlink button on the entity you want to remove.

Don't worry, removing an anchor does not remove the entity. Only one specific anchor in the given full-text document.

Edit text

It often happens that you spot errors in the text and you need to correct them. For this, use the text edit mode of Annotator. Correct the error and save the changes.

View/edit XML markup

There is a third view apart from highlight and text edit: XML view. At the background, InkVisitor operates with a pointed-brackets delimited markup - it can be XML markup or other markup. To avoid XML verbosity and the related drop in speed, InkVisitor anchors are not valid XML, but only the UUID enclosed in pointed brackets, e.g. <a6f9d39e-68cf-4970-b955-c4d50fd7b621> as the start anchor and </a6f9d39e-68cf-4970-b955-c4d50fd7b621> as the end anchor.

You might want to use XML view when you want to check the raw code of the file for exact placement of anchor, for whether it is actually there, or actually removed after you removed it, and also when something goes amiss. With proper care, you can edit the code here - move end or start anchors etc.