R/gettissueiso.R

In syanco/checkyourself: Simulates a simple agent-based species distribution model

#' gettissue
#'
#' Function to calculate tissue isotope values from a single simulated consumer.
#'
#' @param foodlist The list of food items sampled by an individual consumer.
#' This is the list generated by `eatfoodsteps`. Note that this function is
#' intededed to be called from `getiso` which iterates this function across
#' all individuals in a population of consumers (i.e., the list generated by
#' `eatfood`).
#' @param window Integer, the consumer isotope integration window representing
#' the number of steps across which prey isotope values are integrated in an
#' individual consumer to generate consumer tissue isotope values. Window must
#' be less than or equal to `time`.
#' @param time Integer, the step at which the simulated consumer tissue sample
#' is to be taken. Must be less than or equal to the total number of steps
#' simulated.
#'
#' @return A vector containing the C and N values for the simulated consumer
#' tissue.  Tissue values represent the mean isotope values for the prey
#' consumed between `time` - `window` and `time`.
#' @export
gettissue <- function(foodlist, window, time){
  relevant <- foodlist[((time-window+1):time)] #separate the relevant window
  #pull out the carbon values
  carbon <- lapply(relevant, FUN = function(values){carb <- values[1]})
  #pull out the nitrogen values
  nitrogen <- lapply(relevant, FUN = function(values){nit <- values[2]})
  #get the means
  carbmean <- mean(unlist(carbon))
  nitmean <- mean(unlist(nitrogen))
  #combine means into  vector for return
  isos <- c(carbmean, nitmean)
  return(isos)
}

#' getiso
#'
#'Wrapper function to iterate `gettissue` across the set of simulated consumers.
#'
#' @param window Integer, the consumer isotope integration window representing
#' the number of steps across which prey isotope values are integrated in an
#' individual consumer to generate consumer tissue isotope values. Window must
#' be less than or equal to `time`. Passed to `gettissue`.
#' @param time Integer, the step at which the simulated consumer tissue sample
#' is to be taken. Must be less than or equal to the total number of steps
#' simulated. Passed to `gettissue`.
#' @param food The list of simulated prey consumption histories for all
#' individual consumers. Note this is the list generated by `eatfood`.
#'
#' @return A list of simulated "sampled" C and N values for each simulated
#' consumer. Each element of the list represents the sampled value for a single
#' individual consumer and in each list element is a vector of the simulated
#' tissue C and N values (in that order) produced from `gettissue`.
#'
#' @export
getiso <- function(window, time, food){
  if(window >= time)
    stop("Integration window must be less than time step of analysis")
  isos <- lapply(food, gettissue, window = window, time = time)
  return(isos)
}


#' formatiso
#'
#'Convenience fucntion to format simulated consumer tissue isotope values into
#'a dataframe with columns for d13C and d15N and each row being an indivdiual
#'"observation". Default is to write the object to a .csv file formatted for
#'use by `MixSIAR` for mixture decomposition analysis, but can also return a
#' dataframe as an object.
#'
#' @param iso List of simulated "sampled" C and N values for each simulated
#' consumer. Note this should be the output from `getiso`.
#' @param filename String, the name of the file to be saved as a .csv.
#' @param writefile Boolean, whether to write the .csv to file. Default is T.
#' @param returnobject Boolean, whether to return a dataframe object. Default
#' is F
#'
#' @return A .csv written to file and/or a dataframe object.
#' @export
formatiso <- function(iso, filename, writefile = T, returnobject = F){
  #error checks
  if(!is.character(filename))
    stop("Filename must be supplied as a character string")

  #format data
  dat <- data.frame(matrix(unlist(iso), ncol = 2, byrow = T))
  names(dat) <- c("d13C", "d15N")

  #write file routine
  if(writefile == T)
    write.csv(dat, filename, row.names=FALSE)

  #return dataframe routine
  if(returnobject == T)
    return(dat)
}