Visualizations and Animations for Agent Based Models

This page describes functions that can be used in conjunction with Agents.jl to animate and interact with agent based models.

The animation at the start of the page is created using the code of this page, see below.

The docs are built using versions:

using Pkg
Pkg.status(["Agents", "InteractiveDynamics", "CairoMakie"];
    mode = PKGMODE_MANIFEST, io=stdout
)

Status `~/work/InteractiveDynamics.jl/InteractiveDynamics.jl/docs/Manifest.toml`
  [46ada45e] Agents v5.7.0
  [13f3f980] CairoMakie v0.10.2
  [ec714cd0] InteractiveDynamics v0.22.1 `~/work/InteractiveDynamics.jl/InteractiveDynamics.jl`

Static plotting of ABMs

Static plotting, which is also the basis for creating custom plots that include an abm plot, is done using the abmplot function. Its usage is exceptionally straight-forward, and in principle one simply defines functions for how the agents should be plotted. Here we will use a pre-defined model, the Daisyworld as an example throughout this docpage. To learn about this model you can visit the example hosted at AgentsExampleZoo ,

using InteractiveDynamics, Agents
using CairoMakie
daisypath = joinpath(dirname(pathof(InteractiveDynamics)), "agents", "daisyworld_def.jl")
include(daisypath)
model, daisy_step!, daisyworld_step! = daisyworld(;
    solar_luminosity = 1.0, solar_change = 0.0, scenario = :change
)
model

StandardABM with 360 agents of type Daisy
 space: GridSpaceSingle with size (30, 30), metric=chebyshev, periodic=true
 scheduler: fastest
 properties: temperature, solar_luminosity, max_age, surface_albedo, ratio, solar_change, tick, scenario

Now, to plot daisyworld is as simple as

daisycolor(a::Daisy) = a.breed # color of agents
as = 20 # size of agents
am = '✿' # marker of agents
scatterkwargs = (strokewidth = 1.0,) # add stroke around each agent
fig, ax, abmobs = abmplot(model; ac = daisycolor, as, am, scatterkwargs)
fig

To this, we can also plot the temperature of the planet by providing the access field as a heat array:

heatarray = :temperature
heatkwargs = (colorrange = (-20, 60), colormap = :thermal)
plotkwargs = (;
    ac = daisycolor, as, am,
    scatterkwargs = (strokewidth = 1.0,),
    heatarray, heatkwargs
)

fig, ax, abmobs = abmplot(model; plotkwargs...)
fig

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

GraphSpace models

While the ac, as, am keyword arguments generally relate to agent colors, markersizes, and markers, they are handled a bit differently in the case of GraphSpace models. Here, we collect those plot attributes for each node of the underlying graph which can contain multiple agents. If we want to use a function for this, we therefore need to handle an iterator of agents. Keeping this in mind, we can create an exemplary GraphSpace model and plot it with abmplot.

sir_model, sir_agent_step!, sir_model_step! = Models.sir()
city_size(agents_here) = 0.005 * length(agents_here)
function city_color(agents_here)
    agents_here = length(agents_here)
    infected = count(a.status == :I for a in agents_here)
    recovered = count(a.status == :R for a in agents_here)
    return RGBf(infected / agents_here, recovered / agents_here, 0)
end

city_color (generic function with 1 method)

To further style the edges and nodes of the resulting graph plot, we can leverage the functionality of GraphMakie.graphplot and pass all the desired keyword arguments to it via a named tuple called graphplotkwargs. When using functions for edge color and width, they should return either one color or a vector with the same length (or twice) as current number of edges in the underlying graph. In the example below, the edge_color function colors all edges to a semi-transparent shade of grey and the edge_width function makes use of the special ability of linesegments to be tapered (i.e. one end is wider than the other).

using GraphMakie.Graphs
edge_color(model) = fill((:grey, 0.25), ne(model.space.graph))
function edge_width(model)
    w = zeros(ne(model.space.graph))
    for e in edges(model.space.graph)
        push!(w, 0.004 * length(model.space.stored_ids[e.src]))
        push!(w, 0.004 * length(model.space.stored_ids[e.dst]))
    end
    return w
end
graphplotkwargs = (
    layout = Shell(), # node positions
    arrow_show = false, # hide directions of graph edges
    edge_color = edge_color, # change edge colors and widths with own functions
    edge_width = edge_width,
    edge_plottype = :linesegments # needed for tapered edge widths
)
fig, ax, abmobs = abmplot(sir_model;
    agent_step! = sir_agent_step!, model_step! = sir_model_step!,
    as = city_size, ac = city_color, graphplotkwargs)
fig

Interactive ABM Applications

Continuing from the Daisyworld plots above, we can turn them into interactive applications straightforwardly, simply by providing the stepping functions as illustrated in the documentation of abmplot. Note that GLMakie should be used instead of CairoMakie when wanting to use the interactive aspects of the plots.

fig, ax, abmobs = abmplot(model;
    agent_step! = daisy_step!, model_step! = daisyworld_step!,
    plotkwargs...)
fig

One could click the run button and see the model evolve. Furthermore, one can add more sliders that allow changing the model parameters.

params = Dict(
    :surface_albedo => 0:0.01:1,
    :solar_change => -0.1:0.01:0.1,
)
fig, ax, abmobs = abmplot(model;
    agent_step! = daisy_step!, model_step! = daisyworld_step!,
    params, plotkwargs...)
fig

One can furthermore collect data while the model evolves and visualize them using the convenience function abmexploration

using Statistics: mean
black(a) = a.breed == :black
white(a) = a.breed == :white
adata = [(black, count), (white, count)]
temperature(model) = mean(model.temperature)
mdata = [temperature, :solar_luminosity]
fig, abmobs = abmexploration(model;
    agent_step! = daisy_step!, model_step! = daisyworld_step!, params, plotkwargs...,
    adata, alabels = ["Black daisys", "White daisys"], mdata, mlabels = ["T", "L"]
)

abmexploration(model::ABM; alabels, mlabels, kwargs...)

ABM Videos

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

E.g., continuing from above,

model, daisy_step!, daisyworld_step! = daisyworld()
abmvideo(
    "daisyworld.mp4",
    model,  daisy_step!, daisyworld_step!;
    title = "Daisy World", frames = 150,
    plotkwargs...
)

Agent inspection

It is possible to inspect agents at a given position by hovering the mouse cursor over the scatter points in the agent plot. Inspection is automatically enabled for interactive applications (i.e. when either agent or model stepping functions are provided). To manually enable this functionality, simply add enable_inspection = true as an additional keyword argument to the abmplot/abmplot! call. A tooltip will appear which by default provides the name of the agent type, its id, pos, and all other fieldnames together with their current values. This is especially useful for interactive exploration of micro data on the agent level.

The tooltip can be customized by extending InteractiveDynamics.agent2string.

agent2string(agent::A)

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

Creating custom ABM plots

The existing convenience function abmexploration will always display aggregated collected data as scatterpoints connected with lines. In cases where more granular control over the displayed plots is needed, we need to take a few extra steps and utilize the ABMObservable returned by abmplot. The same steps are necessary when we want to create custom plots that compose animations of the model space and other aspects.

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

To do custom animations you need to have a good idea of how Makie's animation system works. Have a look at this tutorial if you are not familiar yet.

create a basic abmplot with controls and sliders

model, = daisyworld(; solar_luminosity = 1.0, solar_change = 0.0, scenario = :change)
fig, ax, abmobs = abmplot(model;
    agent_step! = daisy_step!, model_step! = daisyworld_step!, params, plotkwargs...,
    adata, mdata, figure = (; resolution = (1600,800))
)
fig

abmobs

ABMObservable with model:
StandardABM with 360 agents of type Daisy
 space: GridSpaceSingle with size (30, 30), metric=chebyshev, periodic=true
 scheduler: fastest
 properties: temperature, solar_luminosity, max_age, surface_albedo, ratio, solar_change, tick, scenario
and with data collection:
 adata: Tuple{Function, typeof(count)}[(Main.var"ex-agents".black, count), (Main.var"ex-agents".white, count)]
 mdata: Any[Main.var"ex-agents".temperature, :solar_luminosity]

create a new layout to add new plots to to the right of the abmplot

plot_layout = fig[:,end+1] = GridLayout()

GridLayout[1:1, 1:1] with 0 children

create a sublayout on its first row and column

count_layout = plot_layout[1,1] = GridLayout()

GridLayout[1:1, 1:1] with 0 children

collect tuples with x and y values for black and white daisys

blacks = @lift(Point2f.($(abmobs.adf).step, $(abmobs.adf).count_black))
whites = @lift(Point2f.($(abmobs.adf).step, $(abmobs.adf).count_white))

Observable(Point{2, Float32}[[0.0, 180.0]])

create an axis to plot into and style it to our liking

ax_counts = Axis(count_layout[1,1];
    backgroundcolor = :lightgrey, ylabel = "Number of daisies by color")

Axis with 0 plots:

plot the data as scatterlines and color them accordingly

scatterlines!(ax_counts, blacks; color = :black, label = "black")
scatterlines!(ax_counts, whites; color = :white, label = "white")

Combined{Makie.scatterlines, Tuple{Vector{Point{2, Float32}}}}

add a legend to the right side of the plot

Legend(count_layout[1,2], ax_counts; bgcolor = :lightgrey)

Legend()

and another plot, written in a more condensed format

ax_hist = Axis(plot_layout[2,1];
    ylabel = "Distribution of mean temperatures\nacross all time steps")
hist!(ax_hist, @lift($(abmobs.mdf).temperature);
    bins = 50, color = :red,
    strokewidth = 2, strokecolor = (:black, 0.5),
)

fig

Now, once we step the abmobs::ABMObservable, the whole plot will be updated

Agents.step!(abmobs, 1)
Agents.step!(abmobs, 1)
fig

Of course, you need to actually adjust axis limits given that the plot is interactive

autolimits!(ax_counts)
autolimits!(ax_hist)

Or, simply trigger them on any update to the model observable:

on(abmobs.model) do m
    autolimits!(ax_counts)
    autolimits!(ax_hist)
end

ObserverFunction defined at none:2 operating on Observable(StandardABM with 784 agents of type Daisy
 space: GridSpaceSingle with size (30, 30), metric=chebyshev, periodic=true
 scheduler: fastest
 properties: temperature, solar_luminosity, max_age, surface_albedo, ratio, solar_change, tick, scenario)

and then marvel at everything being auto-updated by calling step! :)

for i in 1:100; step!(abmobs, 1); end
fig