link examples to readthedocs

projectmesa · Sep 19, 2022 · c7c5f27 · c7c5f27
1 parent 010f8f8
commit c7c5f27
Show file tree

Hide file tree

Showing 15 changed files with 194 additions and 18 deletions.
diff --git a/docs/examples/geo_schelling.md b/docs/examples/geo_schelling.md
@@ -0,0 +1,15 @@
+# GeoSchelling Model (Polygons)
+
+<iframe
+    width="560"
+    height="315"
+    src="https://www.youtube.com/embed/ZnBk_eSw0_M"
+    frameborder="0"
+    allowfullscreen>
+</iframe>
+
+```{include} ../../examples/geo_schelling/README.md
+---
+start-line: 3
+---
+```
diff --git a/docs/examples/geo_schelling_points.md b/docs/examples/geo_schelling_points.md
@@ -0,0 +1,15 @@
+# GeoSchelling Model (Points & Polygons)
+
+<iframe
+    width="560"
+    height="315"
+    src="https://www.youtube.com/embed/iLMU6jfmir8"
+    frameborder="0"
+    allowfullscreen>
+</iframe>
+
+```{include} ../../examples/geo_schelling_points/README.md
+---
+start-line: 3
+---
+```
diff --git a/docs/examples/geo_sir.md b/docs/examples/geo_sir.md
@@ -0,0 +1,15 @@
+# GeoSIR Epidemics Model
+
+<iframe
+    width="560"
+    height="315"
+    src="https://www.youtube.com/embed/oZShtptaIg4"
+    frameborder="0"
+    allowfullscreen>
+</iframe>
+
+```{include} ../../examples/geo_sir/README.md
+---
+start-line: 3
+---
+```
diff --git a/docs/examples/overview.md b/docs/examples/overview.md
@@ -0,0 +1,31 @@
+# Examples
+
+**Vector Data**
+
+- [GeoSchelling Model (Polygons)](geo_schelling.md)
+- [GeoSchelling Model (Points & Polygons)](geo_schelling_points.md)
+- [GeoSIR Epidemics Model](geo_sir.md)
+
+**Raster Data**
+
+- [Rainfall Model](rainfall.md)
+- [Urban Growth Model](urban_growth.md)
+
+**Raster and Vector Data Overlay**
+
+- [Population Model](population.md)
+
+```{toctree}
+---
+maxdepth: 2
+hidden: true
+caption: Examples
+---
+Overview <self>
+geo_schelling
+geo_schelling_points
+geo_sir
+rainfall
+urban_growth
+population
+```
diff --git a/docs/examples/population.md b/docs/examples/population.md
@@ -0,0 +1,15 @@
+# Population Model
+
+<iframe
+    width="560"
+    height="315"
+    src="https://www.youtube.com/embed/0k8tsYPVwQs"
+    frameborder="0"
+    allowfullscreen>
+</iframe>
+
+```{include} ../../examples/population/README.md
+---
+start-line: 3
+---
+```
diff --git a/docs/examples/rainfall.md b/docs/examples/rainfall.md
@@ -0,0 +1,15 @@
+# Rainfall Model
+
+<iframe
+    width="560"
+    height="315"
+    src="https://www.youtube.com/embed/R-IXN13YB1o"
+    frameborder="0"
+    allowfullscreen>
+</iframe>
+
+```{include} ../../examples/rainfall/README.md
+---
+start-line: 3
+---
+```
diff --git a/docs/examples/urban_growth.md b/docs/examples/urban_growth.md
@@ -0,0 +1,15 @@
+# Urban Growth Model
+
+<iframe
+    width="560"
+    height="315"
+    src="https://www.youtube.com/embed/UNtTJL5N83g"
+    frameborder="0"
+    allowfullscreen>
+</iframe>
+
+```{include} ../../examples/urban_growth/README.md
+---
+start-line: 3
+---
+```
diff --git a/docs/index.md b/docs/index.md
@@ -61,7 +61,9 @@ Don't forget to check out the [Contributors guide](https://github.com/projectmes
 maxdepth: 2
 hidden: true
 ---
-tutorials/intro_tutorial
+Introduction <self>
+Tutorial <tutorials/intro_tutorial>
+examples/overview
 API Documentation <apis/api_main>
 ```
 

diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,16 @@
+# Examples
+
+## Vector Data
+
+- [GeoSchelling Model (Polygons)](https://github.com/projectmesa/mesa-geo/tree/main/examples/geo_schelling)
+- [GeoSchelling Model (Points & Polygons)](https://github.com/projectmesa/mesa-geo/tree/main/examples/geo_schelling_points)
+- [GeoSIR Epidemics Model](https://github.com/projectmesa/mesa-geo/tree/main/examples/geo_sir)
+
+## Raster Data
+
+- [Rainfall Model](https://github.com/projectmesa/mesa-geo/tree/main/examples/rainfall)
+- [Urban Growth Model](https://github.com/projectmesa/mesa-geo/tree/main/examples/urban_growth)
+
+## Raster and Vector Data Overlay
+
+- [Population Model](https://github.com/projectmesa/mesa-geo/tree/main/examples/population)
diff --git a/examples/geo_schelling/README.md b/examples/geo_schelling/README.md
@@ -1,10 +1,18 @@
-# GeoSchelling Segregation Model
+# GeoSchelling Model (Polygons)
+
+![](../../docs/images/examples/geo_schelling.gif)
 
 ## Summary
 
 This is a geoversion of a simplified Schelling example. For the original implementation details please see the Mesa Schelling examples.
-Instead of a regular grid it uses European NUTS-2 regions as location for majority and minority opinions.
-For a region to be happy it only needs to have more similar neighbors than unsimilar ones.
+
+### GeoSpace
+
+Instead of an abstract grid space, we represent the space using NUTS-2 regions to create the GeoSpace in the model.
+
+### GeoAgent
+
+NUTS-2 regions are the GeoAgents. The neighbors of a polygon are considered those polygons that touch its border (i.e., edge neighbours). During the running of the model, a polygon queries the colors of the surrounding polygon and if the ratio falls below a certain threshold (e.g., 40% of the same color), the agent moves to an uncolored polygon.
 
 ## How to Run
 

diff --git a/examples/geo_schelling_points/README.md b/examples/geo_schelling_points/README.md
@@ -1,16 +1,18 @@
-# GeoSchelling Segregation Model with Point Agents
+# GeoSchelling Model (Points & Polygons)
+
+![](../../docs/images/examples/geo_schelling_points.gif)
 
 ## Summary
 
 This is a geoversion of a simplified Schelling example.
 
-**GeoSpace**
+### GeoSpace
 
-The NUTS-2 regions are considered as a shared definition of neighborhood among all agents, instead of a locally defined neighborhood such as Moore or von Neumann.
+The NUTS-2 regions are considered as a shared definition of neighborhood among all people agents, instead of a locally defined neighborhood such as Moore or von Neumann.
 
-**GeoAgent**
+### GeoAgent
 
-Each agent resides in a randomly assigned region, and checks the color ratio of its region against a pre-defined "happiness" threshold at every step. If the ratio falls below the threshold, the agent is found to be "unhappy", and randomly moves to another region. In this example, agents are represented as points, with locations randomly chosen within their regions.
+There are two types of GeoAgents: people and regions. Each person resides in a randomly assigned region, and checks the color ratio of its region against a pre-defined "happiness" threshold at every time step. If the ratio falls below a certain threshold (e.g., 40%), the agent is found to be "unhappy", and randomly moves to another region. People are represented as points, with locations randomly chosen within their regions. The color of a region depends on the color of the majority population it contains (i.e., point in polygon calculations).
 
 ## How to run
 

diff --git a/examples/geo_sir/README.md b/examples/geo_sir/README.md
@@ -1,5 +1,7 @@
 # GeoSIR Epidemics Model
 
+[![](https://img.youtube.com/vi/oZShtptaIg4/0.jpg)](https://www.youtube.com/watch?v=oZShtptaIg4)
+
 ## Summary
 
 This is a geoversion of a simple agent-based pandemic SIR model, as an example to show the capabilities of mesa-geo.

diff --git a/examples/population/README.md b/examples/population/README.md
@@ -1,7 +1,18 @@
-Population Model
-==============
+# Population Model
 
-An implementation of the [Uganda Example](https://github.com/abmgis/abmgis/tree/master/Chapter05-GIS/Models/UgandaExample) in Python, using [Mesa](https://github.com/projectmesa/mesa) and [Mesa-Geo](https://github.com/projectmesa/mesa-geo).
+[![](https://img.youtube.com/vi/0k8tsYPVwQs/0.jpg)](https://www.youtube.com/watch?v=0k8tsYPVwQs)
+
+## Summary
+
+This is an implementation of the [Uganda Example](https://github.com/abmgis/abmgis/tree/master/Chapter05-GIS/Models/UgandaExample) in Python, using [Mesa](https://github.com/projectmesa/mesa) and [Mesa-Geo](https://github.com/projectmesa/mesa-geo).
+
+### GeoSpace
+
+The GeoSpace consists of both a raster and a vector layer. The raster layer contains population data for each cell, and it is this data that is used for model initialisation, in the sense creating the agents. The vector layer shown in blue color represents a lake in Uganda. It overlays with the raster layer to mask out the cells that agents cannot move into.
+
+### GeoAgent
+
+The GeoAgents are people, created based on the population data. As this is a simple example model, the agents only move randomly to neighboring cells at each time step. To make the simulation more realistic and visually appealing, the agents in the same cell have a randomized position within the cell, so that they don’t stand on top of each other at exactly the same coordinate.
 
 ## How to run
 

diff --git a/examples/rainfall/README.md b/examples/rainfall/README.md
@@ -1,7 +1,18 @@
-Rainfall Model
-==============
+# Rainfall Model
 
-An implementation of the [Rainfall Model](https://github.com/abmgis/abmgis/tree/master/Chapter06-IntegratingABMandGIS/Models/Rainfall) in Python, using [Mesa](https://github.com/projectmesa/mesa) and [mesa-geo](https://github.com/projectmesa/mesa-geo).
+[![](https://img.youtube.com/vi/R-IXN13YB1o/0.jpg)](https://www.youtube.com/watch?v=R-IXN13YB1o)
+
+## Summary
+
+This is an implementation of the [Rainfall Model](https://github.com/abmgis/abmgis/tree/master/Chapter06-IntegratingABMandGIS/Models/Rainfall) in Python, using [Mesa](https://github.com/projectmesa/mesa) and [Mesa-Geo](https://github.com/projectmesa/mesa-geo). Inspired by the NetLogo [Grand Canyon model](http://ccl.northwestern.edu/netlogo/models/GrandCanyon), this is an example of how a digital elevation model (DEM) can be used to create an artificial world.
+
+### GeoSpace
+
+The GeoSpace contains a raster layer representing elevations. It is this elevation value that impacts how the raindrops move over the terrain. Apart from `elevation`, each cell of the raster layer also has a `water_level` attribute that is used to track the amount of water it contains. 
+
+### GeoAgent
+
+In this example, the raindrops are the GeoAgents. At each time step, raindrops are randomly created across the landscape to simulate rainfall. The raindrops flow from cells of higher elevation to lower elevation based on their eight surrounding cells (i.e., Moore neighbourhood). The raindrop also has its own height, which allows them to accumulate, gain height and flow if they are trapped at places such as potholes, pools, or depressions. When they reach the boundary of the GeoSpace, they are removed from the model as outflow.
 
 ## How to run
 

diff --git a/examples/urban_growth/README.md b/examples/urban_growth/README.md
@@ -1,7 +1,10 @@
-UrbanGrowth Model
-==============
+# Urban Growth Model
 
-An implementation of the [UrbanGrowth Model](https://github.com/abmgis/abmgis/tree/master/Chapter06-IntegratingABMandGIS/Models/UrbanGrowth) in Python, using [Mesa](https://github.com/projectmesa/mesa) and [mesa-geo](https://github.com/projectmesa/mesa-geo).
+[![](https://img.youtube.com/vi/UNtTJL5N83g/0.jpg)](https://www.youtube.com/watch?v=UNtTJL5N83g)
+
+## Summary
+
+This is an implementation of the [UrbanGrowth Model](https://github.com/abmgis/abmgis/tree/master/Chapter06-IntegratingABMandGIS/Models/UrbanGrowth) in Python, using [Mesa](https://github.com/projectmesa/mesa) and [Mesa-Geo](https://github.com/projectmesa/mesa-geo).
 
 ## How to run