R/nullmodel.R

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

#' rand.sel
#'
#' Simulation of a null model where individuals simply randomly lccate on the landscape with no locational
#' preferences. Each iteration of this function represents a single individual settling a landscape randomly.
#'
#' @param hab.mat The matrix containing the "grown" habitats enumerated by the strength of preference
#' (e.g., the output from pref.strength, not convert.cell.). This matrix is only used to calculate the
#' size of the landscape from which the agent chooses.
#' @param ... Additional arguments as necessary.
#'
#' @return Returns a single number: the cell ID of the randomly chosen location.
#' @export
rand.sel <- function(hab.mat, ...) {
  samp <- sample(length(hab.mat), size=1, replace = T) #choose a random cell in the matrix, unweighted
  return(samp)
}

#' settle.rand
#'
#' A convenience function that allows 'rand.sel' to be iterated across multiple individuals ('n.individ')
#' Allows the entire ABM to be run an arbitray number of times  (see `reps` below) in order to generate a
#' sampling distribution of apparent selections generated by the model.
#'
#' @param n.individ The number of individuals to simulate for a single model run.
#' @param hab.mat The matrix containing the "grown" habitats enumerated by the strength of preference
#' (e.g., the output from pref.strength, not convert.cell.) Note that which hab.mat to use (i.e., which
#' preference strength to use) is arbitrary for the null model, but the choice must match the A.coef supplied (below).
#' @param A.coef The habitat preference parameter that matches the hab.mat supplied.  This is the "key" that
#' allows the function to interpret each cell of the matrix as either "Habitat A" or "Habitat B".
#' @param ... Additional arguments as necessary.
#'
#' @return A list, the first element of which is the set of coordinates for the settled location of each individual and
#' the 2nd element of which is the proportion of those indviduals that settled within "Habitat A".  If the model is iterated,
#' returns a list of such lists.
#' @export
settle.rand<- function(n.individ, hab.mat, A.coef, ...) {
  loc <- replicate(n.individ, rand.sel(hab.mat = hab.mat))

  #calculate proportion habitat selected
  hab.sel <- hab.mat[loc]
  sel.p <- mean(hab.sel == A.coef)
  result <- list(loc, sel.p)
  return(result)
}

#' repRand
#'
#' Convenience funtion to iterate the null model (settle.rand) reps number of times.
#' @param reps Number of model runs to simulate (each run conisting of n.individ number of individuals settling)
#' @param n.individ The number of individuals to simulate for a single model run. Passed to settle.rand.
#' @param hab.mat The matrix containing the "grown" habitats enumerated by the strength of preference
#' (e.g., the output from pref.strength, not convert.cell.) Note that which hab.mat to use (i.e., which
#' preference strength to use) is arbitrary for the null model, but the choice must match the A.coef supplied (below).
#' Passed to settle.rand.
#' @param A.coef The habitat preference parameter that matches the hab.mat supplied.  This is the "key" that
#' allows the function to interpret each cell of the matrix as either "Habitat A" or "Habitat B". Passed to settle.rand.
#' @param ... Additional arguments as necessary.
#'
#' @return A list of list, each element of which is the result of a single model run, Within the results of each model run,
#' the first element is the set of coordinates for the settled location of each individual and the 2nd element is the
#' proportion of those indviduals that settled within "Habitat A".
#' @export
repRand <- function(reps, n.individ, hab.mat, A.coef, ...) {
  sampling.rand <- list(replicate(reps, settle.rand(n.individ = n.individ,
                                               hab.mat = hab.mat,
                                               A.coef = A.coef)))
  names(sampling.rand) <- "--"
  return(sampling.rand)
}