Visualizations and Animations for Agent Based Models

abmplot(model::ABM; kwargs...) → fig, ax, abmobs
abmplot!(ax::Axis/Axis3, model::ABM; kwargs...) → abmobs

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. The same function is used to make custom composite plots and interactive applications for the model evolution using the returned abmobs. abmplot is also used to launch interactive GUIs for evolving agent based models, see "Interactivity" below.

Requires Agents. See also abmvideo and abmexploration.

Keyword arguments

Agent related

• ac, as, am : These three keywords decide 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 agent and outputs the corresponding value.

  Using constants: ac = "#338c54", as = 10, am = :diamond

  Using functions:

  ac(a) = a.status == :S ? "#2b2b33" : a.status == :I ? "#bf2642" : "#338c54"
  as(a) = 10rand()
  am(a) = a.status == :S ? :circle : a.status == :I ? :diamond : :rect

  Notice that for 2D models, am can be/return a Polygon instance, which plots each agent as an arbitrary polygon. It is assumed that the origin (0, 0) is the agent's position when creating the polygon. In this case, the keyword as is meaningless, as each polygon has its own size. Use the functions scale, rotate2D to transform this polygon.

  3D models currently do not support having different markers. As a result, am cannot be a function. It should be a Mesh or 3D primitive (such as Sphere or Rect3D).

• offset = nothing : If not nothing, it must be a function taking as an input an agent and outputting an offset position tuple to be added to the agent's position (which matters only if there is overlap).

• scatterkwargs = () : Additional keyword arguments propagated to the scatter! call.

Preplot related

• heatarray = nothing : A keyword that plots a heatmap over the space. Its values can be standard data accessors given to functions like run!, i.e. either a symbol (directly obtain model property) or a function of the model. The returned data must be a matrix of the same size as the underlying space. For example heatarray = :temperature is used in the Daisyworld example. But you could also define f(model) = create_matrix_from_model... and set heatarray = f. The heatmap will be updated automatically during model evolution in videos and interactive applications.

  It is strongly recommended to use abmplot instead of the abmplot! method if you use heatarray, so that a colorbar can be placed naturally.

• heatkwargs = NamedTuple() : Keywords given to Makie.heatmap function if heatarray is not nothing.

• add_colorbar = true : Whether or not a Colorbar should be added to the right side of the heatmap if heatarray is not nothing.

• static_preplot! : A function f(ax, model) that plots something after the heatmap but before the agents. Notice that you can still make objects of this plot be visible above the agents using a translation in the third dimension like below:

  function static_preplot!(ax, model)
      obj = scatter!(ax, [50 50]; color = :red) # Show position of teacher
      hidedecorations!(ax) # hide tick labels etc.
      translate!(obj, 0, 0, 5) # be sure that the teacher will be above students
  end

• osmkwargs = NamedTuple() : keywords directly passed to osmplot! from OSMMakie.jl if model space is OpenStreetMapSpace.

The stand-alone function abmplot also takes two optional NamedTuples named figure and axis which can be used to change the automatically created Figure and Axis objects.

Interactivity

Evolution related

• agent_step!, model_step! = Agents.dummystep: Stepping functions to pass to ABMObservable which itself passes to Agents.step!.
• add_controls::Bool: If true, abmplot switches to "interactive application" mode. This is by default true if either agent_step! or model_step! keywords are provided. These stepping functions are used to evolve the model interactively using Agents.step!. The application has the following interactive elements:
  1. "step": advances the simulation once for spu steps.
  2. "run": starts/stops the continuous evolution of the model.
  3. "reset model": resets the model to its initial state from right after starting the interactive application.
  4. 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.
• enable_inspection = add_controls: If true, enables agent inspection on mouse hover.
• spu = 1:50: The values of the "spu" slider.
• params = Dict() : 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 propagated to the actual model after a press of the "update" button.

Data collection related

• adata, mdata, when: Same as the keyword arguments of Agents.run!. If either or both adata, mdata are given, data are collected and stored in the abmobs, see ABMObservable. The same keywords provide the data plots of abmexploration. This also adds the button "clear data" which deletes previously collected agent and model data by emptying the underlying DataFrames adf/mdf. Reset model and clear data are independent processes.

See the documentation string of ABMObservable for custom interactive plots.

abmexploration(model::ABM; alabels, mlabels, 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 abmplot, and the model argument as well as splatted kwargs are propagated there as-is. This convencience function only works for aggregated agent data.

Calling abmexploration returns: fig::Figure, p::_ABMPlot. So you can save and/or further modify the figure. But it is also possible to access the collected data (if any) via the plot object, just like in the case of using abmplot directly.

Clicking the "reset" button will add a red vertical line to the data plots for visual guidance.

Keywords arguments (in addition to those in abmplot)

• alabels, mlabels: If data are collected from agents or the model with adata, mdata, the corresponding plots' y-labels are automatically named after the collected data. It is also possible to provide alabels, mlabels (vectors of strings with exactly same length as adata, mdata), and these labels will be used instead.
• figure = NamedTuple(): Keywords to customize the created Figure.
• axis = NamedTuple(): Keywords to customize the created Axis.
• plotkwargs = NamedTuple(): Keywords to customize the styling of the resulting scatterlines plots.

abmvideo(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 the interactive version of abmplot (without sliders). The plotting is identical as in abmplot and applicable keywords are propagated.

Keywords

• 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, including the starting frame.
• title = "": The title of the figure.
• showstep = true: If current step should be shown in title.
• figure = NamedTuple(): Figure related keywords (e.g. resolution, backgroundcolor).
• axis = NamedTuple(): Axis related keywords (e.g. aspect).
• kwargs...: All other keywords are propagated to abmplot.

agent2string(agent::A)

Convert agent data into a string which is used to display all agent variables and their values in the tooltip on mouse hover. Concatenates strings if there are multiple agents at one position. Custom tooltips for agents can be implemented by adding a specialised method for agent2string. Example:

import InteractiveDynamics.agent2string
function agent2string(agent::SpecialAgent)
    """
    ✨ SpecialAgent ✨
    ID = $(agent.id)
    Main weapon = $(agent.charisma)
    Side weapon = $(agent.pistol)
    """
end

ABMObservable(model; agent_step!, model_step!, adata, mdata, when) → abombs

abmobs contains all information necessary to step an agent based model interactively. It is also returned by abmplot.

Calling Agents.step!(abmobs, n) will step the model for n using the provided agent_step!, model_step!, n as in Agents.step!.

The fields abmobs.model, abmobs.adf, abmobs.mdf are observables that contain the AgentBasedModel, and the agent and model dataframes with collected data. Data are collected as described in Agents.run! using the adata, mdata, when keywords. All three observables are updated on stepping (when it makes sense). The field abmobs.s is also an observable containing the current step number.

All plotting and interactivity should be defined by lifting these observables.