edu.uchsc.ccp.knowtator
Class AnnotationUtil

java.lang.Object
  edu.uchsc.ccp.knowtator.AnnotationUtil

All Implemented Interfaces:

SpanEditListener, EventListener

public class AnnotationUtil
extends Object
implements SpanEditListener

Authors: Philip V. Ogren Created: September, 2004 Description: This class aids in creating, editing and retrieving annotation intances as well as the supporting annotation classes. The annotation model is defined in annotations.pprj. This project must be included when the annotator plug-in is used. Todo: AnnotationUtil should really not have an instance of knowtator as a member variable. I need to create the appropriate listeners, so that Knowtator can take care of itself as it see fits. Changes: 02/28/2005 added annotation filter functionality 05/02/2005 package changed to ...knowtator 8/11/2005 pvo added getReferencedAnnotations method 10/04/2005 Changed signature of main createAnnotations method so that a string for the spanned text can be passed in. This removes the necessity of gathering the spanned text from the actual text source which may be an unnecessary task if you are copying an annotation (e.g. as in MergeAnnotations). This change had a small ripple effect on other methods: setSpans, updateAnnotationText 10/04/2005 Changed name of deleteAnnotationMention to deleteMention (I just didn't like the name!)

Constructor Summary

AnnotationUtil(KnowtatorManager manager)

Method Summary

boolean	compareSpans(List<SimpleInstance> annotations)
boolean	compareSpans(SimpleInstance annotation1, SimpleInstance annotation2) This method returns true if two annotations have exactly the same spans.
SimpleInstance	createAnnotation(Cls annotationCls, List<Span> spans, String spannedText, String textSourceName)
SimpleInstance	createAnnotation(Cls annotationCls, List<Span> spans, String spannedText, String textSourceName, SimpleInstance annotator, SimpleInstance set)
SimpleInstance	createAnnotation(SimpleInstance mention, SimpleInstance annotator, List<Span> spans, SimpleInstance textSourceInstance, SimpleInstance annotationSet)
SimpleInstance	createAnnotation(SimpleInstance mention, SimpleInstance annotator, List<Span> spans, String spannedText, SimpleInstance textSourceInstance, Collection<SimpleInstance> annotationSets)
SimpleInstance	createAnnotation(SimpleInstance mention, SimpleInstance annotator, List<Span> spans, String spannedText, SimpleInstance textSourceInstance, Collection<SimpleInstance> annotationSets, String creationDate) Creates an annotation.
SimpleInstance	createAnnotation(SimpleInstance mention, SimpleInstance annotator, List<Span> spans, TextSource textSource, SimpleInstance annotationSet) If the textSource does not have a corresponding instance in the kb, then one will be created.
void	deleteMention(SimpleInstance annotation) This method deletes the mention of annotation.
Collection<SimpleInstance>	getAnnotations(SimpleInstance textSourceInstance) Does the work of finding all "annotation" instances that have the textSourceInstance as the value of "annotation_text_source" slot.
Collection<SimpleInstance>	getAnnotations(String textSourceName)
Collection<SimpleInstance>	getAnnotations(TextSource textSource) Returns the "annotation" instances associated with a TextSource if the TextSource does not have a corresponding "text source" instance in the knowledgebase, then null is returned.
SimpleInstance	getAnnotator(SimpleInstance annotation)
String	getComment(SimpleInstance annotation)
String	getCreationDate(SimpleInstance annotation)
SimpleInstance	getMention(SimpleInstance annotation)
Set<SimpleInstance>	getRelatedAnnotations(SimpleInstance annotation) Returns all annotations that are related to the passed in annotation.
Set<SimpleInstance>	getSets(SimpleInstance annotation)
SimpleInstance	getShortestAnnotation(Collection<SimpleInstance> annotations) This method returns the shortest annotation - that is the annotation whose span is the shortest.
int	getSize(SimpleInstance annotation)
List<Span>	getSpans(SimpleInstance annotation) Returns a list of Span objects that correspond to the span values given to an annotation instance.
List<Span>	getSpans(SimpleInstance annotation, boolean ignoreCache) Returns a list of Span objects that correspond to the span values given to an annotation instance.
String	getText(SimpleInstance annotation)
SimpleInstance	getTextSource(SimpleInstance annotation)
boolean	hasTeamAnnotator(SimpleInstance annotation)
boolean	isAnnotation(SimpleInstance annotation)
List<SimpleInstance>	retrieveAllAnnotations()
void	setAnnotator(SimpleInstance annotation, SimpleInstance annotator)
void	setComment(SimpleInstance annotation, String comment)
void	setCreationDate(SimpleInstance annotation, String creationDate)
void	setMention(SimpleInstance annotation, SimpleInstance mention)
void	setMentionUtil(MentionUtil mentionUtil)
void	setProjectAnnotationSet(SimpleInstance annotation)
void	setProjectAnnotator(SimpleInstance annotation)
void	setSet(SimpleInstance annotation, SimpleInstance set)
void	setSets(SimpleInstance annotation, Collection<SimpleInstance> sets)
void	setSpans(SimpleInstance annotation, List<Span> spans, String spannedText) Sets the spans slot for an annotation instance.
void	setText(SimpleInstance annotation, String spannedText)
void	setTextSource(SimpleInstance annotation, SimpleInstance textSource)
void	setTextSourceUtil(TextSourceUtil textSourceUtil)
void	spanEditted(SpanEditEvent see) To get the currently selected spans at any time call KnowtatorProjectUtil.getSelectedSpans()
boolean	spansOverlap(SimpleInstance annotation1, SimpleInstance annotation2)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AnnotationUtil

public AnnotationUtil(KnowtatorManager manager)

Method Detail

setTextSourceUtil

public void setTextSourceUtil(TextSourceUtil textSourceUtil)

setMentionUtil

public void setMentionUtil(MentionUtil mentionUtil)

deleteMention

public void deleteMention(SimpleInstance annotation)

This method deletes the mention of annotation. Although it is not possible with the current interface to associate a mention with more than one annotation, there is no other reason why this can't happen. If a mention is associated with more than one annotation, then the mention will not be deleted.

Parameters:

annotation - the mention of this annotation will be deleted via mentionUtil.deleteMention.

spanEditted

public void spanEditted(SpanEditEvent see)

Description copied from interface: SpanEditListener

To get the currently selected spans at any time call KnowtatorProjectUtil.getSelectedSpans()

Specified by:

spanEditted in interface SpanEditListener

See Also:

KnowtatorManager.getSelectedSpans()

getSpans

public List<Span> getSpans(SimpleInstance annotation)
                    throws InvalidSpanException

Returns a list of Span objects that correspond to the span values given to an annotation instance. The spans will be ordered as defined by the Comparable interface implementation in Span. If a span value from an annotation does not parse (i.e. has a string value that is not in the correct span format), then an InvalidSpanException will be thrown.

Parameters:

annotation - the spans for the annotation will be returned

Returns:

a list of spans corresponding to the annotation's kpu.getAnnotationSpanSlot()

Throws:

InvalidSpanException

getSpans

public List<Span> getSpans(SimpleInstance annotation,
                           boolean ignoreCache)
                    throws InvalidSpanException

Returns a list of Span objects that correspond to the span values given to an annotation instance. The spans will be ordered as defined by the Comparable interface implementation in Span. If a span value from an annotation does not parse (i.e. has a string value that is not in the correct span format), then an InvalidSpanException will be thrown.

Parameters:

annotation - the spans for the annotation will be returned

Returns:

a list of spans corresponding to the annotation's kpu.getAnnotationSpanSlot()

Throws:

InvalidSpanException

setSpans

public void setSpans(SimpleInstance annotation,
                     List<Span> spans,
                     String spannedText)
              throws TextSourceAccessException

Sets the spans slot for an annotation instance. If a

Parameters:

annotation - set the span slot for the passed in annotation

spans - a list of spans for the annotation. This will typically be a list of 1 span object, but may occasionally have a 2 or more spans.

spannedText - if null, then the text from the text source for the annotation will be used to determine the spannedText. If the spannedText is already known, then it may be useful to pass in the spannedText. Passing in an empty string will cause the spannedText to be an empty string.

Throws:

TextSourceAccessException

getAnnotations

public Collection<SimpleInstance> getAnnotations(TextSource textSource)

Returns the "annotation" instances associated with a TextSource if the TextSource does not have a corresponding "text source" instance in the knowledgebase, then null is returned. If the "text source" instance does exist then all of the "annotation" instances are found and returned. If none are found, an empty array of instances is returned.

getAnnotations

public Collection<SimpleInstance> getAnnotations(String textSourceName)

getAnnotations

public Collection<SimpleInstance> getAnnotations(SimpleInstance textSourceInstance)

Does the work of finding all "annotation" instances that have the textSourceInstance as the value of "annotation_text_source" slot.

createAnnotation

public SimpleInstance createAnnotation(Cls annotationCls,
                                       List<Span> spans,
                                       String spannedText,
                                       String textSourceName)
                                throws TextSourceAccessException

Throws:

TextSourceAccessException

createAnnotation

public SimpleInstance createAnnotation(Cls annotationCls,
                                       List<Span> spans,
                                       String spannedText,
                                       String textSourceName,
                                       SimpleInstance annotator,
                                       SimpleInstance set)
                                throws TextSourceAccessException

Throws:

TextSourceAccessException

createAnnotation

public SimpleInstance createAnnotation(SimpleInstance mention,
                                       SimpleInstance annotator,
                                       List<Span> spans,
                                       TextSource textSource,
                                       SimpleInstance annotationSet)
                                throws TextSourceAccessException

If the textSource does not have a corresponding instance in the kb, then one will be created.

Throws:

TextSourceAccessException

createAnnotation

public SimpleInstance createAnnotation(SimpleInstance mention,
                                       SimpleInstance annotator,
                                       List<Span> spans,
                                       SimpleInstance textSourceInstance,
                                       SimpleInstance annotationSet)
                                throws TextSourceAccessException

Throws:

TextSourceAccessException

createAnnotation

public SimpleInstance createAnnotation(SimpleInstance mention,
                                       SimpleInstance annotator,
                                       List<Span> spans,
                                       String spannedText,
                                       SimpleInstance textSourceInstance,
                                       Collection<SimpleInstance> annotationSets)
                                throws TextSourceAccessException

Throws:

TextSourceAccessException

createAnnotation

public SimpleInstance createAnnotation(SimpleInstance mention,
                                       SimpleInstance annotator,
                                       List<Span> spans,
                                       String spannedText,
                                       SimpleInstance textSourceInstance,
                                       Collection<SimpleInstance> annotationSets,
                                       String creationDate)
                                throws TextSourceAccessException

Creates an annotation. Overloaded to include the creation date in the annotation. Designed to be used for creating the annotation while importing an XML file.

Parameters:

creationDate - A String representation of the date (time stamp) the annotation was created.

Throws:

TextSourceAccessException

compareSpans

public boolean compareSpans(SimpleInstance annotation1,
                            SimpleInstance annotation2)

This method returns true if two annotations have exactly the same spans.

compareSpans

public boolean compareSpans(List<SimpleInstance> annotations)

isAnnotation

public boolean isAnnotation(SimpleInstance annotation)

hasTeamAnnotator

public boolean hasTeamAnnotator(SimpleInstance annotation)

setProjectAnnotator

public void setProjectAnnotator(SimpleInstance annotation)

setProjectAnnotationSet

public void setProjectAnnotationSet(SimpleInstance annotation)

getRelatedAnnotations

public Set<SimpleInstance> getRelatedAnnotations(SimpleInstance annotation)

Returns all annotations that are related to the passed in annotation. If an annotation is the slot value of another annotation (or more correctly if the mention of an annotation is a slot mention's value of another annotation's mention). This method recursively gathers all annotations that are related (not just directly related).

retrieveAllAnnotations

public List<SimpleInstance> retrieveAllAnnotations()

setAnnotator

public void setAnnotator(SimpleInstance annotation,
                         SimpleInstance annotator)

setSet

public void setSet(SimpleInstance annotation,
                   SimpleInstance set)

setSets

public void setSets(SimpleInstance annotation,
                    Collection<SimpleInstance> sets)

getSets

public Set<SimpleInstance> getSets(SimpleInstance annotation)

getTextSource

public SimpleInstance getTextSource(SimpleInstance annotation)

setTextSource

public void setTextSource(SimpleInstance annotation,
                          SimpleInstance textSource)

getText

public String getText(SimpleInstance annotation)

setText

public void setText(SimpleInstance annotation,
                    String spannedText)

spansOverlap

public boolean spansOverlap(SimpleInstance annotation1,
                            SimpleInstance annotation2)

getSize

public int getSize(SimpleInstance annotation)
            throws InvalidSpanException

Returns:

the size of the span associated with the annotation. If the annotation has more than one span, then the sum of the size of the spans is returned.

Throws:

InvalidSpanException - if the annotation has a badly formed span, then an exception will be thrown.

getShortestAnnotation

public SimpleInstance getShortestAnnotation(Collection<SimpleInstance> annotations)

This method returns the shortest annotation - that is the annotation whose span is the shortest. If an annotation has more than one span, then its size is the sum of the size of each of its spans.

Parameters:

annotations -

Returns:

will only return one annotation. In the case of a tie, will return the first annotation with the smallest size encountered during iteration. Returns null if annotation.size() == 0 or if each of the annotations has poorly formed spans (very unlikely).

getMention

public SimpleInstance getMention(SimpleInstance annotation)

setMention

public void setMention(SimpleInstance annotation,
                       SimpleInstance mention)

getAnnotator

public SimpleInstance getAnnotator(SimpleInstance annotation)

getComment

public String getComment(SimpleInstance annotation)

setComment

public void setComment(SimpleInstance annotation,
                       String comment)

getCreationDate

public String getCreationDate(SimpleInstance annotation)

setCreationDate

public void setCreationDate(SimpleInstance annotation,
                            String creationDate)