Agent based models

abm_plot(model::ABM; kwargs...) → fig, abmstepper

Plot an agent based model by plotting each individual agent as a marker and using the agent's position field as its location on the plot. Requires Agents.

Return the overarching fig object, as well as a struct abmstepper that can be used to interactively animate the evolution of the ABM and combine it with other subplots. To progress the ABM plot n steps simply do:

Agents.step!(abmstepper, model, agent_step!, model_step!, n)

You can still call this function with n=0 to update the plot for a new model, without doing any stepping. From fig you can obtain the plotted axis (to e.g. turn off ticks, etc.) using ax = content(fig[1, 1]).

Keywords

• ac, as, am: These three keywords decided the color, size, and marker, that each agent will be plotted as. They can each be either a constant or a function, which takes as an input a single argument and ouputs the corresponding value. For example:

  # ac = "#338c54"
  ac(a) = a.status == :S ? "#2b2b33" : a.status == :I ? "#bf2642" : "#338c54"
  # as = 10
  as(a) = 10*randn() + 1
  # as = :diamond
  as(a) = a.status == :S ? :circle : a.status == :I ? :diamond : :rect

• scheduler = model.scheduler: decides the plotting order of agents (which matters only if there is overlap).
• offset = nothing: If not nothing, it must be a function taking as an input an agent and outputting an offset position vector to be added to the agent's position (which matters only if there is overlap).
• equalaspect = true: Whether the plot should be of equal aspect ratio.
• scatterkwargs = (): Additional keyword arguments propagated to the scatter plot.
• resolution = (600, 600): Resolution of the fig.

abm_play(model, agent_step!, model_step!; kwargs...) → fig, abmstepper

Launch an interactive application that plots an agent based model and can animate its evolution in real time. Requires Agents.

The agents are plotted exactly like in abm_plot, while the two functions agent_step!, model_step! decide how the model will evolve, as in the standard approach of Agents.jl and its step! function.

The application has two buttons: "run" and "reset" which starts/stops the time evolution and resets the model to its original configuration. Two sliders control the animation speed: "spu" decides how many model steps should be done before the plot is updated, and "sleep" the sleep() time between updates.

Keywords

• ac, am, as, scheduler, offset, equalaspect, scatterkwargs: propagated to abm_plot.
• spu = 1:100: The values of the "spu" slider.

abm_video(file, model, agent_step! [, model_step!]; kwargs...)

This function exports the animated time evolution of an agent based model into a video saved at given path file, by recording the behavior of abm_play (without sliders). The plotting is identical as in abm_plot.

Keywords

• ac, am, as, scheduler, offset, equalaspect, scatterkwargs: propagated to abm_plot.
• spf = 1: Steps-per-frame, i.e. how many times to step the model before recording a new frame.
• framerate = 30: The frame rate of the exported video.
• frames = 300: How many frames to record in total.
• resolution = (600, 600): Resolution of the fig.
• axiskwargs = NamedTuple(): Keyword arguments given to the main axis creation for e.g. setting xticksvisible = false.

abm_data_exploration(model::ABM, agent_step!, model_step!, params=Dict(); kwargs...)

Open an interactive application for exploring an agent based model and the impact of changing parameters on the time evolution. Requires Agents.

The application evolves an ABM interactively and plots its evolution, while allowing changing any of the model parameters interactively and also showing the evolution of collected data over time (if any are asked for, see below). The agent based model is plotted and animated exactly as in abm_play, and the arguments model, agent_step!, model_step! are propagated there as-is.

Calling abm_data_exploration returns: figure, agent_df, model_df. So you can save the figure, but you can also access the collected data (if any).

Interaction

Besides the basic time evolution interaction of abm_play, additional functionality here allows changing model parameters in real time, based on the provided fourth argument params. This is a dictionary which decides which parameters of the model will be configurable from the interactive application. Each entry of params is a pair of Symbol to an AbstractVector, and provides a range of possible values for the parameter named after the given symbol (see example online). Changing a value in the parameter slides is only updated into the actual model when pressing the "update" button.

The "reset" button resets the model to its original agent and space state but it updates it to the currently selected parameter values. A red vertical line is displayed in the data plots when resetting, for visual guidance.

Keywords

• ac, am, as, scheduler, offset, equalaspect, scatterkwargs: propagated to abm_plot.
• adata, mdata: Same as the keyword arguments of Agents.run!, and decide which data of the model/agents will be collected and plotted below the interactive plot. Notice that data collection can only occur on plotted steps (and thus steps not plotted due to "spu" are also not data-collected).
• alabels, mlabels: If data are collected from agents or the model with adata, mdata, the corresponding plots have a y-label named after the collected data. Instead, you can give alabels, mlabels (vectors of strings with exactly same length as adata, mdata), and these labels will be used instead.
• when = true: When to perform data collection, as in Agents.run!.
• spu = 1:100: Values that the "spu" slider will obtain.