ca: Run cellular automata simulation.
In fdschneider/caspr: Cellular Automata for Spatial Pressure in R

Description Usage Arguments Details Value Examples

Run cellular automata simulation.

ca(x, model = grazing, parms = "default", t_max = 200, saveeach = 1,
  stopifsteady = FALSE, steady = caspr::steady, steadyparms = list(t_eval
  = 200, accept = 0.001), t_min = 0, plotting = FALSE,
  filename = "modelrun", seed = NULL, ...)

`x`	A landscape object.
`model`	A valid object of class 'ca_model'. Defaults to musselbed. Valid values are: `musselbed`, `grazing`.
`parms`	A list of parameters with one or several parameters containing a vector of parameter values. Those will be combined full-factorially using `expand.grid()`. Will be checked against template parameters in `model`. If not provided, template parameters will be used.
`t_max`	Maximal number of timesteps. Model will be terminated even if still in transient dynamics (i.e. model did not reach steady state)
`saveeach`	Timespan between timesteps at which a full snapshot of the landscape is saved into the output of the simulation.
`stopifsteady`	Binary parameter, defaults to FALSE. If TRUE, the function provided in parameter `steady` will be applied to test in each timestep if steady state is reached.
`steady`	A function returning TRUE or FALSE, taking exactly the parameters `i`, `result`, `steadyparms`. By default the function returns TRUE if the difference in mean cover of the primary cell state (i.e. the first in the vector provided in `model$states`) over two subsequent timespans of length `steadyparms$t_eval` is smaller than `steadyparms$accept`.
`steadyparms`	a list of parameters that are required by the function provided in `steady`.
`plotting`	A binary variable. If TRUE, simulation is plotted into an animated gif.
`filename`	A character string. Filename of animated gif (defaults to "modelrun.gif") which will be placed in current working directory. If not provided global seeds of R apply.
`seed`	An integer number serving as seed for random number generation.
`...`	Parameters handed over to update function in `model$update`.
`t_eval`	Timespan of moving window that is evaluated for the end of transient dynamics.

Runs iterations of the update function model$update() on the initial landscape x until a t_max is reached. The function saves the full timeseries, i.e. a value for each timestep, of the global cover of each state as well as the average local cover of each state. The full landscape object of each timestep is stored in a list result$landscapes of the output object, but frequency of these snapshots can be altered by increasing the parameter saveeach.

The output is returned as a list object of class ca_result, containing a full timeseries of global and local cover as well as snapshots of the landscape.

$model: The entire model object used to generate this simulation run, including the parameters at $model$parms
$time: Vector of timesteps.
$issteady: Binary vector reporting for each timestep if the criterion for steady state was fulfilled. The criterion can be customized by adjusting parameter steady.
$cover: A list of cover timeseries for each state of the model.
$local: A list of local cover timeseries for each state of the model.
$snaps: A vector of indices of saved snapshots.
$landscapes: A list of landscape objects at each point in $snaps
$issteady: A binary vector of the returned values of function steady

# 1. run simulation and save a snapshot each 50 timesteps. plot timeseries and snapshots.

l <- init_landscape(c("+","0","-"), c(0.6,0.2,0.2), width = 100) 
p <- list(r = 0.4, d = 0.9, delta = 0.01)   # set parameters
r <- ca(l, model = musselbed, parms = p, t_max = 200)    # run simulation
plot(r)

par(mfrow= c(2,3))
sapply(c(0,25,50,100,150,200)+1, function(i) plot(r$landscapes[[i]]) )

# 2. run simulation and save full landsape at each timestep. create animated gif.

l <- init_landscape(c("1","0"), c(0.6,0.4), 100)
r <- ca(l, model = life, t_max = 400)
animate(r, "life01.gif")