Updating Examples and Docs inline with the new API. (#2819)

* Added updated basic examples

* fix schelling agent_portrayal

* fixed marker import logic

* update boltzman wealth model

* update remaining basic examples

* remove unwanted parameter

* fix network agents error

* fix word repetetion

* added sys paths

* Revert "added sys paths"

* remove sys paths

* updated advanced examples

* remove unnecessary docstring

* fix alpha not working in matplotlib error

* added ordering functionality to altair

* Revert "added ordering functionality to altair"

* updated first tutorial

* updated second tutorial

* added 3rd visualization tutorial

* updated 3rd example

* added reviewed changes

* added property layer tutorial

* updated getting_started.md

* updated getting started last part

* empty commit

* added post_process test and updated example doc

* updated test

Author: Sahil-Chhoker

docs/getting_started.md

@@ -13,9 +13,11 @@ If you want to get a quick start on how to build agent based models with MESA, c
 - [AgentSet](tutorials/3_agentset): Learn how to more effectively manage agents with  Mesa's AgentSet.
 - [Basic Visualization](tutorials/4_visualization_basic): Learn how to build an interactive dashboard with Mesa's visualization module.
 - [Dynamic Agent Visualization](tutorials/5_visualization_dynamic_agents): Learn how to dynamically represent your agents in your interactive dashboard.
-- [Custom Visualization Components](tutorials/6_visualization_custom): Learn how to add custom visual components to your interactive dashboard.
-- [Parameter Sweeps](tutorials/7_batch_run): Learn how to conduct parameter sweeps on multiple processors with Mesa's BatchRunner.
-- [Comparing Scenarios](tutorials/8_comparing_scenarios): Think through how to analyze your parameter sweep results to find insight in your Mesa simulations.
+- [Visualization using SpaceRenderer](tutorials/6_visualization_rendering_with_space_renderer.ipynb): Learn how to use SpaceRenderer to its full extent to enhance your visualizations.
+- [Property Layer Visualization](tutorials/7_visualization_propertylayer_visualization.ipynb): Learn how to visualize property layers in mesa.
+- [Custom Visualization Components](tutorials/8_visualization_custom): Learn how to add custom visual components to your interactive dashboard.
+- [Parameter Sweeps](tutorials/9_batch_run): Learn how to conduct parameter sweeps on multiple processors with Mesa's BatchRunner.
+- [Comparing Scenarios](tutorials/10_comparing_scenarios): Think through how to analyze your parameter sweep results to find insight in your Mesa simulations.
 
 ## Examples
 Mesa ships with a collection of example models. These are classic ABMs, so if you are familiar with ABMs and want to get a quick sense of how MESA works, these examples are great place to start. You can find them [here](examples).
@@ -60,9 +62,11 @@ Collecting Data <tutorials/2_collecting_data>
 AgentSet <tutorials/3_agentset>
 Basic Visualization <tutorials/4_visualization_basic>
 Dynamic Agent Visualization <tutorials/5_visualization_dynamic_agents>
-Custom Visualization Components <tutorials/6_visualization_custom>
-Parameter Sweeps <tutorials/7_batch_run>
-Comparing Scenarios <tutorials/8_comparing_scenarios>
+Visualisation using SpaceRenderer <tutorials/6_visualization_rendering_with_space_renderer>
+Property Layer Visualization <tutorials/7_visualization_propertylayer_visualization>
+Custom Visualization Components <tutorials/8_visualization_custom>
+Parameter Sweeps <tutorials/9_batch_run>
+Comparing Scenarios <tutorials/10_comparing_scenarios>
 Best Practices <best-practices>
 
 

docs/tutorials/8_comparing_scenarios.ipynb renamed to docs/tutorials/10_comparing_scenarios.ipynb

@@ -60,7 +60,8 @@
     "\n",
     "import mesa\n",
     "from mesa.discrete_space import CellAgent, OrthogonalMooreGrid\n",
-    "from mesa.visualization import SolaraViz, make_plot_component, make_space_component"
+    "from mesa.visualization import SolaraViz, SpaceRenderer, make_plot_component\n",
+    "from mesa.visualization.components import AgentPortrayalStyle"
    ]
   },
   {
@@ -187,7 +188,11 @@
    "source": [
     "#### Grid Visualization\n",
     "\n",
-    "Mesa's grid visualizer works by looping over every cell in a grid, and generating a portrayal for every agent it finds. A portrayal is a dictionary (which can easily be turned into a JSON object) which tells Matplotlib the color and size of the scatterplot markers (each signifying an agent). The only thing we need to provide is a function which takes an agent, and returns a portrayal dictionary. Here's the simplest one: it'll draw each agent as a blue, filled circle, with a radius size of 50."
+    "Mesa’s grid visualizer works by iterating over each cell in the grid and generating a portrayal for every agent it finds. The portrayal function is called for each agent and returns an `AgentPortrayalStyle`—an object that defines how the agent is visually represented.\n",
+    "\n",
+    "All you need to provide is a function that takes an agent as input and returns an `AgentPortrayalStyle`.\n",
+    "\n",
+    "Here's the simplest example: it draws each agent as a filled orange circle with a radius of 50."
    ]
   },
   {
@@ -197,10 +202,7 @@
    "outputs": [],
    "source": [
     "def agent_portrayal(agent):\n",
-    "    return {\n",
-    "        \"color\": \"tab:blue\",\n",
-    "        \"size\": 50,\n",
-    "    }"
+    "    return AgentPortrayalStyle(color=\"tab:orange\", size=50)"
    ]
   },
   {
@@ -236,7 +238,7 @@
    "source": [
     "Next, we instantiate the visualization object which (by default) displays the grid containing the agents, and timeseries of values computed by the model's data collector. In this example, we specify the Gini coefficient.\n",
     "\n",
-    "There are 3 buttons:\n",
+    "There are 3 main buttons (we will discuss the play interval, render interval and use threads in lesson 6):\n",
     "- the step button, which advances the model by 1 step\n",
     "- the play button, which advances the model indefinitely until it is paused\n",
     "- the pause button, which pauses the model\n",
@@ -247,6 +249,26 @@
     "3. Press reset "
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "##### SpaceRenderer\n",
+    "This is the Python object used to visualize the grid, agents, and property layers associated with the space and the model and is passed to the `SolaraViz`\n",
+    "\n",
+    "We initialize the SpaceRenderer with a model instance (e.g., `money_model` in this case) and specify the rendering backend. The available backends are `matplotlib`(default) and `altair`.\n",
+    "\n",
+    "Both backends can be extended using the post_process function, which can either be passed directly to the render() method or set as a property of the renderer. (We’ll cover this in more detail later.)\n",
+    "\n",
+    "The method shown here is the quickest way to set up the visualization using the `render()` function.\n",
+    "\n",
+    "It renders the space, agents, and property layers—provided that the corresponding portrayal functions are supplied for both agents and property layers.\n",
+    "\n",
+    "> **Note:**\n",
+    "> \n",
+    "> You can make the small window full screen by clicking the button in the top-right corner of the title bar."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -256,12 +278,16 @@
     "# Create initial model instance\n",
     "money_model = MoneyModel(n=50, width=10, height=10)  # keyword arguments\n",
     "\n",
-    "SpaceGraph = make_space_component(agent_portrayal)\n",
+    "renderer = SpaceRenderer(model=money_model, backend=\"matplotlib\").render(\n",
+    "    agent_portrayal=agent_portrayal\n",
+    ")\n",
+    "\n",
     "GiniPlot = make_plot_component(\"Gini\")\n",
     "\n",
     "page = SolaraViz(\n",
     "    money_model,\n",
-    "    components=[SpaceGraph, GiniPlot],\n",
+    "    renderer,\n",
+    "    components=[GiniPlot],\n",
     "    model_params=model_params,\n",
     "    name=\"Boltzmann Wealth Model\",\n",
     ")\n",
@@ -291,7 +317,7 @@
  "metadata": {
   "anaconda-cloud": {},
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "env",
    "language": "python",
    "name": "python3"
   },
@@ -305,7 +331,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.5"
+   "version": "3.13.1"
   },
   "widgets": {
    "state": {},

docs/tutorials/4_visualization_basic.ipynb

@@ -14,7 +14,7 @@
    "metadata": {},
    "source": [
     "If you want to get straight to the tutorial checkout these environment providers:<br>\n",
-    "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/projectmesa/mesa/main?labpath=docs%2Ftutorials%2F4_visualization_basic.ipynb) (This can take 30 seconds to 5 minutes to load)\n",
+    "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/projectmesa/mesa/main?labpath=docs%2Ftutorials%2F5_visualization_dynamic_agents.ipynb) (This can take 30 seconds to 5 minutes to load)\n",
     "\n",
     "Due to conflict with Colab and Solara there are no colab links for this tutorial\n",
     "\n",
@@ -60,7 +60,8 @@
     "\n",
     "import mesa\n",
     "from mesa.discrete_space import CellAgent, OrthogonalMooreGrid\n",
-    "from mesa.visualization import SolaraViz, make_plot_component, make_space_component"
+    "from mesa.visualization import SolaraViz, SpaceRenderer, make_plot_component\n",
+    "from mesa.visualization.components import AgentPortrayalStyle"
    ]
   },
   {
@@ -189,9 +190,18 @@
     "\n",
     "In the first visualization, all we could see is the agents moving around -- but not how much money they had, or anything else of interest. In this tutorial let's change it so that agents are represented by the units of wealth they have. So those who are broke (wealth 0) are drawn in red, smaller. \n",
     "\n",
-    "As Mesa is open source, it is important to point out that currently, we can't direct the drawing order of the circles, so a broke agent may be overshadowed by a wealthy agent. If you have some ideas, please feel free to [contribute](https://github.com/projectmesa/mesa/blob/main/CONTRIBUTING.md). \n",
+    "Since Mesa is open source, if you have ideas to improve the visualization stack, feel free to [contribute](https://github.com/projectmesa/mesa/blob/main/CONTRIBUTING.md).\n",
+    "\n",
+    "When using the default drawer, an agent's shape can be customized in addition to its size and color.\n",
+    "\n",
+    "* For `matplotlib`, allowed shape values can be found [here](https://matplotlib.org/stable/api/markers_api.html).\n",
+    "* For `altair`, supported shapes include: `\"circle\"`, `\"square\"`, `\"cross\"`, `\"diamond\"`, `\"triangle-up\"`, `\"triangle-down\"`, `\"triangle-right\"`, and `\"triangle-left\"`.\n",
+    "\n",
+    "**Note:**\n",
+    "Always check which backend is being used before assigning shapes. If a shape name doesn't match what's supported by the selected backend, it may cause errors.\n",
+    "\n",
+    "In some cases, Mesa implicitly converts common shape names between Altair and Matplotlib (e.g., from Altair to Matplotlib), but this mapping is limited—and there's no support for conversion in the reverse direction (Matplotlib to Altair).\n",
     "\n",
-    "In addition to size and color, an agent's shape can also be customized when using the default drawer. The allowed values for shapes can be found [here](https://matplotlib.org/stable/api/markers_api.html).\n",
     "\n",
     "To do this, we go back to our `agent_portrayal` code and add some code to change the portrayal based on the agent properties and launch the server again."
    ]
@@ -203,12 +213,10 @@
    "outputs": [],
    "source": [
     "def agent_portrayal(agent):\n",
-    "    size = 10\n",
-    "    color = \"tab:red\"\n",
+    "    portrayal = AgentPortrayalStyle(size=50, color=\"tab:orange\")\n",
     "    if agent.wealth > 0:\n",
-    "        size = 50\n",
-    "        color = \"tab:blue\"\n",
-    "    return {\"size\": size, \"color\": color}"
+    "        portrayal.update((\"color\", \"tab:blue\"), (\"size\", 100))\n",
+    "    return portrayal"
    ]
   },
   {
@@ -244,7 +252,7 @@
    "source": [
     "Then just like last time we instantiate the visualization object which (by default) displays the grid containing the agents, and timeseries of values computed by the model's data collector. In this example, we specify the Gini coefficient.\n",
     "\n",
-    "There are 3 buttons:\n",
+    "There are 3 main buttons (we will discuss the play interval, render interval and use threads in lesson 6):\n",
     "- the step button, which advances the model by 1 step\n",
     "- the play button, which advances the model indefinitely until it is paused\n",
     "- the pause button, which pauses the model\n",
@@ -263,13 +271,16 @@
    "source": [
     "# Create initial model instance\n",
     "money_model = MoneyModel(n=50, width=10, height=10)\n",
+    "renderer = SpaceRenderer(model=money_model, backend=\"matplotlib\").render(\n",
+    "    agent_portrayal=agent_portrayal\n",
+    ")\n",
     "\n",
-    "SpaceGraph = make_space_component(agent_portrayal)\n",
     "GiniPlot = make_plot_component(\"Gini\")\n",
     "\n",
     "page = SolaraViz(\n",
     "    money_model,\n",
-    "    components=[SpaceGraph, GiniPlot],\n",
+    "    renderer,\n",
+    "    components=[GiniPlot],\n",
     "    model_params=model_params,\n",
     "    name=\"Boltzmann Wealth Model\",\n",
     ")\n",
@@ -292,7 +303,7 @@
    "source": [
     "## Next Steps\n",
     "\n",
-    "Check out the next [visualization tutorial custom components](https://mesa.readthedocs.io/latest/tutorials/6_visualization_custom.html) on how to further enhance your interactive dashboard."
+    "Check out the next tutorial [visualization rendering with `SpaceRenderer`](https://mesa.readthedocs.io/latest/tutorials/6_visualization_rendering_with_space_renderer.html) on how to further enhance your interactive dashboard."
    ]
   },
   {
@@ -308,7 +319,7 @@
  "metadata": {
   "anaconda-cloud": {},
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "env",
    "language": "python",
    "name": "python3"
   },
@@ -322,7 +333,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.5"
+   "version": "3.13.1"
   },
   "widgets": {
    "state": {},