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

@@ -1,5 +1,3 @@
-import altair as alt
-
 from mesa.examples.basic.boltzmann_wealth_model.model import BoltzmannWealth
 from mesa.mesa_logging import INFO, log_to_stderr
 from mesa.visualization import (
@@ -67,4 +65,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,8 +207,6 @@ def collect_agent_data(
 
         return final_data
 
-
-
     def draw_agents(
         self, arguments, chart_width: int = 450, chart_height: int = 350, **kwargs
     ):
@@ -219,7 +223,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 +235,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,19 +249,19 @@ 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", "")
@@ -316,10 +325,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 +446,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 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