Plotting and interactive application

Plotting and interaction functionality comes from InteractiveDynamics, another package of JuliaDynamics, which uses Makie.jl.

Plotting, and the interactive application of Agents.jl, are model-agnostic and simple to use. Defining simple functions that map agents to colors, and shapes, is the only thing you need to do. If you have already defined an ABM and functions for stepping the model, you typically need to write only an extra couple of lines of code to get your visualizations going.

You need to install both InteractiveDynamics, as well as a plotting backend (we recommend GLMakie) to use the following functions.

The version of InteractiveDynamics used in the docs is:

using Pkg
Pkg.status("InteractiveDynamics")
      Status `~/work/Agents.jl/Agents.jl/docs/Project.toml`
  [ec714cd0] InteractiveDynamics v0.16.2

Some parts of Agents.jl cannot be plotted yet in Makie.jl, and therefore alternatives are provided. However in the near future we hope to have moved everything to plotting with Makie.jl and not necessitate usage of Plots.jl or other libraries.

Plotting

The following functions allow you to plot an ABM, animate it via play/pause buttons, or directly export the time evolution into a video. At the moment these functions support 2D continuous and discrete space.

InteractiveDynamics.abm_plotFunction
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. The figure is not displayed by default, you need to either return fig as a last statement in your functions or simply call display(fig). Notice that models with DiscreteSpace are plotted starting from 0 to n, with n the space size along each dimension.

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]). See Sugarscape for an example of using abmstepper to make an animation of evolving the ABM and a heatmap in parallel with only a few lines of code.

Agent related 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
    # am = :diamond
    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).

  • 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).

  • scatterkwargs = (): Additional keyword arguments propagated to the scatter plot. If am is/returns Polygons, then these arguments are propagated to a poly plot.

Model and figure related keywords

  • 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_some_matrix_from_model... and set heatarray = f. The heatmap will be updated automatically during model evolution in videos and interactive applications.
  • heatkwargs = (colormap=:tokyo,) : Keyowrds given to Makie.heatmap function if heatarray is not nothing.
  • aspect = DataAspect(): The aspect ratio behavior of the axis.
  • resolution = (600, 600): Resolution of the figugre.
  • 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 = CairoMakie.scatter!([50 50]; color = :red) # Show position of teacher
        CairoMakie.hidedecorations!(ax) # hide tick labels etc.
        CairoMakie.translate!(obj, 0, 0, 5) # be sure that the teacher will be above students
    end
InteractiveDynamics.abm_playFunction
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, aspect, scatterkwargs: propagated to abm_plot.
  • spu = 1:100: The values of the "spu" slider.
InteractiveDynamics.abm_videoFunction
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

  • 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.
  • resolution = (600, 600): Resolution of the fig.
  • axiskwargs = NamedTuple(): Keyword arguments given to the main axis creation for e.g. setting xticksvisible = false.
  • kwargs...: All other keywords are propagated to abm_plot.

Interactive application

InteractiveDynamics.abm_data_explorationFunction
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, aspect, 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.

Here is an example application made with InteractiveDynamics.abm_data_exploration from the Daisyworld example.

Graph plotting

To plot agents existing of a GraphSpace we can't use InteractiveDynamics because Makie.jl does not support plotting on graphs (yet). We provide the following function in this case, which comes into scope when using Plots. See also the SIR model for the spread of COVID-19 example for an application.

Agents.abm_plot_on_graphFunction
abm_plot_on_graph(model::ABM{<: GraphSpace}; ac, as, am, kwargs...)

This function plots an ABM with a GraphSpace. It functions similarly with [abm_plot], but is based on Plots.jl (specifically GraphRecipes.jl).

The three key functions ac, as, am do not get an agent as an input but a vector of agents at each node of the graph. Their output is the same: the color, size, and marker type of the node.

Here as defaults to length. Internally, the graphplot recipe is used, and all other kwargs... are propagated there.

source

Open Street Map plotting

Plotting an open street map is also not possible with Makie.jl at the moment, but there is a Julia package that does this kind of plotting, OpenStreetMapXPlots.jl. Its usage is demonstrated in the Zombie Outbreak example page.

Plots.jl Recipes

Whilst the primary method for plotting agents models is through InteractiveDynamics, the following Plots recipes can also be used if you prefer the Plots.jl ecosystem.

Notice that these methods will emit a warning. Pass warn = false to suppress it.

Agents.plotabmFunction
plotabm(model::ABM{<: ContinuousSpace}; ac, as, am, kwargs...)
plotabm(model::ABM{<: DiscreteSpace}; ac, as, am, kwargs...)

Plot the model as a scatter-plot, by configuring the agent color, size and marker (shape) via the keywords ac, as, am. These keywords can be constants, or they can be functions, each accepting an agent and outputting a valid value for color/size/marker.

The keyword scheduler = model.scheduler decides the plotting order of agents (which matters only if there is overlap).

The keyword offset is a function with argument offest(a::Agent). It targets scenarios where multiple agents existin within a grid cell as it adds an offset (same type as agent.pos) to the plotted agent position.

All other keywords are propagated into Plots.scatter and the plot is returned.

plotabm(model::ABM{<: GraphSpace}; ac, as, am, kwargs...)

This function is the same as plotabm for ContinuousSpace, but here the three key functions ac, as, am do not get an agent as an input but a vector of agents at each node of the graph. Their output is the same.

Here as defaults to length. Internally, the graphplot recipe is used, and all other kwargs... are propagated there.

source
Agents.plotabm!Function
plotabm!(model)
plotabm!(plt, model)

Functionally the same as plotabm, however this method appends to the active plot, or one identified as plt.

source