diff --git a/docs/examples/geo_schelling.md b/docs/examples/geo_schelling.md new file mode 100644 index 00000000..eba950d3 --- /dev/null +++ b/docs/examples/geo_schelling.md @@ -0,0 +1,15 @@ +# GeoSchelling Model (Polygons) + + + +```{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 new file mode 100644 index 00000000..3751758f --- /dev/null +++ b/docs/examples/geo_schelling_points.md @@ -0,0 +1,15 @@ +# GeoSchelling Model (Points & Polygons) + + + +```{include} ../../examples/geo_schelling_points/README.md +--- +start-line: 3 +--- +``` diff --git a/docs/examples/geo_sir.md b/docs/examples/geo_sir.md new file mode 100644 index 00000000..7dfc8e8c --- /dev/null +++ b/docs/examples/geo_sir.md @@ -0,0 +1,15 @@ +# GeoSIR Epidemics Model + + + +```{include} ../../examples/geo_sir/README.md +--- +start-line: 3 +--- +``` diff --git a/docs/examples/overview.md b/docs/examples/overview.md new file mode 100644 index 00000000..d4ca9d3d --- /dev/null +++ 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 +geo_schelling +geo_schelling_points +geo_sir +rainfall +urban_growth +population +``` diff --git a/docs/examples/population.md b/docs/examples/population.md new file mode 100644 index 00000000..e9d0593e --- /dev/null +++ b/docs/examples/population.md @@ -0,0 +1,15 @@ +# Population Model + + + +```{include} ../../examples/population/README.md +--- +start-line: 3 +--- +``` diff --git a/docs/examples/rainfall.md b/docs/examples/rainfall.md new file mode 100644 index 00000000..6526ecf1 --- /dev/null +++ b/docs/examples/rainfall.md @@ -0,0 +1,15 @@ +# Rainfall Model + + + +```{include} ../../examples/rainfall/README.md +--- +start-line: 3 +--- +``` diff --git a/docs/examples/urban_growth.md b/docs/examples/urban_growth.md new file mode 100644 index 00000000..b026954c --- /dev/null +++ b/docs/examples/urban_growth.md @@ -0,0 +1,15 @@ +# Urban Growth Model + + + +```{include} ../../examples/urban_growth/README.md +--- +start-line: 3 +--- +``` diff --git a/docs/index.md b/docs/index.md index 19b6a5f9..41734481 100644 --- 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 +Tutorial +examples/overview API Documentation ``` diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000..6a8830ca --- /dev/null +++ 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 index 97e6b903..f9059f63 100644 --- 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 index 3999d4b3..2b873fa3 100644 --- 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 index 8ec679a7..0cd2ca73 100644 --- 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 index 4a53d1e3..d427e999 100644 --- 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 index 8fb207cd..59c2e517 100644 --- 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 index d1516965..eca178e3 100644 --- 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