Geospatial Modelling Environment

simulation.gridspread (Grid Spread Simulation)

Simulates the spread of an agent (e.g. fire) triggered by random events (e.g. lightening) on a raster landscape in discrete time (a cellular automata model).


This program simulates the spread of events among neighbouring cells in a raster landscape. It is designed to be as general as possible, though is inspired by the spread of fires that have been started by lightening strikes.

There are two major components to this model: 1) events that occur randomly in time and space and that can trigger a response in a landscape cell (e.g. lightening strikes starting a fire), and 2) the spread of the disturbance (e.g. fire) among neighbouring cells. This is a discrete time, discrete space simulation, and is a form of cellular automata model.

There are two spatial datasets needed to run this model, though the same raster can be used for both purposes. First, a binary (0/1) raster representing the landscape cells in which the random events can trigger a response (e.g. cells that can be ignited by lightening). Second, a binary raster representing the cells in which spread can occur. Although these may be the same raster for some processes, the flexibility exists to specify two different rasters.

There are several parameters that must also be specified. The random event component is driven by a rate parameter ("eventrate"), which must be specified in the same units as the time step of the model, and a parameter ("suscptconst") defining the probability that an event triggers a response on the landscape. The ignition component of the model works as follows. The number of events that occur in a time step is determined at the beginning of each time step by drawing from a Poisson distribution using the specified eventrate parameter. Each of these events are then randomly located on the landscape: a random row and column is selected, and provided the cell is not a NoData cell, then the event is applied to that cell. An event causes a response if a random number in the range [0,1] is less than or equal to the specified susceptibility probability (susceptconst) multiplied by the cell value (0 or 1). As such, if the cell value is 0, no response is triggered, and if the cell value is 1, then a response is triggered proportionally to susceptconst. Events occurring in NoData cells are recycled until they occur in a 0 or 1 cell. You can force an event to occur in the first time step (this is essentially equivalent to starting monitoring when an event first occurs) use the "force" parameter.

The spread model is driven by a spread probability parameter ("spreadconst") in the range [0,1]. In each time step, spread can occur from currently active (e.g. burning) cells and cells in the spread raster with a value of 1 that are not yet burning. The neighbourhood is defined as the 8 cells surrounding a cell, so spread can occur on diagonals. The probability of spread is proportional to the number of active cells surrounding a cell. A value is drawn from a binomial distribution with probability parameter spreadconst, and a size parameter equal to the number of active neighbouring cells (1-8). This random number corresponds conceptually to the number of times that the event spreads into the current cell from neighbours, and can theoretically range from 0-8. Any value greater than 0 results in spread, and the current cell becomes active in the next time step.

Cells that have just become active, either through initial ignition, or through local spread, cannot themselves spread to other cells until the next time step. The duration of the event (number of time steps) is controlled by the "duration" parameter, and must be at least 1 to allow any local spread to occur. When this duration is exceeded, the event expires, and spread can no longer occur to or from this cell.

The "timesteps" parameter controls how many time steps the simulation is run for, and "iterations" controls the number of independent iterations of the simulation to perform. All output is written to the "out" folder, using the "prefix" you specify. There is both tabular and raster output. The rasters represent the state of cells at a given time step (raster values: (1) no event has taken place, (2) an event is currently active in this cell, (3)

an event previously occurred and has now expired). The frequency at which these rasters are written is controlled by the "writefreq" value. By default, only the final raster in the time series is written. If writefreq is 1 then rasters are written at every time step, and if writefreq is 10 then rasters are written every 10th time step. It is recommended you only specify values that are exactly divisible into the number of time steps (e.g. if timesteps is 100, valid values of writefreq include 1, 2, 4, 5, 10, 20, 25, 50). If you view these rasters in ArcMap it is recommended that you switch the symbology to "unique values".

Three statistics files are also written. "prefix_modelsummary.txt" contains basic summary information and records the parameter values used in the simulation. "prefix_rawdata.csv" contains summary statistics for every time step in every iteration. "prefix_meansxtime.csv" contains mean summary statistics for every time step among all iterations. The summary statistics are:

  1. Iteration: iteration number
  2. Timestep: the time step number
  3. EventCount: the cumulative number of events that have occurred
  4. NewEventCount: the number of new events in the current time step
  5. EventReponses: the cumulative number of events that have resulted in a response in a cell
  6. SpreadCount: the cumulative number of spread events that have occurred
  7. NewSpreads: the number of spread events in the current time step
  8. ExpiredCount: the cumulative number of expired disturbances (fires go out)
  9. NewExpires: the number of expirations in the current time step
  10. ActiveCells: the number of active cells from which spread can occur in the current time step

Limitations. This simulation program is limited to rasters that are no larger than 50 million pixels. If you specify a larger raster, it will read the first 50 million pixels and perform the simulation on that portion alone. This can be a computationally intensive program to run with large datasets.


simulation.gridspread(susceptibility, susceptconst, spread, spreadconst, eventrate, out, prefix, timesteps, duration, iterations, [force], [writefreq]);

susceptibilitybinary raster (0/1) representing the susceptibility of a cell to the random events
susceptconsta value in the range [0,1] representing the susceptibility of the raster cells to the random events (this value is applied to cells of value 1 in the susceptibility raster)
spreadbinary raster (0/1) representing the susceptibility of a cell to spread of events from neighbouring cells
spreadconsta value in the range [0,1] representing the susceptibility of the raster cells to spread of events from neighbouring cells (this value is applied to cells of value 1 in the spread raster)
eventratethe rate at which events randomly occur within the defined landscape, expressed in the same units as the specified time step
outthe output folder to which all data is written (a new, empty folder is strongly recommended)
prefixthe file name prefix used when writing all output (a short, simple prefix is recommended)
timestepsthe number of time steps that the simulation is run for
durationthe duration of an event in a single cell (number of time steps)
iterationsthe number of iterations to run the simulation
[force](TRUE/FALSE) If TRUE, forces an event at the start (default=FALSE)
[writefreq]The frequency (number of time steps) at which output rasters are written e.g. 1=every time step, 10=every 10th time step (default: writes only the final raster)


simulation.gridspread(susceptibility="C:\data\landscape\susceptible.img", susceptconst=0.5, spread="C:\data\landscape\spread.img", spreadconst=0.1, eventrate=0.76, out="C:\data\landscape\sims", prefix="fires1", timesteps=100, duration=2, iterations=10, force=TRUE, writefreq=25);


Please consider making a purchase to support the continued development of these tools  Read more...

Tips on how to use this interface efficiently 


Open Source GIS

Copyright © 2001-2014 Hawthorne L. Beyer, Ph.D., Spatial Ecology LLC    Connect on LinkedIn