PubAnnotation uses JSON as its default format to store annotations. This document describes how annotations are represented in JSON in PubAnnotation.
PubAnnotation JSON annotation format supports three different types of information:
- relation, and
A denotation connects a span of text to a conceptual object. In following example, there are two denotation annotations:
Following is a visualization of the above annotation, generated by TextAE:
Note that in the visualization, labels are truncated in the end in case of insufficient space.
The example states that there are two denotations, T1 and T2.
- The first one connects span 0-5 (the text spanning from 0’th to 5th characters) to Protein,
- while the second connects span 42-47 to Protein.
The semantic interpreation may vary. However, the default interpretation of T1 is as follows:
- the text span between the 0’th and the 5’th characters
- denotes an entity T1
- of which the type is Protein.
A relation connects two entities.
The example above states that the two entities, T1 and T2, that are introduced by the two denotations, are related to each other by the predicate, interactWith. Note that the two entities are specified by the two different keys, subj and obj, so the relation is directional. The design is motivated for a better compatibility with RDF.
Note that PubAnnotation does not enforce any specific annotation scheme, e.g., the labels for obj in denotations and those for pred in relations, and it is fully up to the producer of annotation how to design the scheme of his/her annotation. For example, while the way of annotation in above example may be familiar to the community which seeks informatin on protein-protein interaction, another community, e.g., BioNLP Shared Task, may be more familiar with a finer-grained annotation.
FYI, For color coding of the above example, the following TextAE configuration was used:
The modification type of annotation is deprecated in favor of attribute type of annotation.
An attribute annotation adds additional information to a denotation.
In the above example, the attribute annotation, A1 and A2, add the uniprot ID information to T1 and t2. Also, A3 tells that the denotation, T2, is uncertain.
Note again that the choice of the predicate is up to the designer of the annotation.
FYI, for the color coding of the above example, the following TextAE configuration was used:
Multi-layer annotations - annotations which are made by multiple projects to the same text - can be represented as muptiple tracks.
Usually, you will access annotations within a project, e.g.,
In the case, you will get the annotations without tracks:
However, if you access annotations without indication of a project (or if you specify multiple projects), e.g.,
then you will get the annotations in multiple tracks:
Note that the difference comes whether a project is specified or not in the URL.
Sometimes, there may be a case of denotation for which you may want to involve multiple discontinuous spans. For example, what if you want to annotate left lung in the text, left or right lung, with the ontology id, UBERON:0002168. As the two words are not adjacent to each other, it is not straightforward to specify the span of the denotation.
For representation of discontinuous spans as the span of a denotation, PubAnnotation supports two models: (1) bagging model, and (2) chaining model.
In the bagging model, it is allowed to specify the span of a denotation by an array of begin and end offsets, e.g.,
The bagging model may be intuitively easy to understand particularly in the JSON representation. However, it is a kind syntactic sugar which is beyond the normal representation of PubAnnotation. Internally, it is converted to the chaining model.
Note that in the bagging model, a span may be specified either by just a single pair of begin and end offsets, or by an array of pairs. Therefore, for a software program to read a JSON representation of annotation, it must perform a dynamic type checking, a.k.a. duck typing.
Chaining model (default)
The chaining model uses normal syntax of PubAnnotation JSON format. Instead, it uses special vocabularly to represent an involvement of multiple discontinuous spans in a denotation. For example, the above example in the bagging model will be internally converted to the chaining model as below:
It will be rendered in TextAE as below:
PubAnnotation uses the chaining model as default. The JSON representation in the bagging model can be accessed by setting the parameter discontinuous_span to be the value, bag, e.g.,