Plot Functions#

utopya provides a number of additional plot functions over those already made available via dantro.

.plot.ca: Visualize Cellular Automata (CA)
- Square grids
- Hexagonal grids
.plot.abm: Visualize Agent-Based Models (ABM)
.plot.facet_grid extensions
.plot.facet_grid.imshow_hexagonal
.plot.graph: Plot graphs
.plot.snsplot: Plot using seaborn

`.plot.ca`: Visualize Cellular Automata (CA)#

The caplot() function, accessible via the .plot.ca 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:

my_ca_plot:
  based_on:
    - .creator.pyplot       # or some other creator
    - .plot.ca              # select the CA plotting function

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

  to_plot:                  # and which data to plot
    some_data:
      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.

Hint

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.

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

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

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

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

`.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:

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

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

  to_plot:                  # and which data to plot
    some_agents:
      # 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:

Corresponding plot configuration

The following configuration was used to generate the above example animation:

  based_on:
    - .creator.universe
    - .plot.abm
    - .animation.ffmpeg
    - .animation.high_dpi

  select:
    # Test data:
    #   xr.Datasets with data variables `x`, `y`, `orientation`,
    #   each with `(time, agent)` dimensions.
    prey: abm/circle_walk_noisy
    predator: abm/circle_walk_noisy2

  x: x
  y: y
  domain:
    mode: fixed  # can be: fixed, follow
    pad: 0.1
    aspect: 1

  orientation: orientation
  frames: time

  to_plot:
    prey:
      marker: fish
      size_scale: 0.0005  # fraction of the domain a single marker takes up

      # Let colors encode the fish's orientation and configure the colorbar
      hue: orientation
      cmap: twilight
      vmin: min
      vmax: max

      label: orientation $\theta$
      cbar_labels:
        0: 0
        1.570795: $π/2$
        3.14159: $π$
        4.712385: $3π/2$
        6.28318: $2π$

    predator:
      # Use a larger and more predator-like marker with a fixed color
      marker: fish2
      size_scale: 0.0010
      color: black

  # Draw a tail for the last 12 positions
  tail_length: 12
  tail_decay: 0.2
  tail_max_segment_length: 0.5  # don't draw segments longer than this
  tail_kwargs:
    color: black
    alpha: 0.6      # start value, is multiplied by (1 - tail_decay) each frame
    linewidth: 1.5
    capstyle: butt
    zorder: -42

  # Make the suptitle more subtle
  suptitle_fstr: "$t = {val:3d}$"
  suptitle_kwargs:
    x: 0.90
    ha: left
    fontfamily: monospace
    fontsize: medium

The used dummy data (circle_walk…) is an xarray.Dataset with data variables x, y, orientation, each one spanning dimensions time and agents. Data variables do not have coordinates in this case, but it would be possible to supply some.

Agents in periodic space

The tail_max_segment_length parameter is useful if you plan on drawing tails of agents that move in a periodic space. In such a case, agent positions may jump aprubtly when crossing a boundary. Ordinarily, this would lead to the tail segment going across the whole domain.

To avoid this, set the tail_max_segment_length parameter to half the domain size; this typically suffices to detect jumps in x- or y- position and leads to these segments not being drawn. (To be precise, the length refers not to that of the segment but to the differences in x- and/or y-position.)