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

Author: DipayanDasgupta

mesa/examples/basic/boltzmann_wealth_model/app.py

@@ -14,8 +14,9 @@
 
 def agent_portrayal(agent):
     return AgentPortrayalStyle(
-        color=agent.wealth
-    )  # we are using a colormap to translate wealth to color
+        color=agent.wealth,
+        tooltip={"Agent ID": agent.unique_id, "Wealth": agent.wealth},
+    )
 
 
 model_params = {
@@ -37,23 +38,6 @@ def agent_portrayal(agent):
 }
 
 
-def post_process(chart):
-    """Post-process the Altair chart to add a colorbar legend."""
-    chart = chart.encode(
-        color=alt.Color(
-            "color:N",
-            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.
@@ -63,11 +47,13 @@ def post_process(chart):
 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)
-
-# 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
+renderer.draw_agents(
+    agent_portrayal=agent_portrayal,
+    cmap="viridis",
+    vmin=0,
+    vmax=10,
+    legend_title="Wealth",
+)
 
 # Creates a line plot component from the model's "Gini" datacollector.
 GiniPlot = make_plot_component("Gini")
@@ -81,4 +67,4 @@ def post_process(chart):
     model_params=model_params,
     name="Boltzmann Wealth Model",
 )
-page  # noqa
+page  # noqa

mesa/visualization/backends/altair_backend.py

@@ -1,4 +1,3 @@
-# noqa: D100
 import warnings
 from collections.abc import Callable
 from dataclasses import fields
@@ -75,6 +74,7 @@ def collect_agent_data(
             "stroke": [],  # Stroke color
             "strokeWidth": [],
             "filled": [],
+            "tooltip": [],
         }
 
         # Import here to avoid circular import issues
@@ -129,6 +129,7 @@ def collect_agent_data(
                     linewidths=dict_data.pop(
                         "linewidths", style_fields.get("linewidths")
                     ),
+                    tooltip=dict_data.pop("tooltip", None),
                 )
                 if dict_data:
                     ignored_keys = list(dict_data.keys())
@@ -184,6 +185,7 @@ def collect_agent_data(
             # FIXME: Make filled user-controllable
             filled_value = True
             arguments["filled"].append(filled_value)
+            arguments["tooltip"].append(aps.tooltip)
 
         final_data = {}
         for k, v in arguments.items():
@@ -199,87 +201,84 @@ 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.
-
-        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.
-        """
+        """Draw agents using Altair backend."""
         if arguments["loc"].size == 0:
             return None
 
-        # To get a continuous scale for color the domain should be between [0, 1]
-        # that's why changing the the domain of strokeWidth beforehand.
-        stroke_width = [data / 10 for data in arguments["strokeWidth"]]
-
-        # Agent data preparation
-        df_data = {
-            "x": arguments["loc"][:, 0],
-            "y": arguments["loc"][:, 1],
-            "size": arguments["size"],
-            "shape": arguments["shape"],
-            "opacity": arguments["opacity"],
-            "strokeWidth": stroke_width,
-            "original_color": arguments["color"],
-            "is_filled": arguments["filled"],
-            "original_stroke": arguments["stroke"],
-        }
-        df = pd.DataFrame(df_data)
-
-        # To ensure distinct shapes according to agent portrayal
-        unique_shape_names_in_data = df["shape"].unique().tolist()
-
-        fill_colors = []
-        stroke_colors = []
-        for i in range(len(df)):
-            filled = df["is_filled"][i]
-            main_color = df["original_color"][i]
-            stroke_spec = (
-                df["original_stroke"][i]
-                if isinstance(df["original_stroke"][i], str)
-                else None
-            )
-            if filled:
-                fill_colors.append(main_color)
-                stroke_colors.append(stroke_spec)
+        # Prepare a list of dictionaries, which is a robust way to create a DataFrame
+        records = []
+        for i in range(len(arguments["loc"])):
+            record = {
+                "x": arguments["loc"][i][0],
+                "y": arguments["loc"][i][1],
+                "size": arguments["size"][i],
+                "shape": arguments["shape"][i],
+                "opacity": arguments["opacity"][i],
+                "strokeWidth": arguments["strokeWidth"][i] / 10, # Scale for continuous domain
+                "original_color": arguments["color"][i],
+            }
+            # Add tooltip data if available
+            tooltip = arguments["tooltip"][i]
+            if tooltip:
+                record.update(tooltip)
+
+            # 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
             else:
-                fill_colors.append(None)
-                stroke_colors.append(main_color)
-        df["viz_fill_color"] = fill_colors
-        df["viz_stroke_color"] = stroke_colors
+                record["viz_fill_color"] = None
+                record["viz_stroke_color"] = arguments["color"][i]
+
+            records.append(record)
+
+        df = pd.DataFrame(records)
+
+        # Ensure all columns that should be numeric are, handling potential Nones
+        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')
+
+
+        # 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())
 
         # Extract additional parameters from kwargs
-        # FIXME: Add more parameters to kwargs
         title = kwargs.pop("title", "")
         xlabel = kwargs.pop("xlabel", "")
         ylabel = kwargs.pop("ylabel", "")
-
-        # Tooltip list for interactivity
-        # FIXME: Add more fields to tooltip (preferably from agent_portrayal)
-        tooltip_list = ["x", "y"]
+        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)
 
-        color_is_numeric = np.issubdtype(df["original_color"].dtype, np.number)
+        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(
@@ -290,6 +289,7 @@ def draw_agents(
 
         # Determine space dimensions
         xmin, xmax, ymin, ymax = self.space_drawer.get_viz_limits()
+        unique_shape_names_in_data = df["shape"].dropna().unique().tolist()
 
         chart = (
             alt.Chart(df)
@@ -316,16 +316,10 @@ 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)
@@ -437,4 +431,4 @@ def draw_propertylayer(
                 main_charts.append(current_chart)
 
         base = alt.layer(*main_charts).resolve_scale(color="independent")
-        return base
+        return base

mesa/visualization/components/portrayal_components.py

@@ -55,6 +55,7 @@ class AgentPortrayalStyle:
     alpha: float | None = 1.0
     edgecolors: str | tuple | None = None
     linewidths: float | int | None = 1.0
+    tooltip: dict | None = None
 
     def update(self, *updates_fields: tuple[str, Any]):
         """Updates attributes from variable (field_name, new_value) tuple arguments.
@@ -91,7 +92,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/colormap rendering. If they are not
+    normalized between these values for color/colorbar 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
@@ -117,4 +118,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'")