Package org.dkpro.statistics.agreement.coding

Class CodingAnnotationStudy

java.lang.Object
org.dkpro.statistics.agreement.AnnotationStudy
org.dkpro.statistics.agreement.coding.CodingAnnotationStudy
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, ICodingAnnotationStudy, IAnnotationStudy
public class CodingAnnotationStudy
extends AnnotationStudy
implements ICodingAnnotationStudy, java.lang.Cloneable, java.io.Serializable
Default implementation of the ICodingAnnotationStudy interface. Instantiate this class for representing the annotation item of a coding study (i.e., an annotation setup in which the (human) raters are asked to code a set of given annotation items). The standard way of representing the annotation units (i.e., the category assigned by a certain rater) of an annotation item is using the addItem(Object...) method which allows specifying the list of categories assigned by the raters.
Author:
Christian M. Meyer
See Also:
ICodingAnnotationStudy, ICodingAnnotationItem, Serialized Form

  • Field Details

  • Constructor Details

    • CodingAnnotationStudy

      protected CodingAnnotationStudy()
      Initializes and empty annotation study for a coding task. The basic setup of a coding study is assigning categories to units with fixed boundaries.

    • CodingAnnotationStudy

      public CodingAnnotationStudy​(int raterCount)
      Initializes and empty annotation study for a coding task with the given number of raters. The basic setup of a coding study is assigning categories to units with fixed boundaries.

  • Method Details

    • addItem

      protected void addItem​(ICodingAnnotationItem item)
      Add the given annotation item to this study. The specified item should never be null. When relying on the default implementation CodingAnnotationItem, it is recommended to use addItem(Object...) instead.

    • addItem

      public ICodingAnnotationItem addItem​(java.lang.Object... annotations)
      Creates a new CodingAnnotationItem which has been coded with the given annotation categories. Note that the order of the categories must correspond to the raters' indexes. Use null to represent missing annotations, Invoking addItem("A", "B", null, "A") indicates an annotation item which has been coded as category "A" by rater 0 and 3 and as category "B" by rater 1. Rater 2 did not assign any category to the item. The method is a shorthand for addItemAsArray(Object[]).
      Throws:
      java.lang.IllegalArgumentException - if the number of annotations does not match the number of raters.

    • addItemAsArray

      public ICodingAnnotationItem addItemAsArray​(java.lang.Object[] annotations)
      Creates a new CodingAnnotationItem which has been coded with the given annotation categories. Note that the order of the categories must correspond to the raters' indexes. Use null to represent missing annotations, Invoking addItem(new Object[]{"A", "B", null, "A"}) indicates an annotation item which has been coded as category "A" by rater 0 and 3 and as category "B" by rater 1. Rater 2 did not assign any category to the item.
      Throws:
      java.lang.IllegalArgumentException - if the number of annotations does not match the number of raters.

    • addMultipleItems

      public void addMultipleItems​(int times, java.lang.Object... values)
      Shorthand for invoking addItem(Object...) with the same parameters multiple times. This method is useful for modeling annotation data based on a contingency table.

    • createUnit

      protected IAnnotationUnit createUnit​(int index, int raterIdx, java.lang.Object category)

    • getItem

      public ICodingAnnotationItem getItem​(int index)
      Description copied from interface: ICodingAnnotationStudy
      Returns the annotation item with the given index. The first item has index 0.
      Specified by:
      getItem in interface ICodingAnnotationStudy

    • getItems

      public java.lang.Iterable<ICodingAnnotationItem> getItems()
      Description copied from interface: ICodingAnnotationStudy
      Allows iterating all annotation items of this study.
      Specified by:
      getItems in interface ICodingAnnotationStudy

    • getItemCount

      public int getItemCount()
      Description copied from interface: ICodingAnnotationStudy
      Returns the number of annotation items defined by the study.
      Specified by:
      getItemCount in interface ICodingAnnotationStudy

    • getUnitCount

      public int getUnitCount()
      Description copied from interface: ICodingAnnotationStudy
      Returns the number of annotation units defined by the study. That is, the number of annotations coded by the raters. If there are no missing values, the unit count equals the item count multiplied with the number of raters.
      Specified by:
      getUnitCount in interface IAnnotationStudy
      Specified by:
      getUnitCount in interface ICodingAnnotationStudy

    • hasMissingValues

      public boolean hasMissingValues()
      Description copied from interface: ICodingAnnotationStudy
      Returns true if, and only if, the annotation study contains at least one item with a missing value (i.e., an annotation item containing an annotation unit with category null).
      Specified by:
      hasMissingValues in interface ICodingAnnotationStudy

    • clone

      public CodingAnnotationStudy clone()
      Overrides:
      clone in class java.lang.Object

    • stripCategories

      public CodingAnnotationStudy stripCategories​(java.lang.Object keepCategory, java.lang.Object nullCategory)
      Returns a clone of the current annotation study in which all categories are replaced by the given nullCategory except the categories matching the specified keepCategory.

    • extractRaters

      public CodingAnnotationStudy extractRaters​(int... raters)
      Returns a clone of the current annotation study which contains only the annotation units of the raters with the given indexes. All other units will be removed. This method is useful for converting an annotation study with multiple raters into a (pairwise) annotation study with two raters.

    • countAnnotationsPerCategory

      public static java.util.Map<java.lang.Object,​int[]> countAnnotationsPerCategory​(ICodingAnnotationStudy study)
      Returns a two-dimensional map of categories and raters and the corresponding usage frequencies in the given annotation study (i.e., how often a certain rater used a certain category for coding an annotation unit).

    • countTotalAnnotationsPerCategory

      public static java.util.Map<java.lang.Object,​java.lang.Integer> countTotalAnnotationsPerCategory​(ICodingAnnotationStudy study)
      Returns a map of categories and their usage frequencies (i.e., how often they are used in annotation units) within the given annotation study.

    • countTotalAnnotationsPerCategory

      public static java.util.Map<java.lang.Object,​java.lang.Integer> countTotalAnnotationsPerCategory​(ICodingAnnotationItem item)
      Returns a map of categories and their usage frequencies (i.e., how often they are used in annotation units) within the given annotation item.

    • countCategoryCoincidence

      public static java.util.Map<java.lang.Object,​java.util.Map<java.lang.Object,​java.lang.Double>> countCategoryCoincidence​(ICodingAnnotationStudy study)
      Returns a two dimensional map of category pairs and their co-occurrence frequencies for the given annotation study.

    • countCategoryCoincidence

      public static java.util.Map<java.lang.Object,​java.util.Map<java.lang.Object,​java.lang.Double>> countCategoryCoincidence​(ICodingAnnotationItem item)
      Returns a two dimensional map of category pairs and their co-occurrence frequencies for the given annotation item.