Package nzilbb.ag

Class Graph

  • All Implemented Interfaces:
    Serializable, Cloneable, Comparable<Annotation>, Map<String,​Object>, CloneableBean
    public class Graph
extends Annotation
    Linguistic annotation graph.

    An annotation graph 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:

    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.

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

    Author:
    Robert Fromont robert.fromont@canterbury.ac.nz
    See Also:
    Serialized Form

    • Constructor Detail

      • Graph

        public Graph()
        Default constructor.

    • Method Detail

      • getCorpus

        @Deprecated
public String getCorpus()
        Deprecated.
        Getter for corpus: The name of the corpus the graph belongs to.
        Returns:
        The name of the corpus the graph belongs to.

      • setCorpus

        @Deprecated
public Graph setCorpus​(String corpus)
        Deprecated.
        Setter for corpus.
        Parameters:
        corpus - The name of the corpus the graph belongs to.
        Returns:
        this.

      • getAnchors

        @ClonedProperty
public LinkedHashMap<String,​Anchor> getAnchors()
        Getter for anchors: Map of anchors (graph nodes) keyed by id.

        In the underlying map, this is stored as the "children" attribute of a "layers" attribute.

        Returns:
        Map of anchors (graph nodes) keyed by id.

      • setAnchors

        public Graph setAnchors​(LinkedHashMap<String,​Anchor> anchors)
        Setter for anchors.

        In the underlying map, this is stored as the "children" attribute of a "layers" attribute.

        Parameters:
        anchors - Map of anchors (graph nodes) keyed by id.
        Returns:
        this.

      • getOffsetGranularity

        public Double getOffsetGranularity()
        Getter for getOffsetGranularity(): Granularity of offsets - e.g. 0.001 if Anchor offsets are always set to the the nearest millisecond, or null for no particular granularity.
        Returns:
        Granularity of offsets - e.g. 0.001 if Anchor offsets are always set to the the nearest millisecond, or null for no particular granularity.

      • setOffsetGranularity

        public Graph setOffsetGranularity​(Double newOffsetGranularity)
        Setter for getOffsetGranularity().g. 0.001 if Anchor offsets are always set to the the nearest millisecond, or null for no particular granularity.
        Parameters:
        newOffsetGranularity - Granularity of offsets - e.g. 0.001 if Anchor offsets are always set to the the nearest millisecond, or null for no particular granularity.
        Returns:
        this.

      • getOffsetUnits

        public String getOffsetUnits()
        Getter for offsetUnits: The units for anchor offsets - e.g. "s" for seconds, "char" for characters, etc. Preferably the value should be one of the Constants.UNIT_... constants. The default value is Constants.UNIT_SECONDS.
        Returns:
        The units for anchor offsets - e.g. "s" for seconds, "char" for characters, etc. Preferably the value should be one of the Constants.UNIT_... constants.

      • setOffsetUnits

        public Graph setOffsetUnits​(String newOffsetUnits)
        Setter for offsetUnits.g. "s" for seconds, "char" for characters, etc. Preferably the value should be one of the Constants.UNIT_... constants.
        Parameters:
        newOffsetUnits - The units for anchor offsets - e.g. "s" for seconds, "char" for characters, etc. Preferably the value should be one of the Constants.UNIT_... constants.
        Returns:
        this.

      • getAnnotationsById

        public LinkedHashMap<String,​Annotation> getAnnotationsById()
        Getter for annotationsById: Map of annotations (graph edges) keyed by id.
        Returns:
        Map of annotations (graph edges) keyed by id.

      • setAnnotationsById

        public Graph setAnnotationsById​(LinkedHashMap<String,​Annotation> newAnnotationsById)
        Setter for annotationsById.
        Parameters:
        newAnnotationsById - Map of annotations (graph edges) keyed by id.
        Returns:
        this.

      • getSchema

        @ClonedProperty
public Schema getSchema()
        Getter for schema: The layer definitions and their interrelations.
        Returns:
        The layer definitions and their interrelations.

      • setSchema

        public Graph setSchema​(Schema newSchema)
        Setter for schema.
        Parameters:
        newSchema - The layer definitions and their interrelations.
        Returns:
        this.

      • getTimers

        public Timers getTimers()
        Getter for timers: Timers for debugging and optimization.
        Returns:
        Timers for debugging and optimization.

      • setTimers

        public Graph setTimers​(Timers newTimers)
        Setter for timers.
        Parameters:
        newTimers - Timers for debugging and optimization.
        Returns:
        this.

      • getMediaProvider

        public GraphMediaProvider getMediaProvider()
        Getter for mediaProvider.
        Returns:
        An optional provider for media associated with the graph.

      • setMediaProvider

        public Graph setMediaProvider​(GraphMediaProvider mediaProvider)
        Setter for mediaProvider.
        Parameters:
        mediaProvider - An optional provider for media associated with the graph.
        Returns:
        this.

      • isFragment

        public boolean isFragment()
        Determines whether this is a fragment of a larger graph (true) or the whole graph (false).
        Returns:
        false if getGraph() == this, true otherwise.

      • FragmentId

        public static String FragmentId​(String graphId,
                                Double startOffset,
                                Double endOffset)
        Computes a graph fragment ID, given a graph ID and bounding offsets.
        Parameters:
        graphId -
        startOffset -
        endOffset -
        Returns:
        The ID of the fragment, formatted graphId-without-extension__startOffset-endOffset

      • FragmentId

        public static String FragmentId​(Graph graph,
                                Double startOffset,
                                Double endOffset)
        Computes a graph fragment ID, given a graph and bounding offsets.
        Parameters:
        graph -
        startOffset -
        endOffset -
        Returns:
        The ID of the fragment, formatted graphId-without-extension__startOffset-endOffset

      • FragmentId

        public static String FragmentId​(Graph graph,
                                Anchor start,
                                Anchor end)
        Computes a graph fragment ID, given a graph and bounding anchors.
        Parameters:
        graph -
        start -
        end -
        Returns:
        The ID of the fragment, formatted graphId__startOffset-endOffset

      • ParseFragmentId

        public static String[] ParseFragmentId​(String fragmentId)
        Deduces the graph name, start time, and end time from the given fragment ID.
        Parameters:
        fragmentId - The fragment, formatted graphId__startOffset-endOffset
        Returns:
        An array with three elements (or null if the fragmentId is not correctly formatted):
        • 0 : the ID of the original graph
        • 1 : original start offset of the fragment
        • 2 : original end offset of the fragment

      • getFragment

        public Graph getFragment​(double startOffset,
                         double endOffset,
                         String[] layerIds)
        Creates a fragment of this graph, copying into it annotations that fall within the given bounds, on the given layers. Ancestors which do not fall into the interval are also added to the fragment, so that turns/speakers/etc. are accessible, but their anchors are not added to the fragment.

        The ID of the new fragment is graphId__startOffset-endOffset

        Parameters:
        startOffset - The start offset for annotations to include in the fragment.
        endOffset - The end offset for annotations to include in the fragment.
        layerIds - A list of IDs of layers to include in the fragment.
        Returns:
        A graph fragment containing the annotations that fall within the given bounds, on the given layers.

      • getFragment

        public Graph getFragment​(Annotation definingAnnotation,
                         String[] layerIds)
        Creates a fragment of this graph, copying into it the given annotation and its descendants, on the given layers. Ancestors which do not fall into the interval are also added to the fragment, so that turns/speakers/etc. are accessible, but their anchors are not added to the fragment. If the defining annotation's layer is not included in layerIds, the annotation is not included in the resulting fragment.

        The ID of the new fragment is graphId__fragment.start.offset-fragment.end.offset

        Parameters:
        definingAnnotation - The annotation that defines fragment membership.
        layerIds - A list of IDs of layers to include in the fragment.
        Returns:
        A graph fragment containing the annotations that fall within the given bounds, on the given layers.

      • getFragment

        public Graph getFragment​(Annotation bounds,
                         Annotation ancestor,
                         String[] layerIds)
        Creates a fragment of this graph, copying into it annotations that fall within the bounds of the given bounds annotation, and which are descendants of the given ancestor annotation, on the given layers. Ancestors which do not fall into the interval are also added to the fragment, so that turns/speakers/etc. are accessible, but their anchors are not added to the fragment.

        The ID of the new fragment is graphId__fragment.start.offset-fragment.end.offset

        Parameters:
        bounds - Annotation that defines the offset bounds (start/end time) of the included annotations
        ancestor - Annotation that is an ancestor of all annotations to be included.
        layerIds - A list of IDs of layers to include in the fragment.
        Returns:
        A graph fragment containing the annotations that fall within the given bounds, on the given layers.

      • getAnnotation

        public Annotation getAnnotation​(String id)
        Retrieves an annotation given an id.
        Parameters:
        id - ID of the annotation.
        Returns:
        The identified annotation, if it's in the graph, and null otherwise.

      • addAnnotation

        public Annotation addAnnotation​(Annotation annotation)
        Adds an annotation to the graph.

        If either of the anchor IDs is null, and the layer is aligned, then default anchors are created for the annotation. This allows addAnnotation(new Annotation(null, label, layerId)) to be repeatedly invoked, allowing anchor offsets to be set later.

        Overrides:
        addAnnotation in class Annotation
        Parameters:
        annotation - The annotation to add to the graph.
        Returns:
        The annotation.

      • addAnchor

        public Anchor addAnchor​(Anchor anchor)
        Adds an anchor to the graph.
        Parameters:
        anchor - The anchor to add to the graph.
        Returns:
        The anchor.

      • getAnchor

        public Anchor getAnchor​(String id)
        Retrieves an anchor given an id.
        Parameters:
        id - The ID of the anchor.
        Returns:
        The identified anchor, if it's in the graph, and null otherwise.

      • getAnchorAt

        public Anchor getAnchorAt​(double offset)
        Gets an anchor at the given offset.
        Parameters:
        offset - The anchor offset.
        Returns:
        An anchor that has the given offset, or null if there isn't one in the graph.
        See Also:
        getOrCreateAnchorAt(double)

      • getOrCreateAnchorAt

        public Anchor getOrCreateAnchorAt​(double offset)
        Gets an anchor at the given offset. If there isn't already one in the graph, one is created.
        Parameters:
        offset - The anchor offset.
        Returns:
        An anchor that has the given offset.
        See Also:
        getAnchorAt(double), createAnchorAt(double)

      • getOrCreateAnchorAt

        public Anchor getOrCreateAnchorAt​(double offset,
                                  Integer confidence)
        Gets an anchor at the given offset. If there isn't already one in the graph, one is created.

        This convenience method allows, for example, the creation of an anchor with a confidence value in one step: 

         Anchor anchor = graph.getOrCreateAnchorAt(456.789, Constants.CONFIDENCE_AUTOMATIC);
        Parameters:
        offset - The anchor offset.
        confidence - Confidence rating.
        Returns:
        An anchor that has the given offset.
        See Also:
        getAnchorAt(double), createAnchorAt(double,Integer)

      • createAnchorAt

        public Anchor createAnchorAt​(double offset,
                             Integer confidence)
        Creates an anchor at the given offset.

        This convenience method allows, for example, the creation of an anchor with a confidence value in one step: 

         Anchor anchor = graph.createAnchorAt(456.789, Constants.CONFIDENCE_AUTOMATIC);
        Parameters:
        offset - The anchor offset.
        confidence - Confidence rating.
        Returns:
        A new anchor that has the given offset.
        See Also:
        getAnchorAt(double), getOrCreateAnchorAt(double,Integer)

      • getSortedAnchors

        public SortedSet<Anchor> getSortedAnchors()
        Returns the anchors sorted by offset. This includes only anchors for which the offset is actually set.
        Returns:
        The anchors sorted by offset.

      • getAnchorsOrderedByStructure

        public SortedSet<Anchor> getAnchorsOrderedByStructure()
        Returns all anchors, in the best order given their offset and annotation links. This ordering requires much graph traversal to find the best comparison between anchors, so is computationally expensive and should be used sparingly.
        Returns:
        An ordered set of all anchors in the graph.

      • shiftAnchors

        public void shiftAnchors​(double offset)
        Increments all (set) anchor offsets by the given amount.
        Parameters:
        offset -

      • compareOffsets

        public int compareOffsets​(double o1,
                          double o2)
        Compares two offsets, taking getOffsetGranularity() into account.
        Parameters:
        o1 - The first offset to compare.
        o2 - The second offset to compare.
        Returns:
        0 if the two offsets are within getOffsetGranularity() of each other, or a negative number if o1 < o2, and otherwise a positive number.

      • addLayer

        public void addLayer​(Layer layer)
        Adds a layer definition.
        Parameters:
        layer - The layer to add.

      • getLayer

        public Layer getLayer​(String layerId)
        Get the definition of the given layer ID.
        Parameters:
        layerId - The given layer ID.
        Returns:
        The definition of the given layer ID.

      • getLayersTopDown

        public Vector<Layer> getLayersTopDown()
        Get a list of layers, ordered top down.
        Returns:
        A list of layers, ordered top down.

      • labels

        public String[] labels​(String layerId)
        Returns the labels of the annotations on the given layer, as an array of Strings.
        Parameters:
        layerId - The given layer ID.
        Returns:
        The labels of the annotations on the given layer, as an array of Strings.

      • createTag

        public Annotation createTag​(Annotation toTag,
                            String layerId,
                            String label)
        Creates a tag annotation.
        Parameters:
        toTag - The annotation to tag, which can be the parent, or a child of the correct parent.
        layerId - The tag layer ID.
        label - The tag label.
        Returns:
        The tag annotation created.

      • createSubdivision

        public Annotation createSubdivision​(Annotation toSubdivide,
                                    String layerId,
                                    String label)
        Creates an annotation that subdivides the given annotation.

        The first time this is called for any given annotation, a tag is created - i.e. a new annotation that shares both start and end annotations with the given annotation. Subsequent calls for the same annotation will chain new annotations across the given annotation, using insertAfter(Annotation,String,String).

        Peer-layered tags for the last pre-existing annotation will have their end anchors updated, so they continue to share end anchors as before.

        Parameters:
        toSubdivide - The annotation to subdivide.
        layerId - The new annotation's layer ID.
        label - The new annotation's label.
        Returns:
        The annotation just created.

      • createSpan

        public Annotation createSpan​(Annotation from,
                             Annotation to,
                             String layerId,
                             String label,
                             Annotation parent)
        Creates a spanning annotation from the beginning of the start annotation to the ending of the end annotation.
        Parameters:
        from - The first annotation to span.
        to - The last annotation to span.
        layerId - The layer ID of the resulting annotation.
        label - The label of the resulting annotation.
        parent - The new annotation's parent (or a child of the correct parent).
        Returns:
        The new annotation.

      • createSpan

        public Annotation createSpan​(Annotation from,
                             Annotation to,
                             String layerId,
                             String label)
        Creates a spanning annotation from the beginning of the start annotation to the ending of the end annotation. The parent annotation is guessed, if possible, from from or to
        Parameters:
        from - The first annotation to span.
        to - The last annotation to span.
        layerId - The layer ID of the resulting annotation.
        label - The label of the resulting annotation.
        Returns:
        The new annotation.

      • addSpan

        @Deprecated
public Annotation addSpan​(Annotation from,
                          Annotation to,
                          String layerId,
                          String label)
        Deprecated.
        Use createSpan(Annotation,Annotation,String,String)
        Creates a spanning annotation from the beginning of the start annotation to the ending of the end annotation and adds it to the graph. The parent annotation is guessed, if possible, from from or to.

        This method has the same effect as: graph.addAnnotation( graph.createSpan(from, to, layerId, label));

        Parameters:
        from - The first annotation to span.
        to - The last annotation to span.
        layerId - The layer ID of the resulting annotation.
        label - The label of the resulting annotation.
        Returns:
        The new annotation.
        See Also:
        createSpan(Annotation,Annotation,String,String)

      • createAnnotation

        public Annotation createAnnotation​(Anchor from,
                                   Anchor to,
                                   String layerId,
                                   String label,
                                   Annotation parent)
        Creates an annotation starting at from and ending at to.
        Parameters:
        from - The start anchor.
        to - The end anchor.
        layerId - The layer ID of the resulting annotation.
        label - The label of the resulting annotation.
        parent - The new annotation's parent.
        Returns:
        The new annotation.

      • addAnnotation

        @Deprecated
public Annotation addAnnotation​(Anchor from,
                                Anchor to,
                                String layerId,
                                String label,
                                Annotation parent)
        Deprecated.
        Use createAnnotation(Anchor,Anchor,String,String,Annotation)
        Creates an annotation starting at from and ending at to, and adds it to the graph.

        This method has the same effect as: graph.addAnnotation( graph.createAnnotation(from, to, layerId, label, parent));

        Parameters:
        from - The start anchor.
        to - The end anchor.
        layerId - The layer ID of the resulting annotation.
        label - The label of the resulting annotation.
        parent - The new annotation's parent.
        Returns:
        The new annotation.

      • insertAfter

        public Annotation insertAfter​(Annotation before,
                              String layerId,
                              String label)
        Creates an annotation chained after the given annotation. This creates a new anchor, which becomes before.end and the new annotation's start, and the previous before.end becomes the new annotation's end.

        The new anchor, and the new annotation, are both added to the graph.

        Parameters:
        before - The annotation before the new annotation to add. If layerId == before.layerId, the new annotation's parentId is set to before.parentId. Otherwise, it's the caller's responsibility to assign a parent to the new annotation.
        layerId - The new annotation's layer ID.
        label - The new annotation's label.
        Returns:
        The new annotation.

      • insertBefore

        public Annotation insertBefore​(Annotation after,
                               String layerId,
                               String label)
        Creates an annotation chained before the given annotation. This creates a new anchor, which becomes after.start and the new annotation's end, and the previous after.start becomes the new annotation's start.

        The new anchor, and the new annotation, are both added to the graph.

        Parameters:
        after - The annotation after the new annotation to add. If layerId == before.layerId, the new annotation's parentId is set to before.parentId. Otherwise, it's the caller's responsibility to assign a parent to the new annotation.
        layerId - The new annotation's layer ID.
        label - The new annotation's label.
        Returns:
        The new annotation.

      • destroyAll

        public boolean destroyAll​(String layerId)
        Marks all annotations on the given layer for destruction/deletion.
        Parameters:
        layerId - The ID of the layer of annotations to delete.
        Returns:
        true if some annotations were destroyed, false otherwise

      • overlappingAnnotations

        public Annotation[] overlappingAnnotations​(Annotation annotation,
                                           String layerId)
        Returns a list of annotations that overlap with the given offset interval
        Parameters:
        annotation - Annotation whose bounds define the interval.
        layerId - Layer to match.
        Returns:
        A possibly empty array of annotations.

      • overlappingAnnotations

        public Annotation[] overlappingAnnotations​(Anchor start,
                                           Anchor end,
                                           String layerId)
        Returns a list of annotations that overlap with the offset interval defined by the given anchors.
        Parameters:
        start - Start anchor.
        end - End anchor.
        layerId - Layer to match.
        Returns:
        A possibly empty array of annotations.

      • overlappingAnnotations

        public Annotation[] overlappingAnnotations​(double start,
                                           double end,
                                           String layerId)
        Returns a list of annotations that overlap with the given offset interval.
        Parameters:
        start - Start offset of the interval.
        end - End offset of the interval.
        layerId - Layer to match.
        Returns:
        A possibly empty array of annotations.

      • getTrackedAttributes

        public Set<String> getTrackedAttributes()
        Keys for attributes that are change-tracked - in the case of Graph, there are none.
        Overrides:
        getTrackedAttributes in class Annotation
        Returns:
        An empty set.

      • setId

        public Graph setId​(String id)
        Setter for id: The annotation's identifier.
        Overrides:
        setId in class Annotation
        Parameters:
        id - The annotation's identifier.

      • getStartId

        public String getStartId()
        Getter for startId: ID of the anchor with the lowest offset.
        Overrides:
        getStartId in class Annotation
        Returns:
        ID of the anchor with the lowest offset.

      • getEndId

        public String getEndId()
        Getter for endId: ID of the anchor with the highest offset.
        Overrides:
        getEndId in class Annotation
        Returns:
        ID of the anchor with the highest offset.

      • getStart

        public Anchor getStart()
        Getter for start: The anchor with the lowest offset.
        Overrides:
        getStart in class Annotation
        Returns:
        The anchor with the lowest offset.

      • getEnd

        public Anchor getEnd()
        Getter for end: The anchor with the highest offset.
        Overrides:
        getEnd in class Annotation
        Returns:
        The anchor with the highest offset.

      • first

        public Annotation first​(String layerId)
        Gets a single related annotation on the given layer.

        "Related" means that layerId identifies the parent layer, an ancestor layer, a child of an ancestor, or a child layer.

        This utility method makes navigating the layer hierarchy easier and with less prior knowledge of it. e.g.:

        • word.first("turn") for the (parent) turn
        • phone.first("turn") for the (grandparent) turn
        • word.first("POS") for the (first) part of speech annotation
        • phone.first("POS") for the (first) part of speech annotation, which is neither an ancestor nor descendant, but rather is a child of an ancestor (phone.first("word"))
        • word.first("who") for the speaker
        • word.first("transcript") for the transcript
        • word.first("utterance") for the utterance, which is neither an ancestor nor descendant, but rather is a child of an ancestor (word.first("turn"))
        • word.first("corpus") for the graph's corpus, which is neither an ancestor nor descendant, but rather is a child of an ancestor (word.first("transcript"))

        Annotation.setGraph(Graph) must have been previously called, and the graph must have a correct layer hierarchy for this method to work correctly.

        This override of Annotation.first(String) ensures that even orphaned annotations on the given layer are returned.

        Overrides:
        first in class Annotation
        Parameters:
        layerId - The layer of the desired annotation.
        Returns:
        The related annotation (or the first one if there are many), or null if none could be found on the given layer.

      • all

        public Annotation[] all​(String layerId)
        Gets a list of related annotations on the given layer.

        "Related" means that layerId identifies the parent layer, an ancestor layer, a child of an ancestor, a child layer, or a desdendant layer.

        This utility method makes navigating the layer hierarchy easier and with less prior knowledge of it. e.g.:

        • word.all("turn")[0] for the (parent) turn
        • phone.all("turn")[0] for the (grandparent) turn
        • word.all("POS") for all (child) part of speech annotations
        • word.all("phone") for all (child) phones in a word
        • turn.all("phone") for all (grandchild) phones in a turn
        • phone.all("POS") for the all (peer) part of speech annotation, which are neither ancestors nor descendants, but rather children of an ancestor (phone.first("word"))
        • word.all("who")[0] for the (grandparent) speaker
        • word.all("transcript")[0] for the (great-grandparent) transcript
        • word.all("utterance")[0] for the (peer) utterance, which is neither an ancestor nor descendant, but rather is a child of an ancestor (word.my"turn"))
        • utterace.all("word") for the utterance's (peer) words, which are neither an ancestors nor descendants, but rather are children of an ancestor (utterance.my"turn"))
        • word.all("corpus")[0] for the graph's (child of grandparent) corpus, which is neither an ancestor nor descendant, but rather is a child of an ancestor (word.first("transcript"))

        Annotation.setGraph(Graph) must have been previously called, and the graph must have a correct layer hierarchy for this method to work correctly.

        This override of Annotation.all(String) ensures that even orphaned annotations on the given layer are returned.

        Overrides:
        all in class Annotation
        Parameters:
        layerId - The layer of the desired annotations.
        Returns:
        The related annotations, or an empty array if none could be found on the given layer.

      • assignWordsToUtterances

        public void assignWordsToUtterances()
        Convenience function that links each utterance to the words contained in it, via the "@words" attribute.

        By default, the utterance and word layers are 'peers' - i.e. the parent of both is the turn layer. This is so words easily and naturally link to each other across utterance boundaries.

        However, there are circumstances where it's convenient to process words by utterance instead of by turn. Under such circumstances, this method can be used to efficiently link all words to the utterance that contain them.

        Each utterance is assigned a new "@words" key, which is a List<Annotation>, which contains the words that start within the bounds of the utterance, or at the end is not within the bounds of the next utterance.

      • getLayer

        public Layer getLayer()
        Getter for layer: The graph's layer definition, which is by definition the root of its schema.
        Overrides:
        getLayer in class Annotation
        Returns:
        The annotation's layer definition.
        See Also:
        getSchema(), Schema.getRoot()

      • getLabel

        public String getLabel()
        Getter for label: The label for the whole graph, which is defined as it's ID.
        Overrides:
        getLabel in class Annotation
        Returns:
        The graph's label.

      • getGraph

        public Graph getGraph()
        Getter for Annotation.graph, which always returns this.
        Overrides:
        getGraph in class Annotation
        Returns:
        this.

      • sourceGraph

        public Graph sourceGraph()
        Returns the graph which this is a fragment of.
        Returns:
        The fragment's original graph, or this, if this graph is not a fragment.

      • commit

        public void commit()
        Commits graphs's changes, if any. Any annotations/anchors marked for deletion are removed.

      • trackChanges

        public void trackChanges()
        Adds a default change tracker. From this point on, changes to the graph or any of its Anchors/Annotations will be tracked and reversible.

      • applyChangesFromFragment

        public void applyChangesFromFragment​(Graph fragment,
                                     Set<String> includeLayers)
        Applies tracked changes made in the given graph/fragment to this graph.

        NB: It is assumed that the updated anchors/annotations and the destroyed annotations have the name IDs in both graphs. For new anchors/annotations, the IDs from the fragment are not used; this graph generates new IDs, and then the corresponding anchors/annotations in the fragment have their IDs changed to match those from this graph. This means that a side-effect of this method is that the given fragment may change. No anchors are marked for deletion.

        Parameters:
        fragment - The fragment (or graph) from which the changes come.
        includeLayers - A set of layers specifying which annotations to apply changes to, or null for updating all annotations.

      • setTracker

        public TrackedMap setTracker​(ChangeTracker newTracker)
        Ensure tracker is updated for all known annotations and anchors.
        Overrides:
        setTracker in class TrackedMap
        Parameters:
        newTracker - Object that tracks all changes to this object.

      • rollback

        public void rollback()
        Rolls back changes since the object was create or commit() was last called. The effect of this is to rollback all anchors and annotations.
        Overrides:
        rollback in class Annotation
        See Also:
        getTrackedAttributes()

      • getChanges

        public List<Change> getChanges()
        Produces a list of individual changes for this graph and its elements.
        Overrides:
        getChanges in class TrackedMap
        Returns:
        A list of individual changes for the object.

      • getChangedAnchors

        public Stream<Anchor> getChangedAnchors()
        A stream of anchors that have registered changes, in no particular order.
        Returns:
        A stream of anchors that have registered changes, which will be empty if TrackedMap.tracker is not set.

      • getChangedAnnotations

        public Stream<Annotation> getChangedAnnotations()
        Produces a stream of annotations that have registered changes, in no particular order.

        This does not include changes to the graph itself.

        Returns:
        A stream of annotations that have registered changes, which will be empty if TrackedMap.tracker is not set.

      • getChangedAnnotationsOrdered

        public List<Annotation> getChangedAnnotationsOrdered()
        Produces a collection of annotations that have registered changes, ordered so that hierarchically higher created annotations are first and hierarchically lower deleted annotations are last.
        Returns:
        A collection of annotations that have registered changes, ordered so that created annotations are first and deleted annotations are last.