feat: Add tooltip to Altair agent portrayal (#2795)

This feature adds a `tooltip` attribute to `AgentPortrayalStyle`,
enabling agent-specific information to be displayed on hover in
Altair-based visualizations.

This commit addresses review feedback by:
- Adding documentation to clarify the feature is Altair-only.
- Raising a ValueError if tooltips are used with the Matplotlib backend.
- Applying consistency, typo, and formatting fixes suggested by reviewers.

Author: pre-commit-ci[bot]

mesa/examples/basic/boltzmann_wealth_model/app.py

@@ -38,6 +38,23 @@ def agent_portrayal(agent):
 }
 
 
+def post_process(chart):
+    """Post-process the Altair chart to add a colorbar legend."""
+    chart = chart.encode(
+        color=alt.Color(
+            "original_color:Q",
+            scale=alt.Scale(scheme="viridis", domain=[0, 10]),
+            legend=alt.Legend(
+                title="Wealth",
+                orient="right",
+                type="gradient",
+                gradientLength=200,
+            ),
+        ),
+    )
+    return chart
+
+
 model = BoltzmannWealth(50, 10, 10)
 
 # The SpaceRenderer is responsible for drawing the model's space and agents.
@@ -47,13 +64,11 @@ def agent_portrayal(agent):
 renderer = SpaceRenderer(model, backend="altair")
 # Can customize the grid appearance.
 renderer.draw_structure(grid_color="black", grid_dash=[6, 2], grid_opacity=0.3)
-renderer.draw_agents(
-    agent_portrayal=agent_portrayal,
-    cmap="viridis",
-    vmin=0,
-    vmax=10,
-    legend_title="Wealth",
-)
+renderer.draw_agents(agent_portrayal=agent_portrayal)
+# The post_process function is used to modify the Altair chart after it has been created.
+# It can be used to add legends, colorbars, or other visual elements.
+renderer.post_process = post_process
+
 
 # Creates a line plot component from the model's "Gini" datacollector.
 GiniPlot = make_plot_component("Gini")
@@ -67,4 +82,4 @@ def agent_portrayal(agent):
     model_params=model_params,
     name="Boltzmann Wealth Model",
 )
-page  # noqa
+page  # noqa

mesa/visualization/backends/altair_backend.py

@@ -1,3 +1,9 @@
+"""Altair-based renderer for Mesa spaces.
+
+This module provides an Altair-based renderer for visualizing Mesa model spaces,
+agents, and property layers with interactive charting capabilities.
+"""
+
 import warnings
 from collections.abc import Callable
 from dataclasses import fields
@@ -201,12 +207,21 @@ def collect_agent_data(
 
         return final_data
 
-
-
     def draw_agents(
         self, arguments, chart_width: int = 450, chart_height: int = 350, **kwargs
     ):
-        """Draw agents using Altair backend."""
+        """Draw agents using Altair backend.
+
+        Args:
+            arguments: Dictionary containing agent data arrays.
+            chart_width: Width of the chart.
+            chart_height: Height of the chart.
+            **kwargs: Additional keyword arguments for customization.
+            Checkout respective `SpaceDrawer` class on details how to pass **kwargs.
+
+        Returns:
+            alt.Chart: The Altair chart representing the agents, or None if no agents.
+        """
         if arguments["loc"].size == 0:
             return None
 
@@ -219,7 +234,8 @@ def draw_agents(
                 "size": arguments["size"][i],
                 "shape": arguments["shape"][i],
                 "opacity": arguments["opacity"][i],
-                "strokeWidth": arguments["strokeWidth"][i] / 10, # Scale for continuous domain
+                "strokeWidth": arguments["strokeWidth"][i]
+                / 10,  # Scale for continuous domain
                 "original_color": arguments["color"][i],
             }
             # Add tooltip data if available
@@ -230,7 +246,11 @@ def draw_agents(
             # Determine fill and stroke colors
             if arguments["filled"][i]:
                 record["viz_fill_color"] = arguments["color"][i]
-                record["viz_stroke_color"] = arguments["stroke"][i] if isinstance(arguments["stroke"][i], str) else None
+                record["viz_stroke_color"] = (
+                    arguments["stroke"][i]
+                    if isinstance(arguments["stroke"][i], str)
+                    else None
+                )
             else:
                 record["viz_fill_color"] = None
                 record["viz_stroke_color"] = arguments["color"][i]
@@ -240,52 +260,32 @@ def draw_agents(
         df = pd.DataFrame(records)
 
         # Ensure all columns that should be numeric are, handling potential Nones
-        numeric_cols = ['x', 'y', 'size', 'opacity', 'strokeWidth', 'original_color']
+        numeric_cols = ["x", "y", "size", "opacity", "strokeWidth", "original_color"]
         for col in numeric_cols:
             if col in df.columns:
-                df[col] = pd.to_numeric(df[col], errors='coerce')
-
+                df[col] = pd.to_numeric(df[col], errors="coerce")
 
         # Get tooltip keys from the first valid record
         tooltip_list = ["x", "y"]
-        # This is the corrected line:
         if any(t is not None for t in arguments["tooltip"]):
-             first_valid_tooltip = next((t for t in arguments["tooltip"] if t), None)
-             if first_valid_tooltip:
-                 tooltip_list.extend(first_valid_tooltip.keys())
+            first_valid_tooltip = next(
+                (t for t in arguments["tooltip"] if t is not None), None
+            )
+            if first_valid_tooltip is not None:
+                tooltip_list.extend(first_valid_tooltip.keys())
 
         # Extract additional parameters from kwargs
         title = kwargs.pop("title", "")
         xlabel = kwargs.pop("xlabel", "")
         ylabel = kwargs.pop("ylabel", "")
-        legend_title = kwargs.pop("legend_title", "Color")
-
-        # Handle custom colormapping
-        cmap = kwargs.pop("cmap", "viridis")
-        vmin = kwargs.pop("vmin", None)
-        vmax = kwargs.pop("vmax", None)
+        # FIXME: Add more parameters to kwargs
 
         color_is_numeric = pd.api.types.is_numeric_dtype(df["original_color"])
-        if color_is_numeric:
-            color_min = vmin if vmin is not None else df["original_color"].min()
-            color_max = vmax if vmax is not None else df["original_color"].max()
-
-            fill_encoding = alt.Fill(
-                "original_color:Q",
-                scale=alt.Scale(scheme=cmap, domain=[color_min, color_max]),
-                legend=alt.Legend(
-                    title=legend_title,
-                    orient="right",
-                    type="gradient",
-                    gradientLength=200,
-                ),
-            )
-        else:
-            fill_encoding = alt.Fill(
-                "viz_fill_color:N",
-                scale=None,
-                title="Color",
-            )
+        fill_encoding = (
+            alt.Fill("original_color:Q")
+            if color_is_numeric
+            else alt.Fill("viz_fill_color:N", scale=None, title="Color")
+        )
 
         # Determine space dimensions
         xmin, xmax, ymin, ymax = self.space_drawer.get_viz_limits()
@@ -316,10 +316,16 @@ def draw_agents(
                     ),
                     title="Shape",
                 ),
-                opacity=alt.Opacity("opacity:Q", title="Opacity", scale=alt.Scale(domain=[0, 1], range=[0, 1])),
+                opacity=alt.Opacity(
+                    "opacity:Q",
+                    title="Opacity",
+                    scale=alt.Scale(domain=[0, 1], range=[0, 1]),
+                ),
                 fill=fill_encoding,
                 stroke=alt.Stroke("viz_stroke_color:N", scale=None),
-                strokeWidth=alt.StrokeWidth("strokeWidth:Q", scale=alt.Scale(domain=[0, 1])),
+                strokeWidth=alt.StrokeWidth(
+                    "strokeWidth:Q", scale=alt.Scale(domain=[0, 1])
+                ),
                 tooltip=tooltip_list,
             )
             .properties(title=title, width=chart_width, height=chart_height)
@@ -431,4 +437,4 @@ def draw_propertylayer(
                 main_charts.append(current_chart)
 
         base = alt.layer(*main_charts).resolve_scale(color="independent")
-        return base
+        return base

mesa/visualization/backends/matplotlib_backend.py

@@ -27,7 +27,6 @@
 OrthogonalGrid = SingleGrid | MultiGrid | OrthogonalMooreGrid | OrthogonalVonNeumannGrid
 HexGrid = HexSingleGrid | HexMultiGrid | mesa.discrete_space.HexGrid
 
-
 CORRECTION_FACTOR_MARKER_ZOOM = 0.01
 
 
@@ -141,6 +140,10 @@ def collect_agent_data(self, space, agent_portrayal, default_size=None):
                     )
             else:
                 aps = portray_input
+                if aps.tooltip is not None:
+                    raise ValueError(
+                        "The 'tooltip' attribute in AgentPortrayalStyle is only supported by the Altair backend."
+                    )
                 # Set defaults if not provided
                 if aps.x is None and aps.y is None:
                     aps.x, aps.y = self._get_agent_pos(agent, space)

mesa/visualization/components/portrayal_components.py

@@ -56,6 +56,7 @@ class AgentPortrayalStyle:
     edgecolors: str | tuple | None = None
     linewidths: float | int | None = 1.0
     tooltip: dict | None = None
+    """A dictionary of data to display on hover. Note: This feature is only available with the Altair backend."""
 
     def update(self, *updates_fields: tuple[str, Any]):
         """Updates attributes from variable (field_name, new_value) tuple arguments.
@@ -92,7 +93,7 @@ class PropertyLayerStyle:
     (vmin, vmax), transparency (alpha) and colorbar visibility.
 
     Note: vmin and vmax are the lower and upper bounds for the colorbar and the data is
-    normalized between these values for color/colorbar rendering. If they are not
+    normalized between these values for color/colormap rendering. If they are not
     declared the values are automatically determined from the data range.
 
     Note: You can specify either a 'colormap' (for varying data) or a single
@@ -118,4 +119,4 @@ def __post_init__(self):
         if self.color is not None and self.colormap is not None:
             raise ValueError("Specify either 'color' or 'colormap', not both.")
         if self.color is None and self.colormap is None:
-            raise ValueError("Specify one of 'color' or 'colormap'")
+            raise ValueError("Specify one of 'color' or 'colormap'")

tests/test_backends.py

@@ -248,6 +248,7 @@ def test_altair_backend_draw_agents():
         "color": np.array(["red", "blue"]),
         "filled": np.array([True, True]),
         "stroke": np.array(["black", "black"]),
+        "tooltip": np.array([None, None]),
     }
     ab.space_drawer.get_viz_limits = MagicMock(return_value=(0, 10, 0, 10))
     assert ab.draw_agents(arguments) is not None