# Functions for evaluation

source("aux.R")


ReadGold <- function(dframe){
  # Read the gold standard from a data frame
  # 
  # Args:
  #   dframe: The critical column names are Item and Gold. 
  #           No NA values are allowed
  #
  # Return: 
  #   A named vector of the gold standard annotation
  #   An error will be issued if there are different gold standards for an item
  #
  
  # Error handling
  CheckValidity(dframe, c("Item", "Gold"))
  
  # TODO: check uniqueness
  result <- tapply(dframe$Gold, dframe$Item, unique)
  
  return(result)
}

ObservedAgreement <- function(ann1, ann2){
  # Compute the observed agreement between two annotations 
  #
  # Args:
  #   ann1, ann2: named vectors representing the annotations.
  #
  # Return:
  #   The observed agreement, which is the number of annotations in ann1
  #   that agree with ann2, divided by the number of total items in ann1.
  #
  # Note that: 
  #   (1) NAs always count as disagreement 
  #   (2) ann1 need not contain every item in ann2, so strictly speaking 
  #       this function computes the observed agreement FOR ann1 from ann2.
  #   (3) If two annotations are for the same set of items, then the function
  #       is symmetric and thus computes the OA in the normal sense.
  
  return(sum(AgreementVector(ann1, ann2), na.rm=TRUE) / length(ann1))
}