de.julielab.jcore.utility

Class JCoReAnnotationTools

java.lang.Object

de.julielab.jcore.utility.JCoReAnnotationTools

public class JCoReAnnotationTools
extends Object

Most of this functionality is found in UIMAfit nowadays and should be used from there. Some very specific methods like getOverlappingAnnotation(JCas, String, int, int) do not have a direct correspondent, however, and might still be useful.

Constructor Summary

Constructors

Constructor and Description
JCoReAnnotationTools()

Method Summary

Modifier and Type	Method and Description
static <T extends org.apache.uima.jcas.tcas.Annotation> T	getAnnotationAtMatchingOffsets(org.apache.uima.jcas.JCas aJCas, org.apache.uima.jcas.tcas.Annotation focusAnnotation, Class<T> cls)
static org.apache.uima.jcas.tcas.Annotation	getAnnotationAtOffset(org.apache.uima.jcas.JCas aJCas, String fullAnnotationClassName, int startOffset, int endOffset) returns an annotation of the type fullEntityClassName which has exactly the specified offset
static org.apache.uima.jcas.tcas.Annotation	getAnnotationByClassName(org.apache.uima.jcas.JCas aJCas, String fullAnnotationClassName) returns an annotation object (de.julielab.jcore.types.annotation) of the type specified by fullEntityClassName.
static <T extends org.apache.uima.jcas.tcas.Annotation> List<T>	getIncludedAnnotations(org.apache.uima.jcas.JCas aJCas, org.apache.uima.jcas.tcas.Annotation focusAnnotation, Class<T> cls) Returns, in ascending order, all annotations of type cls that are completely included - perhaps with having the same begin and/or end as the focusAnnotation - in focusAnnotation.
static <T extends org.apache.uima.jcas.tcas.Annotation> T	getIncludingAnnotation(org.apache.uima.jcas.JCas aJCas, org.apache.uima.jcas.tcas.Annotation focusAnnotation, Class<T> cls) Returns the leftmost annotation of type cls that completely includes focusAnnotation.
static <T extends org.apache.uima.jcas.tcas.Annotation> T	getLastOverlappingAnnotation(org.apache.uima.jcas.JCas aJCas, org.apache.uima.jcas.tcas.Annotation focusAnnotation, Class<T> cls) Returns the annotation with the highest end offset of type cls overlapping focusAnnotation.
static <T extends org.apache.uima.jcas.tcas.Annotation> T	getNearestIncludingAnnotation(org.apache.uima.jcas.JCas aJCas, org.apache.uima.jcas.tcas.Annotation focusAnnotation, Class<T> cls) Returns the nearest annotation of class cls to focusAnnotation, i.e.
static <T extends org.apache.uima.jcas.tcas.Annotation> List<T>	getNearestOverlappingAnnotations(org.apache.uima.jcas.JCas aJCas, org.apache.uima.jcas.tcas.Annotation focus, Class<T> cls) Returns the nearest annotations of class cls to focusAnnotation.
static <T extends org.apache.uima.jcas.tcas.Annotation> List<T>	getNearestOverlappingAnnotations(org.apache.uima.jcas.JCas aJCas, int begin, int end, Class<T> cls) Convenience method that internally calls getNearestOverlappingAnnotations(JCas, Annotation, Class).
static org.apache.uima.jcas.tcas.Annotation	getOverlappingAnnotation(org.apache.uima.jcas.JCas aJCas, String fullAnnotationClassName, int startOffset, int endOffset) returns an annotation of the type fullEntityClassName which overlaps an or is overlapped by an annotation of the same type at the given offset
static <T extends org.apache.uima.jcas.tcas.Annotation> T	getPartiallyOverlappingAnnotation(org.apache.uima.jcas.JCas aJCas, org.apache.uima.jcas.tcas.Annotation focusAnnotation, Class<T> cls) Returns the leftmost annotation of type cls that overlaps focusAnnotation.
static org.apache.uima.jcas.tcas.Annotation	getPartiallyOverlappingAnnotation(org.apache.uima.jcas.JCas aJCas, String fullAnnotationClassName, int startOffset, int endOffset) returns an annotation of the type fullEntityClassName which partially overlaps an or is overlapped by an annotation of the same type at the given offset

Methods inherited from class java.lang.Object

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

Constructor Detail

JCoReAnnotationTools

public JCoReAnnotationTools()

Method Detail

getAnnotationByClassName

public static org.apache.uima.jcas.tcas.Annotation getAnnotationByClassName(org.apache.uima.jcas.JCas aJCas,
                                                                            String fullAnnotationClassName)
                                                                     throws ClassNotFoundException,
                                                                            SecurityException,
                                                                            NoSuchMethodException,
                                                                            IllegalArgumentException,
                                                                            InstantiationException,
                                                                            IllegalAccessException,
                                                                            InvocationTargetException

returns an annotation object (de.julielab.jcore.types.annotation) of the type specified by fullEntityClassName. This is done by means of dynamic class loading and reflection.

Parameters:

aJCas - the jcas to which to link this annotation object

fullAnnotationClassName - the full class name of the new annotation object

Returns:

Throws:

ClassNotFoundException

SecurityException

NoSuchMethodException

IllegalArgumentException

InstantiationException

IllegalAccessException

InvocationTargetException

getAnnotationAtOffset

public static org.apache.uima.jcas.tcas.Annotation getAnnotationAtOffset(org.apache.uima.jcas.JCas aJCas,
                                                                         String fullAnnotationClassName,
                                                                         int startOffset,
                                                                         int endOffset)
                                                                  throws SecurityException,
                                                                         IllegalArgumentException,
                                                                         ClassNotFoundException,
                                                                         NoSuchMethodException,
                                                                         InstantiationException,
                                                                         IllegalAccessException,
                                                                         InvocationTargetException

returns an annotation of the type fullEntityClassName which has exactly the specified offset

Parameters:

aJCas - the cas to search in

fullAnnotationClassName - the full class name of the specific annotation type

startOffset -

endOffset -

Returns:

the first annotation object of the given type at exactly the given offset. If no annotation is found there, NULL is returned

Throws:

SecurityException

IllegalArgumentException

ClassNotFoundException

NoSuchMethodException

InstantiationException

IllegalAccessException

InvocationTargetException

getAnnotationAtMatchingOffsets

public static <T extends org.apache.uima.jcas.tcas.Annotation> T getAnnotationAtMatchingOffsets(org.apache.uima.jcas.JCas aJCas,
                                                                                                org.apache.uima.jcas.tcas.Annotation focusAnnotation,
                                                                                                Class<T> cls)

getOverlappingAnnotation

public static org.apache.uima.jcas.tcas.Annotation getOverlappingAnnotation(org.apache.uima.jcas.JCas aJCas,
                                                                            String fullAnnotationClassName,
                                                                            int startOffset,
                                                                            int endOffset)
                                                                     throws SecurityException,
                                                                            IllegalArgumentException,
                                                                            ClassNotFoundException,
                                                                            NoSuchMethodException,
                                                                            InstantiationException,
                                                                            IllegalAccessException,
                                                                            InvocationTargetException

returns an annotation of the type fullEntityClassName which overlaps an or is overlapped by an annotation of the same type at the given offset

Parameters:

aJCas - The cas to search in

ullAnnotationClassName - The full class name of the specific annotation type

startOffset -

endOffset -

Returns:

The first annotation object of the given type at exactly the given offset. If no annotation is found there, NULL is returned

Throws:

SecurityException

IllegalArgumentException

ClassNotFoundException

NoSuchMethodException

InstantiationException

IllegalAccessException

InvocationTargetException

getPartiallyOverlappingAnnotation

public static org.apache.uima.jcas.tcas.Annotation getPartiallyOverlappingAnnotation(org.apache.uima.jcas.JCas aJCas,
                                                                                     String fullAnnotationClassName,
                                                                                     int startOffset,
                                                                                     int endOffset)
                                                                              throws SecurityException,
                                                                                     IllegalArgumentException,
                                                                                     ClassNotFoundException,
                                                                                     NoSuchMethodException,
                                                                                     InstantiationException,
                                                                                     IllegalAccessException,
                                                                                     InvocationTargetException

returns an annotation of the type fullEntityClassName which partially overlaps an or is overlapped by an annotation of the same type at the given offset

Parameters:

aJCas - The cas to search in

fullAnnotationClassName - The full class name of the specific annotation type

startOffset -

endOffset -

Returns:

The first annotation object of the given type at exactly the given offset. If no annotation is found there, NULL is returned

Throws:

SecurityException

IllegalArgumentException

ClassNotFoundException

NoSuchMethodException

InstantiationException

IllegalAccessException

InvocationTargetException

getPartiallyOverlappingAnnotation

public static <T extends org.apache.uima.jcas.tcas.Annotation> T getPartiallyOverlappingAnnotation(org.apache.uima.jcas.JCas aJCas,
                                                                                                   org.apache.uima.jcas.tcas.Annotation focusAnnotation,
                                                                                                   Class<T> cls)

Returns the leftmost annotation of type cls that overlaps focusAnnotation. That is, if multiple annotations of type cls overlap with focusAnnotation, the one with the lowest begin offset will be chosen.

The two annotations may overlap in any way (partial, nested, inclusion, exact match). This algorithm has O(n) runtime with n being the number of annotations in the annotation index.

*

TODO: A start offset parameter could be introduced from where to start looking. This way, when iterating over a number of different focusAnnotations in ascending order, one would have only to check from focusAnnotation to focusAnnotation and not always from the very beginning of the annotation index. Same thing for getIncludingAnnotation().

Parameters:

aJCas -

focusAnnotation -

cls -

Returns:

the leftmost annotation of type cls that overlaps focusAnnotation.

getIncludedAnnotations

public static <T extends org.apache.uima.jcas.tcas.Annotation> List<T> getIncludedAnnotations(org.apache.uima.jcas.JCas aJCas,
                                                                                              org.apache.uima.jcas.tcas.Annotation focusAnnotation,
                                                                                              Class<T> cls)

Returns, in ascending order, all annotations of type cls that are completely included - perhaps with having the same begin and/or end as the focusAnnotation - in focusAnnotation.

Parameters:

aJCas -

focusAnnotation -

cls -

Returns:

getIncludingAnnotation

public static <T extends org.apache.uima.jcas.tcas.Annotation> T getIncludingAnnotation(org.apache.uima.jcas.JCas aJCas,
                                                                                        org.apache.uima.jcas.tcas.Annotation focusAnnotation,
                                                                                        Class<T> cls)

Returns the leftmost annotation of type cls that completely includes focusAnnotation. That is, if multiple annotations of type cls include focusAnnotation, the one with the lowest begin offset will be chosen.

This algorithm has O(n) runtime with n being the number of annotations in the annotation index.

TODO: A start offset parameter could be introduced from where to start looking. This way, when iterating over a number of different focusAnnotations in ascending order, one would have only to check from focusAnnotation to focusAnnotation and not always from the very beginning of the annotation index. Same thing for getPartiallyOverlappingAnnotation().

Parameters:

aJCas -

focusAnnotation -

cls -

Returns:

the leftmost annotation of type cls that completely includes focusAnnotation.

getNearestIncludingAnnotation

public static <T extends org.apache.uima.jcas.tcas.Annotation> T getNearestIncludingAnnotation(org.apache.uima.jcas.JCas aJCas,
                                                                                               org.apache.uima.jcas.tcas.Annotation focusAnnotation,
                                                                                               Class<T> cls)

Returns the nearest annotation of class cls to focusAnnotation, i.e. the one (or just one, if multiple exist) with the highest start-offset that completely overlaps focusAnnotation.

This method has nice performance properties when it is known that the annotation looked for is near, e.g. finding the nearest token or sentence.

Parameters:

aJCas -

focusAnnotation -

cls -

Returns:

the leftmost annotation of type cls that completely includes focusAnnotation.

getNearestOverlappingAnnotations

public static <T extends org.apache.uima.jcas.tcas.Annotation> List<T> getNearestOverlappingAnnotations(org.apache.uima.jcas.JCas aJCas,
                                                                                                        int begin,
                                                                                                        int end,
                                                                                                        Class<T> cls)

Convenience method that internally calls getNearestOverlappingAnnotations(JCas, Annotation, Class). This method creates a dummy focus annotation with the given offsets, adds it to CAS indexes, receives the overlapping annotations and removes the focus annotation from indexes again.

This method has nice performance properties when it is known that the annotation looked for is near, e.g. finding overlapping tokens.

Parameters:

aJCas - CAS with the annotations.

begin - Focus begin.

end - Focus end.

cls - The class of the sought annotations.

Returns:

the leftmost annotation of type cls that completely includes focusAnnotation.

getNearestOverlappingAnnotations

public static <T extends org.apache.uima.jcas.tcas.Annotation> List<T> getNearestOverlappingAnnotations(org.apache.uima.jcas.JCas aJCas,
                                                                                                        org.apache.uima.jcas.tcas.Annotation focus,
                                                                                                        Class<T> cls)

Returns the nearest annotations of class cls to focusAnnotation. Those are all annotations a with a.begin > focus.begin but still overlapping focus plus the annotation with a.begin <= focus.begin.

This method has nice performance properties when it is known that the annotation looked for is near, e.g. finding overlapping tokens.

Parameters:

aJCas - The CAS with annotations.

focus - The focus annotation to get overlapping annotations for.

cls -

Returns:

the leftmost annotation of type cls that completely includes focusAnnotation.

getLastOverlappingAnnotation

public static <T extends org.apache.uima.jcas.tcas.Annotation> T getLastOverlappingAnnotation(org.apache.uima.jcas.JCas aJCas,
                                                                                              org.apache.uima.jcas.tcas.Annotation focusAnnotation,
                                                                                              Class<T> cls)

Returns the annotation with the highest end offset of type cls overlapping focusAnnotation.

This method is very similar to getNearestOverlappingAnnotations(JCas, Annotation, Class). Actually, the last result element of getNearestOverlappingAnnotations(JCas, Annotation, Class) equals the returned annotation from this method.

Parameters:

aJCas -

focusAnnotation -

cls -

Returns: