R/sigmaSEA.R

Defines functions sigmaSEA

Documented in sigmaSEA

#' Calculate metrics corresponding to the Standard Ellipse based on a 
#' covariance matrix
#' 
#' This function takes a covariance 2x2 matrix Sigma and returns various 
#' metrics relating to the corresponding Standard Ellipse. The function is 
#' limited to the 2-dimensional case, as many of the ancilliary summary 
#' statistics are not defined for higher dimensions (e.g. eccentricity).
#' 
#' @section Note: This function is currently based on the eigenvalue and 
#'   eigenvector approach which is more flexible for higher dimensional problems
#'   method for calculating the standard ellipse, and replaces the parametric
#'   method used previously in siar and siber. 
#' 
#' @param sigma a 2x2 covariance ellipse.
#' 
#' @return A list comprising the following metrics for summarising the Standard 
#' Ellipse
#' #' \itemize{
#'    \item {SEA}{ the Standard Ellise Area (not sample size corrected)}
#'    \item {eccentricity}{ a measure of the elongation of the ellipse.}
#'    \item {a}{ the length of the semi-major axis}
#'    \item {b}{ the length of the semi-minor axis}
#' }
#' 
#' @examples
#' # A perfect circle
#' sigma <- matrix( c(1, 0, 0, 1), 2, 2)
#' sigmaSEA(sigma)
#' 
#' @export
#' 


sigmaSEA <- function(sigma){

  eig <- eigen(sigma)
  
  a <- sqrt(eig$values[1])
  b <- sqrt(eig$values[2])
  
  # As of v2.0.4 I have replaced the asin() line with atan which 
  # returns the angle of correct sign due to the inclusion of the quotient
  # of the vectors.
  theta <- atan(eig$vectors[2,1] / eig$vectors[1,1])
  
  SEA <- pi*a*b
  

  out <- list()
  out$SEA <- pi*a*b
  out$eccentricity <- sqrt(1-((b^2)/(a^2)))
  out$a <- a
  out$b <- b
  out$theta <- theta

  return(out)
}

Try the SIBER package in your browser

Any scripts or data that you put into this service are public.

SIBER documentation built on May 30, 2017, 2:03 a.m.