Interactive application

The interactive application of Agents.jl is model-agnostic. This means that provided that the space of the model is one of the supported types (currently only 2D GridSpace or ContinuousSpace), the application does not care about the model dynamics or agent properties.

The app is based on InteractiveChaos, another package of JuliaDynamics.

Here is an example application

the application is made with the following function:

InteractiveChaos.interactive_abm — Function
interactive_abm(model::ABM, agent_step!, model_step!, params=Dict(); kwargs...)

Open an interactive application for exploring an Agent-Based-Model. 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).

model, agent_step!, model_step! are the same arguments that step! or run! from Agents accept.

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

Interaction

Buttons and sliders on the right-hand-side allow running/pausing the application. The slider sleep controls how much sleep time should occur after each plot update. The slider spu is the steps-per-update, i.e. how many times to step the model before updating the plot.

The final argument params is a dictionary and 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. 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, as, am: either constants, or functions each accepting an agent and outputting a valid value for the agent color, shape, or size.
  • scheduler = model.scheduler: decides the plotting order of agents (which matters only if there is overlap).
  • offset = nothing: Can be a function accepting an agent and returning an offset position that adjusts the agent's position when plotted (which matters only if there is overlap).
  • 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!.
  • equalaspect = true: Set the ABM scatterplot's aspect ratio to equal.
  • spu = 1:100: Values that the "spu" slider will obtain.

The animation at the start of this page was done with:

using Agents, Random
using Makie
using InteractiveChaos

model, agent_step!, model_step! = Models.forest_fire()

alive(model) = count(a.status for a in allagents(model))
burning(model) = count(!a.status for a in allagents(model))
mdata = [alive, burning, nagents]
mlabels = ["alive", "burning", "total"]

params = Dict(
    :f => 0.02:0.01:1.0,
    :p => 0.01:0.01:1.0,
)

ac(a) = a.status ? "#1f851a" : "#67091b"
am = :rect

p1 = interactive_abm(model, agent_step!, model_step!, params;
ac = ac, as = 1, am = am, mdata = mdata, mlabels=mlabels)