Nothing
#' Identify predator signature proportions beyond range of prey
#'
#' The function \code{pred_beyond_prey} identifies predator signaturee
#' proportions that are outside the range of proportions observed in the
#' individual and mean prey signatures.
#'
#' @param pred_sigs A numeric matrix of predator signature(s) in
#' column-major format. Intended to be the object \code{pred_sigs} returned by
#' the function \code{\link{est_diet}}.
#' @param prey_sigs A numeric matrix of prey signatures in column-major format.
#' Intended to be the object \code{prey_sigs} returned by the function
#' \code{\link{est_diet}}.
#' @param mean_sigs A numeric matrix of mean prey-type signatures. Intended to
#' be the object \code{prey_sigs} returned by the function
#' \code{\link{est_diet}}.
#'
#' @return A list containing the following elements: \describe{
#' \item{beyond_ind}{A logical matrix with TRUE indicating that the
#' corresponding predator proportion is outside the range of individual
#' prey proportions.}
#' \item{beyond_mean}{A logical matrix with TRUE indicating that the
#' corresponding predator proportion is outside the range of mean prey
#' proportions.}
#' \item{err_code}{An integer error code (0 if no error is detected).}
#' \item{err_message}{A string contains a brief summary of the execution.}
#' }
#'
#' @section Details:
#' In quantitative fatty acid signature analysis, predator signatues are assumed
#' to be a linear mixture of mean prey signatures (Iverson et al. 2004).
#' Predator signature proportions should therefore be within the range of
#' the prey signature proportions. Signature proportions outside the range of
#' prey proportions are indicative of a violation of one or both of the primary
#' model assumptions, i.e., the prey library is incomplete or the calibration
#' coefficients are inaccurate (Bromaghin et al. 2015, 2016a). Consequently,
#' checking for predator proportions that are outside the range of mean prey
#' proportions is an important diagnostic aid to evaluate the reliability
#' of diet estimates.
#'
#' The function \code{pred_beyond_prey} identifies predator signature
#' proportions that outside the range of proportions observed among the
#' individual and mean prey signatures. For purposes of diet estimation,
#' proportions outside the range of the mean signatures are most important.
#' However, \code{pred_beyond_prey} also identifies predator proportions that
#' are outside the range of the individual prey proportions for exploratory
#' purposes.
#'
#' \code{pred_beyond_prey} is designed to be called with inputs returned by the
#' function \code{\link{est_diet}}. Although it is not conceptually necessary to
#' estimate diets before performing this diagnostic check, doing so ensures that
#' the predator and prey signatures have been transformed to the optimization
#' space (Bromaghin et al. 2015) in which diets have been estimated.
#'
#' @section References:
#' Iverson, S.J., C. Field, W.D. Bowen, and W. Blanchard. 2004.
#' Quantitative fatty acid signature analysis: A new method of
#' estimating predator diets. \emph{Ecological Monographs} 74:211-235.
#'
#' Bromaghin, J.F., S.M. Budge, G.W. Thiemann, and K.D. Rode. 2016. Assessing
#' the robustness of quantitative fatty acid signature analysis to assumption
#' violations. \emph{Methods in Ecology and Evolution} 7:51-59.
#'
#' Bromaghin, J.F., K.D. Rode, S.M. Budge, and G.W. Thiemann. 2015. Distance
#' measures and optimization spaces in quantitative fatty acid signature
#' analysis. \emph{Ecology and Evolution} 5:1249-1262.
#'
#' @examples
#' pred_beyond_prey(pred_sigs = matrix(c(0.05, 0.10, 0.30, 0.55,
#' 0.04, 0.11, 0.29, 0.56,
#' 0.10, 0.05, 0.35, 0.50,
#' 0.12, 0.03, 0.37, 0.48,
#' 0.10, 0.06, 0.35, 0.49,
#' 0.05, 0.15, 0.35, 0.45), ncol = 6),
#' prey_sigs = matrix(c(0.06, 0.09, 0.31, 0.54,
#' 0.05, 0.09, 0.30, 0.56,
#' 0.03, 0.10, 0.30, 0.57,
#' 0.08, 0.07, 0.30, 0.55,
#' 0.09, 0.05, 0.33, 0.53,
#' 0.09, 0.06, 0.34, 0.51,
#' 0.09, 0.07, 0.34, 0.50,
#' 0.08, 0.11, 0.35, 0.46,
#' 0.06, 0.14, 0.36, 0.44), ncol = 9),
#' mean_sigs = matrix(c(0.047, 0.093, 0.303, 0.557,
#' 0.087, 0.050, 0.323, 0.530,
#' 0.077, 0.106, 0.350, 0.467), ncol = 3))
#'
#' @export
#'
################################################################################
pred_beyond_prey <- function(pred_sigs, prey_sigs, mean_sigs){
# Check inputs for errors ----------------------------------------------------
# Initialize objects for return. The return objects pred_sig and prey_sig
# are not included because they are input arguments and involved in the
# following error checks.
beyond_ind <- NA
beyond_mean <- NA
# Check that pred_sigs is a numeric matrix.
if(!(is.numeric(pred_sigs) & is.matrix(pred_sigs))){
err_code <- 1
err_message <- "The argument pred_sigs is not a numeric matrix!"
return(list(beyond_ind = beyond_ind,
beyond_mean = beyond_mean,
err_code <- err_code,
err_message <- err_message))
}
# Check that pred_sigs are non-negative and their sums do not exceed 1.
# If sig_prep() was called with scale = 2, the signatures will not sum to 1.
if((min(pred_sigs) < 0) | is.na(min(pred_sigs))){
err_code <- 2
err_message <- "One or more predator signatures are invalid!"
return(list(beyond_ind = beyond_ind,
beyond_mean = beyond_mean,
err_code <- err_code,
err_message <- err_message))
}
# Check that prey_sigs is a numeric matrix.
if(!(is.numeric(prey_sigs) & is.matrix(prey_sigs))){
err_code <- 3
err_message <- "The argument prey_sigs is not a numeric matrix!"
return(list(beyond_ind = beyond_ind,
beyond_mean = beyond_mean,
err_code <- err_code,
err_message <- err_message))
}
# Check that prey_sigs are non-negative and their sums do not exceed 1.
# If sig_prep() was called with scale = 2, the signatures will not sum to 1.
if((min(prey_sigs) < 0) | is.na(min(prey_sigs))){
err_code <- 4
err_message <- "One or more prey signatures are invalid!"
return(list(beyond_ind = beyond_ind,
beyond_mean = beyond_mean,
err_code <- err_code,
err_message <- err_message))
}
# Check that mean_sigs is a numeric matrix.
if(!(is.numeric(mean_sigs) & is.matrix(mean_sigs))){
err_code <- 5
err_message <- "The argument mean_sigs is not a numeric matrix!"
return(list(beyond_ind = beyond_ind,
beyond_mean = beyond_mean,
err_code <- err_code,
err_message <- err_message))
}
# Check that mean_sigs are non-negative and their sums do not exceed 1.
# If sig_prep() was called with scale = 2, the signatures will not sum to 1.
if((min(mean_sigs) < 0) | is.na(min(mean_sigs))){
err_code <- 6
err_message <- "One or more mean prey signatures are invalid!"
return(list(beyond_ind = beyond_ind,
beyond_mean = beyond_mean,
err_code <- err_code,
err_message <- err_message))
}
# Check that signature length are equal.
if((nrow(pred_sigs) != nrow(prey_sigs)) | (nrow(pred_sigs) != nrow(mean_sigs))){
err_code <- 7
err_message <- "The signatures are not of equal length!"
return(list(beyond_ind = beyond_ind,
beyond_mean = beyond_mean,
err_code <- err_code,
err_message <- err_message))
}
# Individual prey signatures -------------------------------------------------
# Compute minima and maxima.
min_prop <- matrix(data = apply(X = prey_sigs, MARGIN = 1, FUN = min),
nrow = nrow(pred_sigs), ncol = ncol(pred_sigs))
max_prop <- matrix(data = apply(X = prey_sigs, MARGIN = 1, FUN = max),
nrow = nrow(pred_sigs), ncol = ncol(pred_sigs))
# Identify proportions beyond prey range.
beyond_ind <- (pred_sigs < min_prop) | (pred_sigs > max_prop)
# Mean prey signatures -------------------------------------------------------
# Compute minima and maxima.
min_prop <- matrix(data = apply(X = mean_sigs, MARGIN = 1, FUN = min),
nrow = nrow(mean_sigs), ncol = ncol(pred_sigs))
max_prop <- matrix(data = apply(X = mean_sigs, MARGIN = 1, FUN = max),
nrow = nrow(mean_sigs), ncol = ncol(pred_sigs))
# Identify proportions beyond prey range.
beyond_mean <- (pred_sigs < min_prop) | (pred_sigs > max_prop)
# Return ---------------------------------------------------------------------
err_code <- 0
err_message <- "Success!"
return(list(beyond_ind = beyond_ind,
beyond_mean = beyond_mean,
err_code = err_code,
err_message = err_message))
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.