R/similarity_flag.R

In ianjonsen/foieGras: Fit Continuous-Time State-Space and Latent Variable Models for Quality Control of Argos Satellite (and Other) Telemetry Data and for Estimating Changes in Animal Movement

##' @title Add similarity flag value to a \code{sim_fit} object
##' 
##' @description Calculate the similarity between a single path generated by sim_fit and the
##' observed path used in the SSM fit. In this context, similarity is calculated 
##' as the sum of normalised differences in net displacement (km) and overall 
##' bearing (deg) between the SSM-estimated path and the simulated paths. Similarity
##' flag values are based on two interpretations of the difference in overall distance 
##' and bearing between the two paths. 
##' 
##' @param track a dataframe containing longitude and latitudes of the observed
##' path used in the SSM fit
##' @param sim_track a dataframe containing the longitude and latitude of a single 
##' simulated path from sim_fit
##' @param flag set to either 1 or 2 to define similarity index (see details)
##' @param cpf logical; are tracks simulated as central place foraging trips. If
##' cpf = TRUE then distance & bearing are calculated from the first location to
##' the most distant location, otherwise distance & bearing are calculated from
##' the first to the last location on each track.
##' 
##' @details
##' \code{flag = 1} will use an index based on Hazen (2017)\cr
##' \code{flag = 2} (the default) will use a custom index
##' 
##' @return a single value representing the similarity in distance and bearing between the two paths
##' 
##' @keywords internal
##' 
##' @export
similarity_flag <- function(track, sim_track, flag = 2, cpf){
  
  if(cpf) {
    n <- which(track$dist == max(track$dist, na.rm = TRUE))
  } else {
    n <- nrow(track)
  }
  
  if(flag == 1) {
    return(2 * (track$dist[n] - sim_track$dist[n]) / track$dist[n] + 
             (track$bear[n] - sim_track$bear[n]) / 90)
  } else {
    return(((track$dist[n] - sim_track$dist[n]) / track$dist[n]) + 
             ((track$bear[n] - sim_track$bear[n]) / track$bear[n]))
  }

}