Isaac I. Ullah, PhD bio photo

Isaac I. Ullah, PhD

Computational Archaeology, Complex Adaptive Systems, Social-Ecological Systems, Geoarchaeology

Email Twitter Facebook Google+ Flickr Github Zotero Stackoverflow

GRASS GIS and custom modules for archaeological and socio-ecological research


What is GRASS GIS?

GRASS is a very powerful and completely free GIS software suite for Linux, Macintosh, and Windows. It is developed for scientists by scientists, and is fully open-source. This means you know exactly what the software does, and how it does what it does. You even have citations to the scholarly publications that provided the algorithms used. Also, if you find an error, don’t like something, or want a missing feature, you can get involved and request or enact those changes yourself! Open software promotes the scientific method, and pushes the goals of open knowledge generation, information and skill sharing, and open-access data curating forward.

Please visit the the GRASS homepage ( for more information about GRASS, GRASS modules, tutorials and other resources for open-source GIS. I also manage the GRASS GIS Facebook page, which you may wish to join if you’d like to keep in touch about GRASS-related topics in a more social media-ish way. Finally, you should also check out the OS-Geo homepage for information and downloads of many other great pieces of open-source geospatial software.

GRASS “Addon” modules for computational archaeology

I have coded and contributed several custom modules that you can add to GRASS via the “g.extention” addon manager (see below). I list the modules here, with brief descriptions and citations to the publications in which they are employed. I have updated most of these for use in GRASS 7, and will be maintaing these versions only (i.e., I no longer support the GRASS 6 versions of these modules). These tools are specifically formulated to accomplish computational analyses of archaeological, socio-ecological, and geoarchaeological problems or data. See the note below for instructions on how to install stable versions of these addons. Development versions are hosted in my GRASS_Addons GitHub repository. Please feel free to contact me with any questions or comments about these modules.

Maintained Modules (regularly updated for GRASS 7.x versions)

  • r.landscape.evol – Simulates the cumulative effect of erosion and deposition on a landscape over time. This module uses appropriate flow on different landforms by default; however, singular flow regimes can be chosen by manipulating the cutoff points. This module has been used in several of my publications, including Barton, Ullah, & Mitasova 2010, Barton Ullah, & Bergin 2010, Ullah & Bergin, 2012, and Barton, Ullah, et al., 2012. In particular, the details of the equations and methods can be found in Mitasova, Harmon, et al., 2013.

  • r.catchment – Creates a raster buffer of specified area around vector points using cost distances. This module was used in several of my publications, but was the main focus of Ullah 2011., and was used extensively in Barton, Ullah, & Mitasova 2010, among others.

  • r.viewshed.cva – Undertakes a “cumulative viewshed analysis” using a vector points map as input “viewing” locations. This module uses the fast viewshed module “r.viewshed,” developed by Laura Toma, Yi Zhuang, William Richard, and Markus Metz. “r.viewshed.cva” was used in Ullah, 2015, and is in use for work I plan to publish shortly.

  • r.floorsim – Simulation of artifacts deposition on a housefloor, with site formation disturbance, sampling, and re-randomization. This module is used in Ullah, Duffy, and Banning 2014.

  • r.soildepth – Estimates soil depths on a landscape based on hillslope curvatures. A demonstration of the use of this module can be found in my 2014 EAA presentation.

  • – A grass module that connects to an external Agent-Based (or other) model of human landuse decision-making to enact changes to a GIS landscape. The module requires the external ABM to pass it a list of the number of farming, grazing, and woodgathering plots needed by a series of households in a village. The module then assesses which land cells agents will use, and creates output impacts maps, and adjusts landcover and soil fertility according to agent impacts. These impacts can then be fed into r.landscape.evol to simulate their effect on erosion and deposition. This module is used in many of my publications, including Barton Ullah, & Bergin 2010, Ullah & Bergin, 2012, and Barton, Ullah, et al., 2012.

  • r.agropast.semiadaptive – This is a fully functional script that is not yet in the official GRASS repository because I have not had time to write the docuementation for it yet. Follow the instructions in the ReadMe file on my GitHub if you want to install it. An earlier version of this module was used in Barton, Ullah, and Heimsath, 2016, and this new version is used in a series of experiments that will be published soon.

  • test_pit_sim – This is a fully functional simulation model that uses GRASS and must be run from within a GRASS7.x session, but which is not a regular GRASS addon module and which will not be hosted in the GRASS addon’s repository. This is being used in research into percolation theory and the way in which archaeologists survey for, and excavate sites. This work will be presented at the 2017 Society for American Archaeology meeting in Vancouver. Stay tuned!

Depricated GRASS 6.x modules (unmaintained, with no plans for upgrades or backports from GRASS 7.x versions.)

  • r.landscape.evol

  • r.catchment


  • r.cfactor – Converts a map of landcover values to a c-factor map based on a set of reclass rules. (GRASS 6 only)

  • r.agropast.extensive – Creates a series of iterative landuse maps from a pastoral catchment and an extensive (swiddening) agricultural catchment (both need to be created by r.catchment), and outputs c factor as well. This module was used in Barton, Ullah, & Mitasova 2010. (GRASS 6 only)

  • r.agropast.intensive – Creates a series of iterative landuse maps from a pastoral catchment and an intensive agricultural catchment (both need to be created by r.catchment), and outputs c factor as well. This module was used in Barton, Ullah, & Mitasova 2010. (GRASS 6 only)

  • r.shift.cult – Creates a series of iterative agricultural landuse maps from a catchment created by r.catchment. This model takes natural vegetation succession into account. Optionally outputs c factor as well. This module was used in Barton, Ullah, & Mitasova 2010. (GRASS 6 only)

How to install GRASS Addon Modules

The simplest way to install these (and other) addon modules in GRASS is to use the “g.extension” module. See the help pages for g.extension for instructions on how to use it. This method will work in both GRASS 7 and GRASS 6, and is the preferred method. It may be useful (especially in GRASS 6) to set a custom folder for your addons to live in, which can be done by setting the “GRASS_ADDON_PATH” environmental variable (instructions here).

If you can’t get g.extension to work, then any addon module can be downloaded directly from the GRASS addon SVN repository ( GRASS 7 versions, GRASS 6 versions), and the script file can be saved in your grass addons folder (set with GRASS_ADDON_PATH in GRASS 6 (or 7), or in the default ~/.grass7/addons/ directory in GRASS 7), or the “scripts” directory of the main GRASS install tree (e.g., /usr/local/grass6.4.4/scripts/ on a linux installation of GRASS 6). Note that to install scripts in the system directory, you will likely need administrator (or root) privileges on your system. Also make sure you set the downloaded file to be “executable”.

Once the module is installed following one of the above methods, it can be run by typing its name at the GRASS command prompt, e.g. >r.landscape.evol &. Note that the & will ensure that the module runs modally, and doesn’t lock the terminal to that process.