Visualization#

class LeafletViz(style: dict[str, str | bool | int | float] | None = None, popupProperties: dict[str, str | bool | int | float] | None = None)[source]#

A dataclass defining the portrayal of a GeoAgent in Leaflet map.

The fields are defined to be consistent with GeoJSON options in Leaflet.js: https://leafletjs.com/reference.html#geojson

class MapModule(portrayal_method, tiles)[source]#

A MapModule for Leaflet maps that uses a user-defined portrayal method to generate a portrayal of a raster Cell or a GeoAgent.

For a raster Cell, the portrayal method should return a (r, g, b, a) tuple.

For a GeoAgent, the portrayal method should return a dictionary.

Create a new MapModule.

Parameters:

  • portrayal_method – A method that takes a GeoAgent (or a Cell) and returns a dictionary of options (or a (r, g, b, a) tuple) for Leaflet.js.

  • tiles –

    An optional tile layer to use. Can be a RasterWebTile or a xyzservices.TileProvider. Default is xyzservices.providers.OpenStreetMap.Mapnik.

    If the tile provider requires registration, you can pass the API key inside the options parameter of the RasterWebTile constructor.

    For example, to use the Mapbox raster tile provider, you can use:

    import mesa_geo as mg

mg.RasterWebTile(
    url="https://api.mapbox.com/v4/mapbox.satellite/{z}/{x}/{y}.png?access_token={access_token}",
    options={
        "access_token": "my-private-ACCESS_TOKEN",
        "attribution": '&copy; <a href="https://www.mapbox.com/about/maps/" target="_blank">Mapbox</a> &copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors <a href="https://www.mapbox.com/map-feedback/" target="_blank">Improve this map</a>',
    },
)

    Note that access_token can have different names depending on the provider, e.g., api_key or key. You can check the documentation of the provider for more details.

    xyzservices provides a list of providers requiring registration as well: https://xyzservices.readthedocs.io/en/stable/registration.html

    For example, you may use the following code to use the Mapbox provider:

    import xyzservices.providers as xyz

xyz.MapBox(id="<insert map_ID here>", accessToken="my-private-ACCESS_TOKEN")

make_geospace_component(agent_portrayal, view=None, tiles=xyzservices.providers.OpenStreetMap.Mapnik, **kwargs)[source]#

Create a Solara component that displays a Leaflet map for a model’s GeoSpace.

This function returns a factory callable that can be supplied to Mesa’s SolaraViz to embed an interactive Leaflet map showing the model’s GeoSpace. The map is rendered using ipyleaflet and will draw raster layers, vector layers, and agents with their portrayals, using a user-provided agent_portrayal function.

For a raster Cell, the portrayal method should return a (r, g, b, a) tuple.

For a GeoAgent, the portrayal method should return a dictionary.
Parameters:

  • agent_portrayal – A method that takes a GeoAgent (or a Cell) and returns a dictionary of options (or a (r, g, b, a) tuple) for Leaflet.js.

  • view – Initial map center as (latitude, longitude). If not provided, the map is centered from model.space.total_bounds.

  • tiles –

    An optional tile layer to use. Can be a RasterWebTile or a xyzservices.TileProvider. Default is xyzservices.providers.OpenStreetMap.Mapnik.

    If the tile provider requires registration, you can pass the API key inside the options parameter of the RasterWebTile constructor.

    For example, to use the Mapbox raster tile provider, you can use:

    import mesa_geo as mg

mg.RasterWebTile(
    url="https://api.mapbox.com/v4/mapbox.satellite/{z}/{x}/{y}.png?access_token={access_token}",
    options={
        "access_token": "my-private-ACCESS_TOKEN",
        "attribution": '&copy; <a href="https://www.mapbox.com/about/maps/" target="_blank">Mapbox</a> &copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors <a href="https://www.mapbox.com/map-feedback/" target="_blank">Improve this map</a>',
    },
)

    Note that access_token can have different names depending on the provider, e.g., api_key or key. You can check the documentation of the provider for more details.

    xyzservices provides a list of providers requiring registration as well: https://xyzservices.readthedocs.io/en/stable/registration.html

    For example, you may use the following code to use the Mapbox provider:

    import xyzservices.providers as xyz

xyz.MapBox(id="<insert map_ID here>", accessToken="my-private-ACCESS_TOKEN")

  • **kwargs –

    Extra keyword arguments forwarded to ipyleaflet.Map (e.g., zoom=, scroll_wheel_zoom=). The available options can be found at: https://ipyleaflet.readthedocs.io/en/latest/api_reference/index.html#ipyleaflet.leaflet.Map

Returns:

A factory callable to be passed as a SolaraViz component.

Return type:

Callable[[mesa.Model], solara.Element]

Warning

When using this component with SolaraViz, pass the list of components via the components= keyword argument (not as a positional argument). See the SolaraViz docs: https://mesa.readthedocs.io/latest/apis/visualization.html

Example

Define a custom portrayal for agents and add a map component to SolaraViz:

import mesa_geo as mg
from mesa.visualization import SolaraViz, make_plot_component
from mesa_geo.visualization import make_geospace_component

def agent_portrayal(agent):
    # Return Leaflet style options or RGBA tuple
    if isinstance(agent, mg.GeoAgent):
        return {"radius": 4, "color": "blue"}
    elif isinstance(agent, mg.Cell):
        return (255, 0, 0, 1)  # Red color for raster cells

page = SolaraViz(
    model,
    name="Geo Model",
    model_params=model_params,
    components=[
        make_geospace_component(agent_portrayal),
        make_plot_component(["happy", "unhappy"]),
    ],
)