Utopia features


Visualization allows you intuitively grasp and present the model dynamics.

Utopia provides a host of tools to this end, from animated graphs, agent plots, and cellular automata, to 3-dimensional scatter plots, stacked lines and errorbars, heatmaps, all directly controllable and customisable from the config, and optimised for high-dimensional data. You are also free to add your own custom plot functions: they will integrate seamlessly with the framework.

Animations can make complex dynamics much more comprehensible, and are easy to create using the Utopia plotting framework. Utopia provides animations for agent-based models, graphs, and cellular automata. They are easily controllable from the config. If you want to create your own animation, useful wrappers and tools are at hand to make the process a breeze!

For instance, creating an animated plot of the SEIRD model is simple:

ca/age:                     # name of the plot
    - .creator.universe     # one plot per universe
    - .plot.ca              # specialized CA plot
    - .animation.ffmpeg     # turn on the animation

  select:                   # the data to plot …
    age: age

  to_plot:                  # … and how to plot it
      title: Age
      cmap: YlGn
      limits: [0, max]

You can also use the animations.frames writer to output the frames of the animation as separate snapshots.

More details arrow-right

Utopia provides the .plot.ca function for a simple interface to create plots of cellular automata, including animations. .plot.ca (implemented in utopya) is optimized for plotting two-dimensional cellular automata, such as the grid-based Utopia SEIRD and ForestFire models.

To plot a snapshot of a two-dimensional state, base your plot on .plot.ca and include the .plot.ca.snapshot modifier. You can specify the time of the snapshot with the frames_isel argument (-1 by default). By basing the plot on an animation function, you can easily turn the snapshots into animations – no need to touch code.

More details arrow-right
feature image Example plot from the ForestFire model, showing a snapshot of the forest age.

Utopia uses utopya’s .plot.graph function to make plotting networks and network properties easy. You can plot data as the node size and/or color, plot data as the edge weights, highlight certain nodes and edges using mark_nodes and mark_edges, adjust the plot style and coloring, and even animate your network plot – right from a configuration file, without having to touch python code.

The .plot.graph plot function combines and extends the following four NetworkX plotting utilities:

It preserves the full configurability of the above functions while offering additional features, e.g. plotting directly from a GraphGroup, automatically mapping data to layout properties, or creating graph animations.

More details arrow-right
feature image Example network plot from the Utopia Opinionet model, showing users in a social network. The colors of the nodes encode the opinion value, and the edge widths encode the edge weights. Several nodes and edges have been marked for illustration purposes.

Utopya’s abmplot() function, accessible via the .plot.abm base configuration, is specialized to visualize time series of agent-based models (ABM), i.e. the position and certain properties of agents in their domain. You can data variables onto the agent positions and their color over time, even creating animations.

Visualising high dimensional data containing many variables and coordinates is made easy with facetting, the ability to plot data dimensions onto different axes, colors, and even arranging plots into rows and columns. Utopia combines and extends xarray’s facetting capabilities to allow you to select where to plot which variable right from the config. It even supports auto encoding, meaning variables are automatically distributed onto available dimensions.

More details arrow-right
feature image Infection curves for the Utopia SEIRD model, showing the densities of the susceptible (lightgreen), infected (red), and recovered (darkgreen) cells as a function of time, averaged over different initialisations. The column dimension shows different values of the immunity rate, and the row shows different values of the transmission rate. This plot thus plots data onto six different axes (x, y, yerr, hue, row, col).

Sometimes, all the above tools are simply not required or do not suffice to achieve a certain data analysis or visualization task.

For such cases, Utopia allows to call user-specified Python plotting functions as part of the processing pipeline. These functions can be imported from a specific module or even from a separate Python file and can still make use of many of the features of the dantro plotting framework.

More details arrow-right