Visualization#

For a detailed tutorial, please refer to our Visualization Tutorial.

Jupyter Visualization#

Mesa visualization module for creating interactive model visualizations.

This module provides components to create browser- and Jupyter notebook-based visualizations of Mesa models, allowing users to watch models run step-by-step and interact with model parameters.

Key features:

  • SolaraViz: Main component for creating visualizations, supporting grid displays and plots

  • ModelController: Handles model execution controls (step, play, pause, reset)

  • UserInputs: Generates UI elements for adjusting model parameters

The module uses Solara for rendering in Jupyter notebooks or as standalone web applications. It supports various types of visualizations including matplotlib plots, agent grids, and custom visualization components.

Usage:

  1. Define an agent_portrayal function to specify how agents should be displayed

  2. Set up model_params to define adjustable parameters

  3. Create a SolaraViz instance with your model, parameters, and desired measures

  4. Display the visualization in a Jupyter notebook or run as a Solara app

See the Visualization Tutorial and example models for more details.

split_model_params(model_params)[source]#

Split model parameters into user-adjustable and fixed parameters.

Parameters:

model_params – Dictionary of all model parameters

Returns:

(user_adjustable_params, fixed_params)

Return type:

tuple

check_param_is_fixed(param)[source]#

Check if a parameter is fixed (not user-adjustable).

Parameters:

param – Parameter to check

Returns:

True if parameter is fixed, False otherwise

Return type:

bool

make_initial_grid_layout(num_components)[source]#

Create an initial grid layout for visualization components.

Parameters:

num_components – Number of components to display

Returns:

Initial grid layout configuration

Return type:

list

User Parameters#

Solara visualization related helper classes.

class UserParam[source]#

Bases: object

UserParam.

maybe_raise_error(param_type, valid)[source]#
class Slider(label='', value=None, min=None, max=None, step=1, dtype=None)[source]#

Bases: UserParam

A number-based slider input with settable increment.

Example: slider_option = Slider(“My Slider”, value=123, min=10, max=200, step=0.1)

Parameters:

  • label – The displayed label in the UI

  • value – The initial value of the slider

  • min – The minimum possible value of the slider

  • max – The maximum possible value of the slider

  • step – The step between min and max for a range of possible values

  • dtype – either int or float

Initializes a slider.

Parameters:

  • label – The displayed label in the UI

  • value – The initial value of the slider

  • min – The minimum possible value of the slider

  • max – The maximum possible value of the slider

  • step – The step between min and max for a range of possible values

  • dtype – either int or float

get(attr)[source]#

Matplotlib-based visualizations#

Matplotlib based solara components for visualization MESA spaces and plots.

make_space_matplotlib(*args, **kwargs)[source]#
make_mpl_space_component(agent_portrayal: Callable | None = None, propertylayer_portrayal: dict | None = None, post_process: Callable | None = None, **space_drawing_kwargs) → SpaceMatplotlib[source]#

Create a Matplotlib-based space visualization component.

Parameters:

  • agent_portrayal – Function to portray agents.

  • propertylayer_portrayal – Dictionary of PropertyLayer portrayal specifications

  • post_process – a callable that will be called with the Axes instance. Allows for fine tuning plots (e.g., control ticks)

  • space_drawing_kwargs – additional keyword arguments to be passed on to the underlying space drawer function. See the functions for drawing the various spaces for further details.

agent_portrayal is called with an agent and should return a dict. Valid fields in this dict are “color”, “size”, “marker”, “zorder”, alpha, linewidths, and edgecolors. Other field are ignored and will result in a user warning.

Returns:

A function that creates a SpaceMatplotlib component

Return type:

function

make_plot_measure(*args, **kwargs)[source]#
make_mpl_plot_component(measure: str | dict[str, str] | list[str] | tuple[str], post_process: Callable | None = None, save_format='png')[source]#

Create a plotting function for a specified measure.

Parameters:

  • measure (str | dict[str, str] | list[str] | tuple[str]) – Measure(s) to plot.

  • post_process – a user-specified callable to do post-processing called with the Axes instance.

  • save_format – save format of figure in solara backend

Returns:

A function that creates a PlotMatplotlib component.

Return type:

function

Helper functions for drawing mesa spaces with matplotlib.

These functions are used by the provided matplotlib components, but can also be used to quickly visualize a space with matplotlib for example when creating a mp4 of a movie run or when needing a figure for a paper.

collect_agent_data(space: SingleGrid | MultiGrid | OrthogonalMooreGrid | OrthogonalVonNeumannGrid | HexSingleGrid | HexMultiGrid | HexGrid | NetworkGrid | Network | ContinuousSpace | VoronoiGrid, agent_portrayal: Callable, color='tab:blue', size=25, marker='o', zorder: int = 1)[source]#

Collect the plotting data for all agents in the space.

Parameters:

  • space – The space containing the Agents.

  • agent_portrayal – A callable that is called with the agent and returns a dict

  • color – default color

  • size – default size

  • marker – default marker

  • zorder – default zorder

agent_portrayal should return a dict, limited to size (size of marker), color (color of marker), zorder (z-order), marker (marker style), alpha, linewidths, and edgecolors

draw_space(space, agent_portrayal: Callable, propertylayer_portrayal: dict | None = None, ax: Axes | None = None, **space_drawing_kwargs)[source]#

Draw a Matplotlib-based visualization of the space.

Parameters:

  • space – the space of the mesa model

  • agent_portrayal – A callable that returns a dict specifying how to show the agent

  • propertylayer_portrayal – a dict specifying how to show propertylayer(s)

  • ax – the axes upon which to draw the plot

  • space_drawing_kwargs – any additional keyword arguments to be passed on to the underlying function for drawing the space.

Returns:

Returns the Axes object with the plot drawn onto it.

agent_portrayal is called with an agent and should return a dict. Valid fields in this dict are “color”, “size”, “marker”, “zorder”, alpha, linewidths, and edgecolors. Other field are ignored and will result in a user warning.

draw_property_layers(space, propertylayer_portrayal: dict[str, dict[str, Any]], ax: Axes)[source]#

Draw PropertyLayers on the given axes.

Parameters:

  • space (mesa.space._Grid) – The space containing the PropertyLayers.

  • propertylayer_portrayal (dict) – the key is the name of the layer, the value is a dict with fields specifying how the layer is to be portrayed

  • ax (matplotlib.axes.Axes) – The axes to draw on.

Notes

valid fields in in the inner dict of propertylayer_portrayal are “alpha”, “vmin”, “vmax”, “color” or “colormap”, and “colorbar” so you can do {“some_layer”:{“colormap”:’viridis’, ‘alpha’:.25, “colorbar”:False}}

draw_orthogonal_grid(space: SingleGrid | MultiGrid | OrthogonalMooreGrid | OrthogonalVonNeumannGrid, agent_portrayal: Callable, ax: Axes | None = None, draw_grid: bool = True, **kwargs)[source]#

Visualize a orthogonal grid.

Parameters:

  • space – the space to visualize

  • agent_portrayal – a callable that is called with the agent and returns a dict

  • ax – a Matplotlib Axes instance. If none is provided a new figure and ax will be created using plt.subplots

  • draw_grid – whether to draw the grid

  • kwargs – additional keyword arguments passed to ax.scatter

Returns:

Returns the Axes object with the plot drawn onto it.

agent_portrayal is called with an agent and should return a dict. Valid fields in this dict are “color”, “size”, “marker”, and “zorder”. Other field are ignored and will result in a user warning.

draw_hex_grid(space: HexSingleGrid | HexMultiGrid | HexGrid, agent_portrayal: Callable, ax: Axes | None = None, draw_grid: bool = True, **kwargs)[source]#

Visualize a hex grid.

Parameters:

  • space – the space to visualize

  • agent_portrayal – a callable that is called with the agent and returns a dict

  • ax – a Matplotlib Axes instance. If none is provided a new figure and ax will be created using plt.subplots

  • draw_grid – whether to draw the grid

  • kwargs – additional keyword arguments passed to ax.scatter

Returns:

Returns the Axes object with the plot drawn onto it.

agent_portrayal is called with an agent and should return a dict. Valid fields in this dict are “color”, “size”, “marker”, and “zorder”. Other field are ignored and will result in a user warning.

draw_network(space: ~mesa.space.NetworkGrid | ~mesa.experimental.cell_space.network.Network, agent_portrayal: ~collections.abc.Callable, ax: ~matplotlib.axes._axes.Axes | None = None, draw_grid: bool = True, layout_alg=<function spring_layout>, layout_kwargs=None, **kwargs)[source]#

Visualize a network space.

Parameters:

  • space – the space to visualize

  • agent_portrayal – a callable that is called with the agent and returns a dict

  • ax – a Matplotlib Axes instance. If none is provided a new figure and ax will be created using plt.subplots

  • draw_grid – whether to draw the grid

  • layout_alg – a networkx layout algorithm or other callable with the same behavior

  • layout_kwargs – a dictionary of keyword arguments for the layout algorithm

  • kwargs – additional keyword arguments passed to ax.scatter

Returns:

Returns the Axes object with the plot drawn onto it.

agent_portrayal is called with an agent and should return a dict. Valid fields in this dict are “color”, “size”, “marker”, and “zorder”. Other field are ignored and will result in a user warning.

draw_continuous_space(space: ContinuousSpace, agent_portrayal: Callable, ax: Axes | None = None, **kwargs)[source]#

Visualize a continuous space.

Parameters:

  • space – the space to visualize

  • agent_portrayal – a callable that is called with the agent and returns a dict

  • ax – a Matplotlib Axes instance. If none is provided a new figure and ax will be created using plt.subplots

  • kwargs – additional keyword arguments passed to ax.scatter

Returns:

Returns the Axes object with the plot drawn onto it.

agent_portrayal is called with an agent and should return a dict. Valid fields in this dict are “color”, “size”, “marker”, and “zorder”. Other field are ignored and will result in a user warning.

draw_voronoi_grid(space: VoronoiGrid, agent_portrayal: Callable, ax: Axes | None = None, draw_grid: bool = True, **kwargs)[source]#

Visualize a voronoi grid.

Parameters:

  • space – the space to visualize

  • agent_portrayal – a callable that is called with the agent and returns a dict

  • ax – a Matplotlib Axes instance. If none is provided a new figure and ax will be created using plt.subplots

  • draw_grid – whether to draw the grid or not

  • kwargs – additional keyword arguments passed to ax.scatter

Returns:

Returns the Axes object with the plot drawn onto it.

agent_portrayal is called with an agent and should return a dict. Valid fields in this dict are “color”, “size”, “marker”, and “zorder”. Other field are ignored and will result in a user warning.

Altair-based visualizations#

Altair based solara components for visualization mesa spaces.

make_space_altair(*args, **kwargs)[source]#
make_altair_space(agent_portrayal, propertylayer_portrayal, post_process, **space_drawing_kwargs)[source]#

Create an Altair-based space visualization component.

Parameters:

  • agent_portrayal – Function to portray agents.

  • propertylayer_portrayal – not yet implemented

  • post_process – not yet implemented

  • space_drawing_kwargs – not yet implemented

agent_portrayal is called with an agent and should return a dict. Valid fields in this dict are “color”, “size”, “marker”, and “zorder”. Other field are ignored and will result in a user warning.

Returns:

A function that creates a SpaceMatplotlib component

Return type:

function