mesa-geo introduction

this is a study share or tutorial for mesa-geo study beginner

an interesting metaphor:

（You’re Under Arrest!——anime） Natsumi is a female police officer with short hair, while Miyuki is a female police officer who is driving. They are traffic police officers and spend most of their time executing tasks together, with a smaller portion of time spent separately.

When executing tasks separately, Miyuki’s greetings to Natsumi:

• Moshi moshi!
• Natsumi, which district of Tokyo are you in now? Are you still on duty there? How far is it from where you are to the Motodome Police Station? What are you planning to do after your shift? Are you heading back to Motodome?

At this moment, Tokyo is the city where Natsumi and Miyuki are located, but they are in different areas, which can be regarded as neighborhood agents or region agents.

When we consider Natsumi as a person agent, her name “Natsumi” is actually a unique ID.

“What are you planning to do after your shift?” can actually be seen as what the next step is, or simply “step”.

The interaction between Natsumi, Miyuki, and the city constitutes the model among agents. We need to place them and the city into both spatial and temporal sequences.

1.introduction of mesa-geo package

mesa-geo is a python package which is a extension of mesa package. mesa-geo can help us to conduct Agent based modeling.
https://github.com/projectmesa/mesa-geo

• with mesa-geo, we can build build a geosapce which can contain or support gis Agents
• Compared to traditional Agents, geoAgents have more geometry attributes: shapely, CRS coordinate system…

the geo_data mesa-geo use:

• we can directly use shapely package to create a geometry object on our own.
• we can also import existing geometric objects -> vector data: shp, geojson, geodataframe.

for example:

• Use the point function from the shapely package to generate corresponding coordinate points for the person agent.
• Directly import the regional data of any place.

2.the existing geometric data which can be used by mesa-geo

raster data

• Divided into a grid and segmented into individual pixels, which ensures a uniform format and facilitates uniform operations.
• Detailed representation of various features, resulting in large data volumes.

import rasterio  
#open the rasterio  
ds=rasterio.open('\...\...tif') 

vector data

• Only stores geographic objects such as points, point lists, and related features, resulting in smaller data volumes.
• Accurately represents point-line-plane elements.
• Facilitates modification and editing.

import geopandas as gpd  
gdf = gpd.read_file('\...\...\...shp') 

import matplotlib.pyplot as plt
# read the geojson data
file_path = '\...geojson'
file_path = "\...\....geojson"
gdf_0 = gpd.read_file(file_path)

# draw the map
fig, ax = plt.subplots(1, 1, figsize=(10, 10))
gdf_0.plot(ax=ax, alpha=0.5, edgecolor='k')
ax.set_title('regions')
ax.set_xlabel('Longitude')
ax.set_ylabel('Latitude')

# show the map
plt.show()

3.what is GeoAgent?/how to use the geo_data?

what can be done with these geo_data in mesa-geo?

put the GeoAgents into the geospace! this geo_data are the location where agents are.

however, before we put the GeoAgent into the geospace, let’s figure it out what is GeoAgent.

GeoAgent:

GeoAgent has different kinds of attributes: unique_id, model where the agents are put, geometry, crs

GeoAgent can be buildings, people and others all you hope they have locations in your simulation process.

GeoAgent can move or change state which are set as rules function

GeoAgent will have a string of actions as time goes, so agents have step()function

set GeoAgent Class: set attributes(properties) and rules of agents action

what do attributes, rules fuction and step fuction look like?

• attributes and basic variables

class regionAgent(mg.GeoAgent):

    def __init__(self, unique_id, model, geometry, crs,agent_type ="no_war",war_infection_risk=0.1 ,war_recovery_rate=0.2):
        super().__init__(unique_id, model, geometry, crs)
        self.atype= agent_type
        self.war_infection_risk=war_infection_risk
        self.war_revovery_rate=war_recovery_rate
        self.in_war_step=0
    #(p.s.this is from my war spread abm model created by myself, and I will introduce it clearly later)

• move function

    def move_point(self, dx, dy):
        """
        Move a point by creating a new one
        :param dx:  Distance to move in x-axis
        :param dy:  Distance to move in y-axis
        """
        return Point(self.geometry.x + dx, self.geometry.y + dy)
#this is from official tutorial example

• state change fuction

    def is_unhappy(self):
        if self.is_red:
            return (
                self.model.space.get_region_by_id(self.region_id).red_pct
                < self.SIMILARITY_THRESHOLD
            )
        else:
            return (
                1 - self.model.space.get_region_by_id(self.region_id).red_pct
            ) < self.SIMILARITY_THRESHOLD
#this is from official tutorial example

• step fuction: which can contains the move or state change rules directly or fuction indirectly.
• which can also contains the time register(observer) function.

def step(self):
    self.war_spread()
    self.model.counts[self.atype] += 1

Allocate a location(geographic object) to every GeoAgent:

what we should do next: is to instantiate the GeoAgent in our model

there are several ways:

• using the geo_file we methioned
• using the geometry

using geo_file

ac=mg.AgentCreator(XXAgent, model=self)

instantiate_object = ac.from_file(
    self.XXdate,
    unique_id="name",
    set_attributes=True
)

using the geometry

instantiate_object = mg.AgentCreator(
XXAgent,
model=self,
crs=self.space.crs,
agent_kwargs={}
)

point
XXobject= unique_shelter.create_agent(
    point, "xx" + str(j),
)

put the GeoAgent into space

this is very easy, just put every instantiate_object into the space. it’s OK!

self.space.add_agents(instantiate_object)

4.the time and space in mesa-geo

the time in mesa-geo

the time in mesa-geo is the same as mesa package

it is relevent to mesa.time this module, let’s go on!

• Core idea, simplified: First, line up the little ones, then let them slide down the slide one by one.
• For each agent, set up a step() function, add the agent to the time series of the schedule, and finally, activate them all uniformly through schedule.step().

import mesa
import mesa_geo as mg
#??mesa.time #you can check it yourself

the given example without considering spatial arrangement, but focusing only on the changes in steps:

I have set up a scenario where everyone initially stands in a single line. Each person will take one step forward in their next move. Where will they be after taking 10 steps?

here are some methods of sheldule of mesa:

• mesa.time.RandomActivation(self)
• mesa.time.SimultaneousActivation(self)
• mesa.time.BaseScheduler(self)

import mesa  
  
class Person(mesa.Agent):  
    def __init__(self, unique_id: int, model: 'TestModel') -> None:  
        super().__init__(unique_id, model)  
        self.yuyu = self.random.randint(1, 10) #为每一个agent随机分配一个位置
  
    def step(self):  
        self.yuyu = self.yuyu+1  
        print(self.unique_id,self.yuyu)  

class TestModel(mesa.Model):  
    def __init__(self):  
        super().__init__()  
        #you can try different kinds of methods: just try it!
        self.schedule = mesa.time.RandomActivation(self)
        #self.schedule = mesa.time.SimultaneousActivation(self)
        #self.schedule = mesa.time.BaseScheduler(self)
        self.create_agents()  
  
    def create_agents(self):  
        for i in range(10):  
            personagent = Person(unique_id=i, model=self)  
            self.schedule.add(personagent)  
  
    def step(self):  
        self.schedule.step()  
   
model = TestModel()  
for _ in range(10): #here we repeat 10 times
    model.step()

the space in mesa-geo

we will use mg.geospace，and this module is created based on geobase

geospace: initiate the crs(coordinate system) and layers and so on

geospace fuction:

basic function：

• to_crs: you can change the crs of space, e.g. change the degree crs into m crs
• agents(self)：Return a list of all agents in the Geospace(agents layer)
• layers(self): Return a list of all layers in the Geospace.
• total_bounds(self): Return the bounds of the GeoSpace in [min_x, min_y, max_x, max_y] format.
• geo_interface_(self)

add or remove agents function：
when we want to move the agents, we can use this kind of function

• add_agents(self, agents)：add
• remove_agent(self, agent):remove out

search for specific agent：
when we design the state change fuction or move function, we can use them

• get_relation(self, agent, relation):
• get_intersecting_agents
• get_neighbors_within_distance

describe the agent distance and relationships：

• agents_at(self, pos)
• distance(self, agent_a, agent_b)
• get_neighbors(self, agent)
• get_agents_as_GeoDataFrame

#you can check this module yourself, believe in yourself!
import mesa_geo as mg
#??mg.geospace

5.Model: the part bridge agents, time and space

what you should do is: instantiate all of the GeoAgents and put them into step(time) scheldule and geospace.

and them, run your instantiated model object, you can wait the agents ‘play with’ each other, it’s so fantastic!

6.some tricks:

When we need to set up transitions between different states for an agent:

• Using if-elif-else syntax can achieve this.
• Setting thresholds and recorders for some states, allowing transitions when certain levels are reached.

I want to express in code how to randomly generate two types of objects:

• Set a threshold value at 0.5 (or other values).
• Assign a random number to a specific object and check if this random number is greater than or less than the threshold of 0.5 to naturally categorize it.
• For example: is_red = random.random() < self.red_percentage.

To implement a person’s movement within a circular area centered on themselves with a radius of r:

• Assign a random number within the range [0, r] to represent the distance they will move.
• mobility_range = self.random.randint(0,self.mobility_range) or self.random.uniform(0, self.mobility_range)