Plot Functions#

utopya provides a number of additional plot functions over those already made available via dantro. Visualize Cellular Automata (CA)#

The caplot() function, accessible via the base configuration, is specialized to visualize time series of cellular automaton (CA) data.

To select this plot function, the following configuration can be used as a starting point:

    - .creator.pyplot       # or some other creator
    -              # select the CA plotting function

  select:                   # specify which data to select
      path: path/to/some/data

  to_plot:                  # and which data to plot
      title: some custom title
      cmap: inferno
      limits: [min, max]
      # ... more arguments here, see docstring

For more information, see below.

Square grids#

Typically, cellular automata use a grid discretization with square cells. The output (as an animation) may look like this:

Hexagonal grids#

The caplot() function integrates imshow_hexagonal(), which can plot data from cellular automata that use hexagonal cells. The output (for the same dummy data as used above) may look like this:

imshow_hexagonal() is used for plotting if the grid_structure argument is set to hexagonal or if the given data has data attributes that specify that grid structure.


For an excellent introduction to hexagonal grid representations, see this article.

Specifying properties for hexagonal grid structure

To plot hexagonal grids, more information is required than for square grids; imshow_hexagonal() documents which parameters are needed.

This information can be specified via the plot configuration or alongside the data as metadata attributes. The latter approach is preferable, because it is self-documenting and reduces future errors.

If you store that information alongside the data, it needs to be accessible via the xarray.DataArray.attrs of the data passed to caplot(). Depending on your data source, there are different ways to achieve this.

  • For xarray objects, simply use assignments like my_data.attrs["pointy_top"] = True.

  • If your data is loaded from HDF5 datasets into the DataManager, the dataset attributes are automatically carried over.

If you want to pass grid properties via the plot configuration, they need to be passed through to imshow_hexagonal(). This can happen via multiple arguments:

  • default_imshow_kwargs is passed to all imshow or imshow_hexagonal invocations.

  • imshow_hexagonal_extra_kwargs is passed only to imshow_hexagonal calls, updating the above.

  • imshow_kwargs within to_plot entries are updating the above for the specific entry.

If you want the plot to allow square grid representations, it’s best to use the imshow_hexagonal_extra_kwargs.

  # ... same as above ...
  grid_structure: hexagonal

  default_imshow_kwargs: {}       # passed to imshow *and* imshow_hexagonal

  imshow_hexagonal_extra_kwargs:  # passed *only* to imshow_hexagonal
      coordinate_mode: offset
      pointy_top: true
      offset_mode: even
      # ...

      # ...
      imshow_kwargs:              # passed to this specific imshow or imshow_hexagonal call
          # ...

.plot.abm: Visualize Agent-Based Models (ABM)#

The 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.

To select this plot function, the following configuration can be used as a starting point:

    - .creator.pyplot       # or some other creator
    - .plot.abm             # select the ABM plotting function

  select:                   # which data to select for plotting
      path: path/to/some/agent_data

  to_plot:                  # and which data to plot
      # specify which data variables to use for position and orientation
      x: x
      y: y
      orientation: orientation
      # ... more arguments here, see docstring

  # arguments on this level are shared among all entries in `to_plot`

Example output may look like this:

.plot.facet_grid extensions#


Brings faceting support to imshow_hexagonal():


.plot.graph: Plot graphs#

Invokes draw_graph().



.plot.snsplot: Plot using seaborn#

Invokes snsplot().