api reorganization (#2447)

Author: quaquel

docs/apis/visualization.md

@@ -21,19 +21,26 @@ For a detailed tutorial, please refer to our [Visualization Tutorial](../tutoria
 ```
 
 
-## Matplotlib-based components
+## Matplotlib-based visualizations
 
 ```{eval-rst}
-.. automodule:: mesa.visualization.components.matplotlib
+.. automodule:: mesa.visualization.components.matplotlib_components
    :members:
    :undoc-members:
    :show-inheritance:
 ```
 
-## Altair-based components
+```{eval-rst}
+.. automodule:: mesa.visualization.mpl_space_drawing
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Altair-based visualizations
 
 ```{eval-rst}
-.. automodule:: mesa.visualization.components.altair
+.. automodule:: mesa.visualization.components.altair_components
    :members:
    :undoc-members:
    :show-inheritance:

mesa/examples/advanced/pd_grid/app.py

@@ -3,7 +3,11 @@
 """
 
 from mesa.examples.advanced.pd_grid.model import PdGrid
-from mesa.visualization import SolaraViz, make_plot_component, make_space_component
+from mesa.visualization import (
+    SolaraViz,
+    make_plot_component,
+    make_space_component,
+)
 from mesa.visualization.UserParam import Slider
 
 

mesa/examples/basic/boid_flockers/app.py

@@ -51,7 +51,7 @@ def boid_draw(agent):
 
 page = SolaraViz(
     model,
-    [make_space_component(agent_portrayal=boid_draw)],
+    [make_space_component(agent_portrayal=boid_draw, backend="matplotlib")],
     model_params=model_params,
     name="Boid Flocking Model",
 )

mesa/examples/basic/boltzmann_wealth_model/app.py

@@ -1,5 +1,9 @@
 from mesa.examples.basic.boltzmann_wealth_model.model import BoltzmannWealthModel
-from mesa.visualization import SolaraViz, make_plot_component, make_space_component
+from mesa.visualization import (
+    SolaraViz,
+    make_plot_component,
+    make_space_component,
+)
 
 
 def agent_portrayal(agent):

mesa/visualization/__init__.py

@@ -1,7 +1,11 @@
 """Solara based visualization for Mesa models."""
 
-from .components.altair import make_space_altair
-from .components.matplotlib import make_plot_component, make_space_component
+from mesa.visualization.mpl_space_drawing import (
+    draw_space,
+)
+
+from .components import make_plot_component, make_space_component
+from .components.altair_components import make_space_altair
 from .solara_viz import JupyterViz, SolaraViz
 from .UserParam import Slider
 
@@ -10,6 +14,7 @@
     "SolaraViz",
     "Slider",
     "make_space_altair",
-    "make_space_component",
+    "draw_space",
     "make_plot_component",
+    "make_space_component",
 ]

mesa/visualization/components/__init__.py

@@ -0,0 +1,83 @@
+"""custom solara components."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from .altair_components import SpaceAltair, make_altair_space
+from .matplotlib_components import (
+    SpaceMatplotlib,
+    make_mpl_plot_component,
+    make_mpl_space_component,
+)
+
+
+def make_space_component(
+    agent_portrayal: Callable | None = None,
+    propertylayer_portrayal: dict | None = None,
+    post_process: Callable | None = None,
+    backend: str = "matplotlib",
+    **space_drawing_kwargs,
+) -> SpaceMatplotlib | SpaceAltair:
+    """Create a Matplotlib-based space visualization component.
+
+    Args:
+        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)
+        backend: the backend to use {"matplotlib", "altair"}
+        space_drawing_kwargs : additional keyword arguments to be passed on to the underlying backend specific space drawer function. See
+                               the functions for drawing the various spaces for the appropriate backend further details.
+
+
+    Returns:
+        function: A function that creates a space component
+    """
+    if backend == "matplotlib":
+        return make_mpl_space_component(
+            agent_portrayal,
+            propertylayer_portrayal,
+            post_process,
+            **space_drawing_kwargs,
+        )
+    elif backend == "altair":
+        return make_altair_space(
+            agent_portrayal,
+            propertylayer_portrayal,
+            post_process,
+            **space_drawing_kwargs,
+        )
+    else:
+        raise ValueError(
+            f"unknown backend {backend}, must be one of matplotlib, altair"
+        )
+
+
+def make_plot_component(
+    measure: str | dict[str, str] | list[str] | tuple[str],
+    post_process: Callable | None = None,
+    backend: str = "matplotlib",
+    **plot_drawing_kwargs,
+):
+    """Create a plotting function for a specified measure using the specified backend.
+
+    Args:
+        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.
+        backend: the backend to use {"matplotlib", "altair"}
+        plot_drawing_kwargs: additional keyword arguments to pass onto the backend specific function for making a plotting component
+
+    Notes:
+        altair plotting backend is not yet implemented and planned for mesa 3.1.
+
+    Returns:
+        function: A function that creates a plot component
+    """
+    if backend == "matplotlib":
+        return make_mpl_plot_component(measure, post_process, **plot_drawing_kwargs)
+    elif backend == "altair":
+        raise NotImplementedError("altair line plots are not yet implemented")
+    else:
+        raise ValueError(
+            f"unknown backend {backend}, must be one of matplotlib, altair"
+        )

mesa/visualization/components/altair.py renamed to mesa/visualization/components/altair_components.py

@@ -1,6 +1,7 @@
 """Altair based solara components for visualization mesa spaces."""
 
 import contextlib
+import warnings
 
 import solara
 
@@ -12,7 +13,33 @@
 from mesa.visualization.utils import update_counter
 
 
-def make_space_altair(agent_portrayal=None):  # noqa: D103
+def make_space_altair(*args, **kwargs):  # noqa: D103
+    warnings.warn(
+        "make_space_altair has been renamed to make_altair_space",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return make_altair_space(*args, **kwargs)
+
+
+def make_altair_space(
+    agent_portrayal, propertylayer_portrayal, post_process, **space_drawing_kwargs
+):
+    """Create an Altair-based space visualization component.
+
+    Args:
+        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:
+        function: A function that creates a SpaceMatplotlib component
+    """
     if agent_portrayal is None:
 
         def agent_portrayal(a):
@@ -25,7 +52,12 @@ def MakeSpaceAltair(model):
 
 
 @solara.component
-def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):  # noqa: D103
+def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):
+    """Create an Altair-based space visualization component.
+
+    Returns:
+        a solara FigureAltair instance
+    """
     update_counter.get()
     space = getattr(model, "grid", None)
     if space is None: