Skip to content

Commit

Permalink
update tutorial for simplified namespace
Browse files Browse the repository at this point in the history
  • Loading branch information
@tpike3 @rht
tpike3 authored and rht committed Jun 13, 2022
1 parent 99a71c0 commit c210383
Show file tree
Hide file tree
Showing 18 changed files with 523 additions and 446 deletions.
100 changes: 64 additions & 36 deletions docs/tutorials/adv_tutorial.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@
"\n",
"So far, we've built a model, run it, and analyzed some output afterwards. However, one of the advantages of agent-based models is that we can often watch them run step by step, potentially spotting unexpected patterns, behaviors or bugs, or developing new intuitions, hypotheses, or insights. Other times, watching a model run can explain it to an unfamiliar audience better than static explanations. Like many ABM frameworks, Mesa allows you to create an interactive visualization of the model. In this section we'll walk through creating a visualization using built-in components, and (for advanced users) how to create a new visualization element.\n",
"\n",
"**Note for Jupyter users: Due to conflicts with the tornado server Mesa uses and Jupyter, the interactive browser of your model will load but likely not work. This will require you to use run the code from .py files. The Mesa development team is working to develop a** [Jupyter compatible interface](https://github.com/projectmesa/mesa/issues/1363).**\n",
"\n",
"First, a quick explanation of how Mesa's interactive visualization works. Visualization is done in a browser window, using JavaScript to draw the different things being visualized at each step of the model. To do this, Mesa launches a small web server, which runs the model, turns each step into a JSON object (essentially, structured plain text) and sends those steps to the browser.\n",
"\n",
"A visualization is built up of a few different modules: for example, a module for drawing agents on a grid, and another one for drawing a chart of some variable. Each module has a Python part, which runs on the server and turns a model state into JSON data; and a JavaScript side, which takes that JSON data and draws it in the browser window. Mesa comes with a few modules built in, and let you add your own as well."
Expand All @@ -31,14 +33,13 @@
},
{
"cell_type": "code",
"execution_count": 23,
"execution_count": null,
"metadata": {
"collapsed": true
"tags": []
},
"outputs": [],
"source": [
"from mesa.visualization.modules import CanvasGrid\n",
"from mesa.visualization.ModularVisualization import ModularServer\n",
"import mesa\n",
"\n",
"# If MoneyModel.py is where your code is:\n",
"# from MoneyModel import MoneyModel"
Expand All @@ -53,9 +54,9 @@
},
{
"cell_type": "code",
"execution_count": 24,
"execution_count": 1,
"metadata": {
"collapsed": true
"tags": []
},
"outputs": [],
"source": [
Expand All @@ -79,13 +80,45 @@
},
{
"cell_type": "code",
"execution_count": 25,
"execution_count": null,
"metadata": {
"collapsed": true
"tags": []
},
"outputs": [],
"source": [
"grid = CanvasGrid(agent_portrayal, 10, 10, 500, 500)"
"grid = mesa.visualization.CanvasGrid(agent_portrayal, 10, 10, 500, 500)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"\"\"\"\n",
"The full code should now look like:\n",
"\"\"\"\n",
"# from MoneyModel import *\n",
"import mesa\n",
"\n",
"\n",
"def agent_portrayal(agent):\n",
" portrayal = {\n",
" \"Shape\": \"circle\",\n",
" \"Filled\": \"true\",\n",
" \"Layer\": 0,\n",
" \"Color\": \"red\",\n",
" \"r\": 0.5,\n",
" }\n",
" return portrayal\n",
"\n",
"\n",
"grid = mesa.visualization.CanvasGrid(agent_portrayal, 10, 10, 500, 500)\n",
"server = mesa.visualization.ModularServer(\n",
" MoneyModel, [grid], \"Money Model\", {\"N\": 100, \"width\": 10, \"height\": 10}\n",
")\n",
"server.port = 8521 # The default\n",
"server.launch()"
]
},
{
Expand All @@ -102,19 +135,18 @@
"Once we create the server, we set the port for it to listen on (you can treat this as just a piece of the URL you'll open in the browser). Finally, when you're ready to run the visualization, use the server's `launch()` method.\n",
"\n",
"```python\n",
"server = ModularServer(MoneyModel, \n",
" [grid], \n",
" \"Money Model\", \n",
" 100, 10, 10)\n",
"server = ModularServer(MoneyModel,\n",
" [grid],\n",
" \"Money Model\",\n",
" {\"N\":100, \"width\":10, \"height\":10})\n",
"server.port = 8521 # The default\n",
"server.launch()\n",
"```\n",
"The full code should now look like:\n",
"\n",
"```python\n",
"from MoneyModel import *\n",
"from mesa.visualization.modules import CanvasGrid\n",
"from mesa.visualization.ModularVisualization import ModularServer\n",
"import mesa\n",
"\n",
"\n",
"def agent_portrayal(agent):\n",
Expand All @@ -125,11 +157,13 @@
" \"r\": 0.5}\n",
" return portrayal\n",
"\n",
"grid = CanvasGrid(agent_portrayal, 10, 10, 500, 500)\n",
"server = ModularServer(MoneyModel, \n",
" [grid], \n",
" \"Money Model\", \n",
" 100, 10, 10)\n",
"grid = mesa.visualization.CanvasGrid(agent_portrayal, 10, 10, 500, 500)\n",
"server = mesa.visualization.ModularServer(\n",
" MoneyModel, [grid], \"Money Model\", {\"N\": 100, \"width\": 10, \"height\": 10}\n",
")server = ModularServer(MoneyModel,\n",
" [grid],\n",
" \"Money Model\",\n",
" {\"N\":100, \"width\":10, \"height\":10})\n",
"server.port = 8521 # The default\n",
"server.launch()\n",
"```\n",
Expand All @@ -150,9 +184,7 @@
},
{
"cell_type": "markdown",
"metadata": {
"collapsed": true
},
"metadata": {},
"source": [
"#### Changing the agents\n",
"\n",
Expand Down Expand Up @@ -189,23 +221,19 @@
"\n",
"Next, let's add another element to the visualization: a chart, tracking the model's Gini Coefficient. This is another built-in element that Mesa provides.\n",
"\n",
"```python\n",
"from mesa.visualization.modules import ChartModule\n",
"```\n",
"\n",
"The basic chart pulls data from the model's DataCollector, and draws it as a line graph using the [Charts.js](http://www.chartjs.org/) JavaScript libraries. We instantiate a chart element with a list of series for the chart to track. Each series is defined in a dictionary, and has a `Label` (which must match the name of a model-level variable collected by the DataCollector) and a `Color` name. We can also give the chart the name of the DataCollector object in the model.\n",
"\n",
"Finally, we add the chart to the list of elements in the server. The elements are added to the visualization in the order they appear, so the chart will appear underneath the grid.\n",
"\n",
"```python\n",
"chart = ChartModule([{\"Label\": \"Gini\", \n",
"chart = mesa.visualization.ChartModule([{\"Label\": \"Gini\", \n",
" \"Color\": \"Black\"}],\n",
" data_collector_name='datacollector')\n",
"\n",
"server = ModularServer(MoneyModel, \n",
"server = mesa.visualization.ModularServer(MoneyModel, \n",
" [grid, chart], \n",
" \"Money Model\", \n",
" 100, 10, 10)\n",
" {\"N\":100, \"width\":10, \"height\":10})\n",
"```\n",
"\n",
"Launch the visualization and start a model run, and you'll see a line chart underneath the grid. Every step of the model, the line chart updates along with the grid. Reset the model, and the chart resets too.\n",
Expand Down Expand Up @@ -399,11 +427,11 @@
"Now, you can create your new HistogramModule and add it to the server:\n",
"\n",
"```python\n",
" histogram = HistogramModule(list(range(10)), 200, 500)\n",
" server = ModularServer(MoneyModel, \n",
" histogram = mesa.visualization.HistogramModule(list(range(10)), 200, 500)\n",
" server = mesa.visualization.ModularServer(MoneyModel, \n",
" [grid, histogram, chart], \n",
" \"Money Model\", \n",
" 100, 10, 10)\n",
" {\"N\":100, \"width\":10, \"height\":10})\n",
" server.launch()\n",
"```\n",
"\n",
Expand All @@ -426,7 +454,7 @@
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
Expand All @@ -440,9 +468,9 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.4"
"version": "3.9.6"
}
},
"nbformat": 4,
"nbformat_minor": 1
"nbformat_minor": 4
}
Loading

0 comments on commit c210383

Please sign in to comment.