GeoMason: Geospatial Support for MASON
and Distributed GeoMason

Evolutionary Computation Laboratory and
Center for Social Complexity
George Mason University

About GeoMason

GeoMason is an optional extension to MASON that adds support for vector and raster geospatial data.

A technical report giving an overview of GeoMason capabilities is provided here, and an article describing more GeoMason examples is here. Also, a draft of the GeoMason Cookbook contains "recipes" covering common GeoMason use case scenarios. The class API documentation is available here.

GeoMason is released under the Academic Free License, version 3.0.

As of August 25, 2022 the latest GeoMason version is 1.7

About Distributed GeoMason

Distributed GeoMason is an extension to GeoMason which adds facilities to use it in conjunction with Distributed MASON. It consists of a single jar file. Instructions and documentation for Distriuted GeoMason can be found in the MASON manual (see the Distributed MASON section). The jar file can be found below.

What's New

September 22, 2022 -- Distributed GeoMason 1.0 Released
This is an extension to GeoMason to allow it to work with Distributed MASON
August 25, 2022 -- GeoMason 1.7 Released
This version contains corrected application examples, a number of bug fixes, and new code for compatibility with Distributed MASON.

Getting GeoMason

Source Repository - GitHub

For the current version of GeoMason, clone the MASON GitHub repository,

GeoMason has a dependency on the following Projects under MASON
You can find these in the above mentioned Source Repository

JAR

Current Version
geomason.1.7.jar (19M)

Older versions - JAR files

Installing GeoMason

Install using JAR files

  1. Install MASON
  2. Install MASON's support libraries. Unzip libraries.zip and add the JARS within it to your Java CLASSPATH.
  3. Install GeoMason: geomason.1.7.jar
  4. Unzip GeoMason's support libaries, geomasonLib.1.7.zip, and add the JARs within it to your Java CLASSPATH.
  5. Some demo apps require large data files. If you want to run them, unzip geomasonData.1.7.zip and add the JARs within it to your Java CLASSPATH. Note that this zip file is well over a gigabyte in size.
  6. If you want to use OGR/GDAL or GeoTools extensions to GeoMason, or build GeoMason from scratch, you can install them using the instructions given below.

Install on Eclipse

In short, you'll install using the JAR files as above, but you'll need to let Eclipse know where you put them. We've thrown together a walk-through PDF document to guide you.

External File Format Support

GeoMason natively supports reading and writing ESRI shape files via the ShapeFileImporter and ShapeFileExporter classes, respectively. However, there is optional support via third party libraries for other data formats, which are described below.

GeoTools
GeoTools is a native Java library that offers support for reading a variety of geospatial vector formats including PostGIS and Web Feature Format. The GeoToolsImporter is an optional class that uses the GeoTools library to import data in those supported formats and requires that the associated GeoTools jar files be in the CLASSPATH.
 
GDAL / OGR
GDAL supports a large number of raster geospatial formats including SDTS, DTED, GeoTIFF, and USGS Digital Orthophotoquad formats. Its sibling library, OGR, can handle an equally large number of vector formats such as SDTS, GML, TIGER, S57, KML and NTF. Accordingly, GeoMason offers optional classes that use these respective GDAL and OGR libraries, GDALImporter and OGRImporter. Note that GDAL and OGR are native C++ libraries, and so will require that the jar files and the associated shared libraries be installed before these optional classes can be used.

Installing Distributed GeoMASON

Distributed GeoMASON is a collection of extensions to standard GeoMASON to allow GIS-aware models to be run on Distributed MASON. To use Distributed GeoMASON you must first install both GeoMASON and Distributed MASON. Distributed GeoMason is, well, distributed as a single jar file: The source code for Distributed GeoMason may be found in MASON's github repository. The documentation for Distributed GeoMason is found in the "Distributed MASON" section of the MASON Manual.

GeoMason Examples

Included with GeoMason are several example models. Many of them require geomasonData.1.7.zip to be installed. You can run them as:

java sim.app.geo.acequias.AcequiaWorldWithUI
java sim.app.geo.campusworld.CampusWorldWithUI
java sim.app.geo.cityMigration.CityMigrationModelWithGUI
java sim.app.geo.colorworld.ColorWorldWithUI
java sim.app.geo.conflictDiamonds.ConflictDiamondsUI
java sim.app.geo.dadaab.DadaabGUI
java sim.app.geo.ebola.EbolaWithUI
java sim.app.geo.gridlock.GridlockWithUI
java sim.app.geo.haiti.HaitiFoodWithUI
java sim.app.geo.hotspots.HotspotsWithUI
java sim.app.geo.kibera.KiberaWithUI
java sim.app.geo.masonCSC.gui.StackedAreaChartDemo
java sim.app.geo.nearbyworld.NearbyWorldWithUI
java sim.app.geo.networkworld.NetworkWorldWithUI
java sim.app.geo.omolandCA.LandscapeGUI
java sim.app.geo.refugee.MigrationWithUI
java sim.app.geo.riftland.WorldGUI
java sim.app.geo.schellingpolygon.PolySchellingWithUI
java sim.app.geo.schellingspace.SchellingSpaceWithUI
java sim.app.geo.sickStudents.SickStudentsModelWithUI
java sim.app.geo.sillypeds.SillyPedsWithUI
java sim.app.geo.sleuth.SleuthWorldWithUI
java sim.app.geo.touchingworld.TouchingWorldWithUI
java sim.app.geo.turkana.TurkanaSouthModelWithUI
java sim.app.geo.walkThisWay.WalkThisWayWithUI
java sim.app.geo.waterworld.WaterWorldWithUI

These examples are provided to highlight the basic functionality of GeoMason and act as examples for how geographically explicit models can be built. The source for these demos can be found in GeoMason's sim/app/geo directory; the corresponding data is in sim/app/data.

Here are a few of the examples (not all of them):

ColorWorld

This demo shows how to change the portrayal of individual geometries inside GeoMASON. Our simple example has agents randomly wandering around the Fairfax County, VA, voting districts. The shade of each district is based on the number of agents currently inside the district.

CampusWorld

The simulation starts by reading GIS data describing the buildings, roads, and walkways of the George Mason University Fairfax campus. All the associated attribute data, such as building names, is available through inspectors. The simulation randomly places agents on the walkways and moves them along randomly. When the agents reach an intersection they arbitrarily select a new walkway line segment to continue on.

Note that this demo shows how to write a layer to a shape file. Pressing the "stop" during a simulation run will emit shape files for the building, walkway, and agent layers.

GridLock

This basic traffic model explores how agents travel to Tyson's Corner, Virginia for work. The idea is that if you increased the number of agents (people) more congestion will arise. To some extent this is similar to the GeoMason sim.app.geo.campusworld example.The model demonstrates how you can make agents move along networks (in this case road lines in the form of ESRI shapefiles) from their origin to their destination via a shortest path algorithm.

The number of agents is based census tract information i.e. the number of people who work in Tyson's Corner and their corresponding home locations which is restricted to Washington DC, Virginia and Maryland. This movie shows the fully functional model.

Point Schelling Model

This model in a sense extends the Schelling Polygon model, however, instead of the polygon being the agent we take attribute data from the polygon model and create individual agents (see Crooks, 2010). This is based on the notion that much of the data we have comes at an aggregate level and often in some sort of vector representation of space such as census data. However, if we want to model the individuals or groups of individuals, we need to disaggregate the data.

To do this we create a number of Red and Blue agents based on population counts held within the polygon shapefile. As with the previous model, all agents want to be located in neighborhoods were a certain percentage of their neighbors are of the same type.

However, instead of using a Moore or Von Neumann which is common practice in cell based models. Here neighborhoods are calculated using buffer distance from the agent in question. If an agent is dissatisfied with its current neighborhood, it will move to a random location, regardless of whether or not this new location meets its preference. Moreover, the model demonstrates how to link points (agents) to polygons along with some other basic geographical operations (such as union, point in polygon, buffer). The movie below shows this movement both at the individual level and at the aggregate (census track level).

Refugee

Hu (2016) developed a geographically explicit agent-based model using MASON and GeoMason to explore individual movement paths for the Syrian refugee crisis whish is shown in the Figure below. The model was built utilising open data on migration routes, sources of refugees, numbers etc. (e.g. United Nations High Commissioner for Refugees, International Organisation for Migration , OpenStreetMap) and individual agent goal selection in accordance with the theory of intervening opportunities (Stouffer, 1940). A GitHub repository contains the original model.

Schelling Polygon

In this model we demonstrate how one can use polygons (such as census tracks) to create an abstract Schelling model stylized on Washington DC. The model reads in a ESRI Polygon shapefile and uses attributes of the shapefile to create Red and Blue agents and a number of Unoccupied areas. As with the traditional Schelling model, Red and Blue agents want to be located in neighborhoods were a certain percentage of their neighbors are of the same type. However, instead of using a Moore or Von Neumann which is common practice in cell based models. Here neighborhoods are calculated using the neighbors that share a common edge to the agent in question. If an agent is dissatisfied with its current neighborhood, it will move to a random Unoccupied polygon, regardless of whether or not this new location meets its preference. The movie below shows this movement.

Sick Students

This demo introduces a new agent-based model (ABM) for studying the spread of influenza through the schools and households of Fairfax County, VA. It is intended to explore the following questions. How does an epidemic outbreak spread through a school system? What containment approaches might be most effective at stopping an outbreak?

Sillypeds

This model demonstrates how one can use GeoMason to explore evacuations from a building. The simulation starts by reading raster data describing a building layout (converted from CAD files). The simulation randomly places a number of agents on walkable areas within side of the building. Once the agents have been placed on the ground, they follow the lowest cost path to the exit (in this example there is only one). The movie to the right demonstrates how the agents (red dots) move through the space, and through this movement congestion emerges around the exit. The yellow paths are traces of pedestrian moment.

SLEUTH: Urban Growth Model

This model shows a basic urban growth model based loosely on the SLEUTH model. In the sense, that we have only implemented the four growth rules (spontaneous, new spreading centers, edge and road-influenced growth) and not the self modification element of the SLUETH model. The model demonstrates how different layers (e.g. slope, land use, exclusion, urban extent - urbanized or non-urbanized, transportation, hillshade) can be read into a model to provide cells with multiple values. The movie below shows a specific growth scenario under specific coefficients (parameters) for Santa Fe, New Mexico.

Turkana

Eastern Africa has undergone sustained drought for over a decade placing a great strain on the local population. This demo introduces an agent-based model of grazing called Turkana South. The model makes use of NDVI data and monthly rainfall data to drive vegetation growth.

Note that this demonstrates how to write a layer as an ESRI ASC/Grid format. Pressing "stop" during a simulation run will emit the simulation results as an ASC/Grid file.

Water World

Inspired by NetLogo's Grand Canyon Model. The aim of the model is to show how data in the form of a elevation, can be used as a foundation of a simple spatial agent-based model. Similar to the Netlogo model, the elevation data comes from the National Elevation Dataset. It was converted from an ESRI Grid into an ASCII grid file using ArcGIS.

Similar to Sillypeds, the elevation data acts as our terrain, in this case its Crater Lake in Oregon. Agents within the model (in this case water) fall at random over the terrain and then flows downhill over the terrain. If the water cannot flow downhill, it pools up and once the gradient is sufficient, the water flows. For example, water falling in Crater Lake, initially has to pool up until the water level is sufficient to breach the caldera. Once this occurs water flows out of the lake as highlighted in the top movie to the right.

The second movie to the right highlights the testing of the inner logic of the model in the sense are the raindrops doing as they are expected to do. If you want to test this, uncomment out (e.g. remove '//') from either one of the two lines below:


// uniform landscape, completely flat
//landscape = setupLandscape();


// landscape that slopes in
//landscape = setupLandscapeGradientIn();


These lines can be found in the start method of WaterWorld.java file but ensure you comment out the (e.g. add '//' ) to the following line:


// read landscape from file
landscape = setupLandscapeReadIn("elevation.txt");

Acequias

Wise and Crooks (2012) developed an agent-based model in MASON to explore the complex social interactions of water management, which involves landowners (i.e. farmers) collectively maintaining and managing ditches which distribute water among the properties in Taos, New Mexico. More details for this model:

Wise, S. and Crooks, A.T. (2012), Agent Based Modelling and GIS for Community Resource Management: Acequia-based Agriculture, Computers, Environment and Urban Systems, 36(6): 562-572.

CityMigration

Gulden et al. (2011) develped a model that explored the dispalamnet of people. Here agents flow from one city to another over a newtwork. More details for this model:

Gulden, T., Harrison, J. F. and Crooks, A.T. (2011), Modeling Cities and Displacement through an Agent-based Spatial Interaction Model. The Computational Social Science Society of America Conference (2011), Santa Fe, NM.


Conflict Diamonds

Pires and Crooks (2016) used GeoMason to the civil war in Sierra Leone and how access to the country's diamonds provided the funding needed to sustain the insurgency. More details for this model:

Pires, B. and Crooks, A.T. (2016), The Geography of Conflict Diamonds: The Case of Sierra Leone, in Xu, K. S., Reitter, D., Lee, D. and Osgood, N. (eds.), Proceedings of the 2016 International Conference on Social Computing, Behavioral-Cultural Modeling, and Prediction and Behavior Representation in Modeling and Simulation, Washington, DC, pp. 335-345.


Dadaab

Crooks and Hailegiorgis (2014) used GeoMason to explore the spread of cholera in the Dadaab refugee camp in Kenya using a Susceptible-Exposed-Infected-Recovered model. Results from the model show that the spread of cholera grows radially from contaminated water sources and seasonal rains can cause the emergence of cholera outbreaks. More details for this model:

Crooks, A.T. and Hailegiorgis, A.B. (2014), An Agent-based Modeling Approach Applied to the Spread of Cholera, Environmental Modelling and Software, 62: 164-177.


Haiti

Crooks and Wise (2013) used GeoMason to explore the aftermath of a catastrophic event. The specific case modelled here is the Haiti earthquake of January 2010. Specifically the model explores how people react to the distribution of aid, as well as how rumours relating to aid availability propagate through the population. More details for this model:

Crooks, A.T. and Wise, S. (2013), GIS and Agent-Based models for Humanitarian Assistance, Computers, Environment and Urban Systems, 41: 100-111.


OmolandCA

Hailegiorgis et al. (2018) used GeoMason to explore how climate change could impact rural societies in less developed countries whose livelihoods rely on subsistence agriculture. This specific model uses the South Omo Zone of Ethiopia (an area of 2.3 million hectares) as a case study. More details for this model:

Hailegiorgis, A.B., Crooks, A.T. and Cioff-Revilla, C. (2018), An Agent-Based Model of Rural Households’ Adaptation to Climate Change, Journal of Artificial Societies and Social Simulation, 21 (4): 4. Available at http://jasss.soc.surrey.ac.uk/21/4/4.html.


Riftland

The RifLand Model (Cioffi-Revella et al., 2011; Kennedy et al., 2014) was developed in MASON and utilises GeoMason to simulate coupled social and natural systems. The model is based on several countries in East Africa (roughly 2.6 million km2) including Kenya, Uganda, Rwanda, Burundi, and their respective borderlands with Somalia, Ethiopia, Sudan, Democratic Republic of Congo, and Tanzania. Its purpose was to explore how climate change could impact the inhabitants (herders, farmers, urban populations) of this region including herders and farmers including their decision making (using a fast and frugal decision tree) and how this results in movement and conflict between people More details for this model:

Cioffi-Revilla, C., Gulden, T., Kennedy, W. and Coletti, M. (2011), MASON RiftLand: An Agent Based Model for Analyzing Conflict, Disasters, and Humanitarian Crises in East Africa, Center for Social Complexity, Krasnow Institute for Advanced Study, George Mason University: Working Paper, Fairfax, VA.
Kennedy, W.G., Cotla, C.R., Gulden, T.R., Coletti, M. and Cioffi-Revilla, C. (2014), 'Towards Validating a Model of Households and Societies of East Africa', in Chen, S.H., Terano, I., Yamamoto, H. and Tai, C.C. (eds.), Advances in Computational Social Science: The Fourth World Congress, New York, NY, pp. 315-328.


Kibera

Pires and Crooks (2018) used GeoMason to integrate geographic information systems and social network analysis to model the emergence of riots in the Kibera slum of Nairobi after the results of the 2007 Kenyan election were announced. More details for this model:

Pires, B. and Crooks, A.T. (2017), Modeling the Emergence of Riots: A Geosimulation Approach, Computers, Environment and Urban Systems, 61: 66-80.


Walk This Way

Crooks et al (2015) used GeoMason to explore how new sources of data (e.g., CCTV) can help inform pedestrian models. More details for this model:

Crooks, A.T., Croitoru, A., Lu, X., Wise, S., Irvine, J. and Stefanidis, A. (2015), Walk this Way: Improving Pedestrian Agent-Based Models through Scene Activity Analysis , ISPRS International Journal of Geo-Information, 4(3): 1627-1656.


MasonCSC: Studying Coupled Human- Artifcial- Natural Systems in Boreal and Arctic Region

Cioffi-Revilla et al. (2016) used GeoMason to explore the potential effects of climate change in the Boreal and Arctic regions on its inhabitants (i.e. over 205 million people in approximately 30 million households). More details for this model:

Cioffi-Revilla, C., Rogers, J.D., Schopf, P., Luke, S., Bassett, J., Hailegiorgis, A., Kennedy, W.G., Revay, P., Mulkerin, M., Shaffer, M. and Wei, E. (2016), 'MASON NorthLands: A Geospatial Agent-Based Model of Coupled Human- Artificial-Natural Systems in Boreal and Arctic Regions', The Computational Social Science Society of the Americas (2016), Santa Fe, NM.