trace_plotter {chouca}

Plot simulation covers

Description

This function creates an internal function to plot the model landscape during the simulation of a stochastic cellular automaton.

Usage

trace_plotter(
  mod,
  initmat,
  fun = NULL,
  col = NULL,
  max_samples = 256,
  fps_cap = 24,
  burn_in = 0,
  new_window = TRUE,
  ...
)

Arguments

mod

The model being used (created by link{camodel})

initmat

The initial landscape given to run_camodel

fun

The function used to summarise the landscape into summary metrics. By default, gloal covers of each state are computed. It must return a vector of numeric values.

col

a set of colors (character vector) of length equal to the number of values returned by fun.

max_samples

The maximum number of samples to display in the plot

fps_cap

The maximum number of frame displayed per seconds. Simulation will be slowed down if necessary so that plot updates will not be more frequent than this value

burn_in

Do not display anything before this time step has been reached

new_window

Controls whether the plots are displayed in a new window, or in the default device (typically the plot panel in Rstudio)

...

other arguments passed to matplot, which is used to display the trends.

Details

This function creates another function that is suitable for use with run_camodel. It can plot any quantity computed on the landscape as it is being simulated, using the base function matplot. The resulting function must by passed to run_camodel as the control argument custom_output_fun. Typically, this function is not used by itself, but is being used when specifying simulation options before calling run_camodel, see examples below.

By default, the global covers of each state in the landscape will be displayed, but you can pass any function as argument fun to compute something else, as long as fun returns a numeric vector of length at least 1.

matplot is used internally, and tends to be quite slow at displaying results, but if it is still too fast for your taste, you can cap the refresh rate at a value given by the argument fps_cap.

It is important to note that this function will probably massively slow down a simulation, so it is mostly here for exploratory analyses, or just to have a good look of what is happening in a model.

Value

This function returns another function, which will be called internally when simulating the model using run_camodel, and has probably not much use outside of this context. The return function will display the simulation and returns NULL.

See Also

landscape_plotter, run_camodel

Examples

 

# Display covers of the rock/paper/scissor model as it is running
mod <- ca_library("rock-paper-scissor")
init <- generate_initmat(mod, rep(1, 3)/3, nrow = 100, ncol = 178)
ctrl <- list(custom_output_every = 1,
             custom_output_fun = trace_plotter(mod, init))
run_camodel(mod, init, times = seq(0, 256), control = ctrl)

# Adjust colors of the previous example and increase speed
colors <- c("#fb8500", "#023047", "#8ecae6")
ctrl <- list(custom_output_every = 1,
             custom_output_fun = trace_plotter(mod, init, fps_cap = 60, col = colors))
run_camodel(mod, init, times = seq(0, 600), control = ctrl)

# Display the vegetated to degraded cover ratio for the arid
# vegetation model. 
mod <- ca_library("aridvege")
init <- generate_initmat(mod, rep(1, 3)/3, nrow = 100, ncol = 178)
ratio <- function(mat) {
  mean(mat == "VEGE") / mean(mat == "DEGR")
}
ctrl <- list(custom_output_every = 1,
             custom_output_fun = trace_plotter(mod, init,
                                               fun = ratio))
run_camodel(mod, init, times = seq(0, 512), control = ctrl)

# Display ratios of cell pairs in the rock-paper-scissor model
mod <- ca_library("rock-paper-scissor")
init <- generate_initmat(mod, rep(1, 3)/3, nrow = 100, ncol = 178)
ratio <- function(mat) {
  c(mean(mat == "r") / mean(mat == "p"), 
    mean(mat == "p") / mean(mat == "c"), 
    mean(mat == "c") / mean(mat == "r"))
}
ctrl <- list(custom_output_every = 1,
             custom_output_fun = trace_plotter(mod, init,
                                               fun = ratio))
run_camodel(mod, init, times = seq(0, 512), control = ctrl)