Package nzilbb.ag

Implementation of an Annotation Graph API for linguistic annotations.

Annotation Graphs are a data structure conceived by Steven Bird and Mark Liberman

• http://lanl.arxiv.org/abs/cs/9907003
• http://xxx.lanl.gov/PS_cache/cs/pdf/9903/9903003v1.pdf

The structure is designed to be a tool-independent way of representing annotated linguistic data, and essentially defines an Annotation Graph as a directed acyclic graph where:

• nodes are 'anchors' that represent a point in time (in seconds) or a point in a text (in characters) (although the time/character offset label is optional), and
• edges are 'annotations' which have a 'label' (the content of the annotation) and a 'type' (the kind of annotation, analogous with an 'tier' or 'layer')

This particular implementation, which is used for LaBB-CAT, developed by the NZILBB, includes extra features that allow tier hierarchies and parent/child constraints to be defined. More details on extra features are available in http://dx.doi.org/10.1016/j.csl.2017.01.004

An annotation graph represented by the Graph class, and is a collection of Annotations (edges) joined by Anchors (nodes) which may or may not have temporal/character offsets. Superimposed over this temporally anchored graph is another heirarchical graph, where annotations are nodes and edges are child-to-parent links.

An example of a heirarchical annotation graph

In addition to containing the nodes/edges, this class inherits from Annotation so that it can:

• be the root node of the annotation hierarchy - i.e. be the parent of annotations at the top of the layer hierarchy
• have start/end anchors

In addition to this, the graph also has:

• a corpus attribute representing the collection to which it belongs (see Graph.getCorpus(), Graph.setCorpus(String)),
• definitions of annotation Layers and their hierarchy

It is recommended that other graph attributes are represented as annotations that 'tag' the whole graph, and that speakers/participants are also represented as such annotations, on a "participant" layer, which is the parent of a "turn" layer which defines speaker turns.

The Graph class can also represent graph fragments (sub-graphs). If this is a whole graph, Graph.getGraph() == this, but if it's a fragment, then Graph.getGraph() != this. The Graph.isFragment() convenience method captures this principle. The annotations in a graph fragment have the fragment object (not the whole-graph object) set as their Graph.getGraph().

Author:

Robert Fromont robert.fromont@canterbury.ac.nz

Interface Summary

Interface	Description
GraphMediaProvider	Interface for objects that provide access to media for a given graph.
GraphStore	Interface for querying and updating an annotation graph store, a database of transcripts represented as Annotation Graphs.
GraphStoreAdministration	Interface for administration of a graph store.
GraphStoreQuery	Interface for querying an annotation graph store, a database of transcripts represented using Annotation Graphs.
GraphTransformer	Interface for transformer that transforms a Graph in some way.
IGraphMediaProvider	Deprecated. Use GraphMediaProvider instead.
IGraphStore	Deprecated. Use GraphStore instead.
IGraphStoreAdministration	Deprecated. Use GraphStoreAdministration instead.
IGraphStoreQuery	Deprecated. Use GraphStoreQuery instead.
IGraphTransformer	Deprecated. Use GraphTransformer instead.

Class Summary

Class	Description
Anchor	Annotation graph anchor - a node of the graph.
AnchorChain	Chain of anchors joined by annotations.
Annotation	Annotation graph annotation - an edge of the graph.
AnnotationChain	A set of annotations chained together by sharing end/start annotations.
Change	Defines a single change to a TrackedMap object.
ChangeTracker	Something that listens for Changes to TrackedMap objects.
Constants	Useful annotation constants.
Graph	Linguistic annotation graph.
Layer	Annotation graph layer.
MediaFile	A single media file, which may exist or may be creatable by conversion from some other media file.
MediaTrackDefinition	Definition of a possible media track that a graph might be associated with.
Schema	Definition of layers and their interrelations.
StoreGraphMediaProvider	A graph media provider that uses an IGraphStoreQuery to access media.
TrackedMap	Base class for annotation graph classes, which encapsulates three common features of these classes: Changes to specific attributes can be tracked and rolled back, by setting TrackedMap.getTracker(), which receives notification of all relevant changes.

Enum Summary

Enum	Description
Change.Operation	The change operation on a given object - i.e.

Exception Summary

Exception	Description
GraphNotFoundException	An exception ocurring if a given graph could not be located.
PermissionException	An exception ocurring during an annotation store operation because the operation is disallowed.
StoreException	An exception ocurring during an annotation store operation.
TransformationException	An exception ocurring during a graph transformation.

Annotation Types Summary

Annotation Type	Description
TrackedProperty	Annotation for bean getters, to mark the property as one whose changes can be tracked.