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..7984a49b --- /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 new file mode 100644 index 00000000..d427e999 --- /dev/null +++ b/examples/population/README.md @@ -0,0 +1,25 @@ +# Population Model + +[![](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 + +To run the model interactively, run `mesa runserver` in this directory. e.g. + +```bash +mesa runserver +``` + +Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press `Start`. diff --git a/examples/uganda/data/clip.zip b/examples/population/data/clip.zip similarity index 100% rename from examples/uganda/data/clip.zip rename to examples/population/data/clip.zip diff --git a/examples/uganda/data/lake.zip b/examples/population/data/lake.zip similarity index 100% rename from examples/uganda/data/lake.zip rename to examples/population/data/lake.zip diff --git a/examples/uganda/data/popu.asc.gz b/examples/population/data/popu.asc.gz similarity index 100% rename from examples/uganda/data/popu.asc.gz rename to examples/population/data/popu.asc.gz diff --git a/examples/uganda/uganda/model.py b/examples/population/population/model.py similarity index 99% rename from examples/uganda/uganda/model.py rename to examples/population/population/model.py index 6d4ad8cf..1d265736 100644 --- a/examples/uganda/uganda/model.py +++ b/examples/population/population/model.py @@ -50,7 +50,7 @@ def step(self): self.set_random_world_coord() -class Uganda(mesa.Model): +class Population(mesa.Model): def __init__( self, population_gzip_file="data/popu.asc.gz", diff --git a/examples/uganda/uganda/server.py b/examples/population/population/server.py similarity index 89% rename from examples/uganda/uganda/server.py rename to examples/population/population/server.py index 1685a604..f00b4ef3 100644 --- a/examples/uganda/uganda/server.py +++ b/examples/population/population/server.py @@ -5,7 +5,7 @@ from mesa_geo.visualization.ModularVisualization import ModularServer from mesa_geo.visualization.modules import MapModule -from .model import Uganda +from .model import Population from .space import UgandaCell @@ -38,4 +38,6 @@ def agent_portrayal(agent): geospace_element = MapModule(agent_portrayal) num_agents_element = NumAgentsElement() -server = ModularServer(Uganda, [geospace_element, num_agents_element], "Uganda Model") +server = ModularServer( + Population, [geospace_element, num_agents_element], "Population Model" +) diff --git a/examples/uganda/uganda/space.py b/examples/population/population/space.py similarity index 100% rename from examples/uganda/uganda/space.py rename to examples/population/population/space.py diff --git a/examples/population/run.py b/examples/population/run.py new file mode 100644 index 00000000..00246200 --- /dev/null +++ b/examples/population/run.py @@ -0,0 +1,3 @@ +from population.server import server + +server.launch() diff --git a/examples/rainfall/README.md b/examples/rainfall/README.md index 8fb207cd..11f22f0e 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/T2FQwFnPDR8/0.jpg)](https://www.youtube.com/watch?v=T2FQwFnPDR8) + +## 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/uganda/README.md b/examples/uganda/README.md deleted file mode 100644 index 63367d92..00000000 --- a/examples/uganda/README.md +++ /dev/null @@ -1,14 +0,0 @@ -Uganda 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). - -## How to run - -To run the model interactively, run `mesa runserver` in this directory. e.g. - -```bash -mesa runserver -``` - -Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press `Start`. diff --git a/examples/uganda/run.py b/examples/uganda/run.py deleted file mode 100644 index abb99c88..00000000 --- a/examples/uganda/run.py +++ /dev/null @@ -1,3 +0,0 @@ -from uganda.server import server - -server.launch() 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 diff --git a/examples/urban_growth/urban_growth/server.py b/examples/urban_growth/urban_growth/server.py index d0e447fa..76003d25 100644 --- a/examples/urban_growth/urban_growth/server.py +++ b/examples/urban_growth/urban_growth/server.py @@ -10,10 +10,10 @@ def cell_portrayal(cell: UrbanCell) -> Tuple[float, float, float, float]: if cell.urban: - if cell.new_urbanized: - return 255, 0, 0, 1 - else: + if cell.old_urbanized: return 0, 0, 255, 1 + else: + return 255, 0, 0, 1 else: return 0, 0, 0, 0 @@ -58,6 +58,6 @@ def render(self, model): server = ModularServer( UrbanGrowth, [map_module, urbanized_text, urbanized_chart], - "UrbanGrowth Model", + "Urban Growth Model", model_params, ) diff --git a/examples/urban_growth/urban_growth/space.py b/examples/urban_growth/urban_growth/space.py index 3146450d..95e957b3 100644 --- a/examples/urban_growth/urban_growth/space.py +++ b/examples/urban_growth/urban_growth/space.py @@ -24,6 +24,7 @@ class UrbanCell(Cell): road_pixel: UrbanCell | None new_urbanized: bool | None + old_urbanized: bool | None def __init__( self, @@ -43,6 +44,7 @@ def __init__( self.road_found = None self.road_pixel = None self.new_urbanized = None + self.old_urbanized = None def step(self): self._new_spreading_center_growth() @@ -102,6 +104,7 @@ def load_datasets( for cell in self.raster_layer: cell.urban = True if cell.urban == 2 else False + cell.old_urbanized = cell.urban def check_road(self): for cell in self.raster_layer: diff --git a/setup.cfg b/setup.cfg index 229231dc..b9207adf 100644 --- a/setup.cfg +++ b/setup.cfg @@ -2,7 +2,7 @@ name = Mesa-Geo url= https://github.com/projectmesa/mesa-geo project_urls = - # Docs: RTD = "https://mesa-geo.readthedocs.io/en/latest/" + Docs: RTD = https://mesa-geo.readthedocs.io/en/main CI: GitHub = https://github.com/projectmesa/mesa-geo/actions GitHub: issues = https://github.com/projectmesa/mesa-geo/issues GitHub: repo = https://github.com/projectmesa/mesa-geo