Documentation
GEOGSIM
Cross-platform ecological simulation
v1.6.3 (June 2008)
CONTENTS
INTRODUCTION ............................................................................................................................... 2
ECOLOGICAL PRINCIPLES AND ASSUMPTIONS .............................................................................. 3
GEOGSIM MODEL DESCRIPTION .................................................................................................... 5
SIMPLE USAGE INSTRUCTIONS ...................................................................................................... 7
ADVANCED USAGE INSTRUCTIONS ................................................................................................ 9
PRE- AND POST-PROCESSING TOOLS .......................................................................................... 11
RUNNING GEOGSIM EXPERIMENTS ............................................................................................. 12
REFERENCES ................................................................................................................................. 13
APPENDIX
System requirements:
Java Runtime Environment 5.0 or higher, 46kb disk space, and 512kb (min) RAM.
1
INTRODUCTION
GeogSim is a spatially explicit, individual-based model that simulates interactive dynamics
between plant species. The model assumes all species are annual plants that germinate, grow and
produce seeds while competing for resources with their neighbors, disperse seeds, and then die in
a single "season."
Germination is by a weighted lottery among seeds present at a given site. Competition is based a
modification of the hyperbolic competition function (Firbank and Watkinson 1985) describing
interactions between the target plant and those in the eight neighboring cells. Dispersal follows a
Gaussian distribution. Users set the competition coefficients, and the fecundity and dispersal
parameters to explore their effects on community dynamics. Users can also explore the effects of
fine-scale habitat structure on community dynamics by setting a proportion of the landscape cells
as uninhabitable, as would be the case in rocky or otherwise patchy environments.
The program can be run in two ways, simple and advanced. Simple usage comprises a graphical
user interface and non-repeatable results and is useful for informal exploration and classroom
use. Advanced usage is done from a command line and is intended for research applications.
Java Runtime Environment 5.0 or higher (www.java.com for download) must be installed to run
GeogSim.
GeogSim was designed by Duane Griffin and written by Phil Marquis.
2
ECOLOGICAL PRINCIPLES AND ASSUMPTIONS
GeogSim is built on a number of ecological principles and assumptions. The most fundamental
of these are:
1.
2.
3.
4.
organisms require resources to grow and reproduce,
individual organisms differ in their ability to obtain resources and produce offspring.
resources are finite, and
organisms produce more offspring than the environment can support.
Together, these four facts imply that
5. Organisms compete for finite resources.
6. Those organisms best able to obtain the resources they need will differentially survive
and reproduce.
Within species, competition leads to selection for genotypes that work best in a particular
environment. Over time, such environmental selection leads to changes in the frequency of
alleles within a population, i.e., evolution.
Competition between species leads, all other things being equal, to the species best able to
obtain resources eventually excluding all others in its habitat. This is the “competitive
exclusion principle” (the CEP). It places strict limits on the number of species that can
coexist in a habitat, at least in theory.
We can confirm the CEP’s validity in laboratory experiments and in simulations like
geogSim, but we rarely (if ever) see it occur in nature: most ecological communities contain
more than one species. The reason why is embedded in the phrase “all other things being
equal.” The CEP depends on a number of conditions that must all be met in order for
exclusion to occur. Palmer (1992) identifies these as:
A) the environment is spatially uniform
B) the environment is temporally constant
C) growth is limited by only one resource
D) species have the opportunity to compete,
E) there has been sufficient time for exclusion to occur, and
F) rare species have no advantages over common ones
If these conditions are met, competitive exclusion should occur. They rarely obtain in natural
settings, however. Real environments are never uniform, conditions change on timescales
from hours to centuries, so competitive advantage shifts from place to place and time to time.
Similarly, organisms require multiple resources and vary in their abilities to obtain them, so
tradeoffs allow coexistence. Species may use the same resource at different times, or physical
characteristics can block interactions. Either way, species that do not interact cannot
compete, and thus cannot exclude one another. Even among species that are competitively
equivalent, exclusion will occur eventually due to random population fluctuations, though it
may take tens of thousands of generations for this to occur. Disturbances such as fires,
3
windthrow, or disease outbreaks “reset the clock” on population dynamics, disrupting
trajectories towards exclusion. Finally, rarity can confer benefits in the form of reduced
populations of predators or herbivores, parasites, pathogens, or other density-dependent
impediments to survival.
The more these conditions are violated, the more species can coexist. The CEP thus provides
a framework way of understanding why a particular environment harbors the diversity that it
does, and can provide insights useful for conservation and management.
GeogSim explicitly incorporates Conditions A, B, and C into its design. It allows users to
explore violation of Condition D by adding unoccupied cells to the landscape matrix, which
disrupt interactions between individuals. Condition E can be manipulated by disrupting and
restarting simulation runs or assessed by evaluating times to extinction with varying
parameters. Rarity is a disadvantage in the model underlying geogSim, so it does not account
for or provide a means of manipulating Condition F.
4
GEOGSIM MODEL DESCRIPTION
GeogSim was originally conceived to investigate the effects of habitat spatial pattern on
competitive interactions and coexistence. It is a reaction-diffusion model in which seed
production alternates with the seed dispersal and colonization lottery, which together constitute a
single “season.” (Figure 1).
Figure 1. Conceptual diagram of geogSim reaction and diffusion phases.
Simulations occur within a square landscape of grid cells, each of which represents a microsite
capable of supporting one plant. GeogSim landscapes are toroidally wrapped to avoid edge
effects.1
For simplicity’s sake, the model treats all species as annuals that complete their entire life cycle
in a single season. In reality, seeds of annual species are durable, allowing species to persist in
seed banks for long periods of time until conditions are favorable for germination. Incorporating
seed banks into the model would add realism but would slow trajectories towards extinction that
the model is designed to evaluate. Thus, geogSim assumes no persistence of seeds from one
season to the next.
Reaction Phase
The reaction phase begins with seed production under local competition in the eight cells
surrounding the target plant (Figure 2). Competition is based on a modification of the hyperbolic
competition function (Firbank and Watkinson 1985) which, for three species, i, j, and k takes
the form:
Fi = Φi(1+ αiiNi + αijNj + αikNk)-1
Where F is the number of seeds produced, Φ is the fecundity parameter (the number of seeds a
plant will produce in the absence of any competitors), Nx is the number of species x in the eight
neighboring cells, and αxy is the competition coefficient for species x on species y.
In a greenhouse study of competition in the early stage of life for six herbaceous species,
Goldberg and Landa (1991) identified alpha values ranging from -0.3 to 10.76, though most
(>90%) fell between 0.15 and 1.5 (~60% are between 0.15 and 0.75).
1
That is, cells located along a top or side edge interact with those at bottom or opposite side, so the simulation space
is a toroid (donut-shaped).
5
Figure 2. Competition neighborhood. In this case, the target plant, B, is surrounded by six
individuals of species A and two of species B.
Diffusion Phase
Once the number of seeds produced has been calculated, these values are distributed around the
parent cell following a Gaussian distribution with a user-specified mean (distance from the
parent) and standard deviation.
Which species germinates on a given microsite is determined by a weighted lottery from the
seeds present at the site.
6
SIMPLE USAGE INSTRUCTIONS
Simple usage takes place in a graphical user interface (GUI) through which users can set model
parameters and view the simulation as it takes place. It is intended primarily for instructional use
and for preliminary investigations.
Download the geogSim.jar file to a folder or the desktop. On most computer systems, doubleclick the geogSim.jar file to launch the program. Alternatively, open a command window and
type:
java -jar geogSim.jar
This assumes that the java command is already in your path to executables (the Java installation
process should take care of this).
The GUI includes a representation of the “landscape” and buttons for controlling the simulation
(Figure 3).
Figure 3. geogSim graphical user interface.
The “Species” button opens a window where users can add new species, set the fecundity
parameters, change the color used to represent each species, and access the dispersal parameter
window by clicking the “Gaussian” button (Figure 4a).
Users model different patterns of seed dispersal by changing the parameters of the Gaussian
function used to distribute seeds. Dispersal length changes the mean distance from the parent
plant that seeds are dispersed, and dispersal width alters the degree to which the distribution is
clumped or spread out. The effect of three sets of dispersal parameters are shown in Figure 4b.
The “System” button opens a window that allows users to set the size of the landscape (up to 256
x 256 grid cells), the number of time steps that the simulation will run, and the proportion of
unoccupied cells.
7
Figure 4a (left). The species and dispersal control windows. Figure 4b (right) Dispersal
patterns generated with dispersal mean and standard deviation set to 0 and 1 (yellow), 0 and 5
(white), and 10 and 5 (red).
The “Alpha” button allows users to set the competition coefficients (Figure 5).
Figure 5. Competition coefficient control window. In this case, each individual of
Sp.1 will decrease fecundity of Sp.2 by 1.9 times as much as would a neighboring
species one individual. Similarly, a Sp.2 individual has 1.2 times as much effect
on a Sp.1 plant than would another Sp.1 individual.
The “Run” button starts a new simulation run. “Pause” interrupts the run temporarily, while
“stop” ends the run.
“Renew” sets a new landscape (including a random starting location for each species) and begins
a new simulation run (species and landscape parameters do not change). Because outcomes can
be affected by the initial locations, you should use “Renew” rather than “Run” when doing a
series of simulation runs.
“Export” saves the landscape to a text file that can be opened using a spreadsheet, ArcGIS, or
other applications that support comma-separated (.csv) file imports.
8
ADVANCED USAGE INSTRUCTIONS
Running geogSim from a command line enables users to choose between stochastic or
deterministic modes, and GUI or non-GUI modes. Command line usage requires three text files
specifying the landscape and the model and species parameters (e.g., map.dat, params.dat and
species.dat). Results are written to comma-delimited text files.
Stochastic vs. deterministic mode
GeogSim uses a random number generator for the germination lottery during the growth phase of
the model. By default, geogSim runs in stochastic mode, in which the seed value for random
numbers is determined by the computer's time stamp. As such, outcomes are not repeatable.
In deterministic mode, the random number generator uses a seed value, which ensures repeatable
results for a given seed. Multiple runs within a series will have different seeds, but subsequent
series (e.g. with different map or parameter settings) using the same seed value will follow the
same progression of random numbers in the lottery phase.
A command line flag “-d” enables deterministic mode. Example:
java -jar geogSim.jar -d species.dat map.dat params.dat <output> (note that the species, map, and
params files can have any name you like, as long as they are specified in the command line
sequence.
GUI vs. Non-GUI
By default, GeogSim runs in graphical user interface (GUI) mode. The command line flag “-n”
runs the simulation in non-GUI mode (deterministic) to speed computation.
File Formats
The map, species, and parameter files must be ASCII text files (map files must be tab-delimited).
The pound sign (#) indicates lines that geogSim ignores, and can be used for comments.
The species file contains information about each of the species that will be present in the
simulation. You may name the species anything you like. Standard deviation and mean refer to
the seed dispersal function and phi is the maximum number of seeds that an individual will
produce in ideal conditions. Additional species may be added by appending more lines to the end
of the file.
Sample species file:
#
# species parameters
#
# species name, std deviation, mean, phi
a,0.9,4.0,200
#
#
b,0.5,2.0,255
9
The params file contains information about the system as a whole. The random seed is the seed
value for initializing the pseudorandom number generator (some number must be present). The
alpha competition array is the matrix of coefficients that determine how the species interact with
one another. This matrix will always be n x n, where n is the number of species.
Sample parameter file:
# parameters for sim:
#
# number of time steps
30
#
# random seed
591250
#
# alpha competition array
# 1-1 2-1
# 1-2 2-2
1.0,3.0
6.0,1.0
#
The map file specifies the inhabited and uninhabited cells in the simulation and also contains the
location of the initial individuals. A “0” represents an empty site; a “1” represents uninhabitable
space; any other letters/numbers must correspond to names in the species file. Columns are
separated by tabs. The file must include the header (its format is same as used in ESRI's ArcGIS
output files, which can be used as input files in geogSim). The parameters 'nrows' and 'ncols'
specify the map size (row and column numbers must be equal). GeogSim ignores the remaining
GIS parameters (xllcorner, yllcorner, cellsize, NODATA_value). Note that map files may not
include comments.
Sample map file:
ncols 10
nrows 10
xllcorner -127.37922702362
yllcorner -363.73943236715
cellsize
4
NODATA_value 0
0
0
0
0
1
0
0
0
0
1
0
0
a
0
1
0
0
0
0
1
0
0
0
0
1
0
0
0
0
1
0
0
0
0
1
0
0
0
0
1
0
0
0
0
1
0
0
0
0
1
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
b
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
10
PRE- AND POST-PROCESSING TOOLS
GeogSim also includes pre- and post-processing tools for performing experiments with multiple
runs.
To begin, ensure that all three .jar files reside in the current directory. Also ensure that the
directory contains a valid map file, species file, and parameter file.
The pre-geogSim tool is used for preprocessing the runs and running the simulation. Given an
initial files, it will run geogSim the number of times specified in the parameter file. The tool uses
the original parameter file to generate many more parameter files, each with a different random
seed (these seeds are chosen (pseudo)randomly, based on the original seed value). The tool then
runs geogSim on each of the new parameter files, using the existing map file and species file.
Command line syntax:
java -jar pre-geogSim-util.jar speciesFile mapFile paramsFile experimentName numberOfRuns
The pre-geogSIm tool yields a series of ASCII text output files in CSV (comma separated
values) format, one from each run. These .csv files contain information about the state of the
simulation at each time step and can be imported into a spreadsheet or other software.
To get a sense of what's going on globally and eliminate the influence of outlying data, the postgeogSim tool averages these .csv outputs and condenses them into a single file (summary.csv).
The summary file contains the average and standard deviation of the number of individuals at
each time step. The file also contains a footer with time-to-extinction (TTE) averages and
standard deviations. The post-util will find all the .csv files in the current directory and produce
the summary output.
Command line syntax:
java -jar post-geogSim-util.jar
11
RUNNING GEOGSIM EXPERIMENTS
Basic logic and procedures
Care in designing and setting up experiments will reduce errors and save a great deal of time. In
command-line mode, geogSim will produce a parameter file and an output file for each
individual run and write these to the folder in which geogSim.jar resides or the folder specified
in the command instruction. An experiment comparing five different landscapes, with 100 runs
in each, for example, will produce 1,000 new files. Keeping these files organized is critical.
The following setup will keep everything organized and reduce confusion.
Setting up experiments: file and folder structure.
Create a folder for the entire experiment, and subfolders for each treatment (i.e., each version of
the landscape or parameter file being investigated). Name the folders and subfolders in a way
that makes sense for the particular experiment.
Your main folder should include a log file that details each step of the experiment, including a
description of how you set up the folders, each step of the procedure (with time and date stamps,
in case something goes wrong and you need to sort files later), and results obtained.
If you will be conducting multiple experiments, copy the entire main folder and paste a copy in a
subfolder called “Blank_Experiments.” Make copies of this folder, in turn, for each subsequent
experiment.
Place the appropriate landscape, parameter, and species file in each subfolder, together with a
copy of the geogSim.jar file and copies of the pre- and post-processing tools. The geogSim.jar
and pre/post-processing tools are very small, so having multiple copies in various folders will not
tax system resources.
Using this structure, you can simply navigate to the appropriate folder (in the command
window), enter the command-line instructions, and run your experiment.
Using batch files to control experiments.
Typing command line instructions for a single set of runs is not burdensome, but any error—no
matter how small—will prevent the experiment from running. Batch files are small scripts that
automate tasks from the command line. Batch files greatly simplify the process of running an
experiment and ensure uniformity between its various parts.
If you are using an operating system that allows you to use batch files, you can create a batch file
with the command line instructions for pre-processing, running the experiment, and post
processing. You can then place the file in the appropriate subfolder and conduct a series of runs
by simply clicking on it or typing its name in the command line. You can even create a “master”
batch file in the main folder that will change directories as needed and run the entire experiment
from a single command.
12
Alternatively, you may be able to type the command line instructions in your log file, copy it,
and paste it into the command line.
Example
The log from a geogSim experiment is included in the Appendix and illustrates the steps
involved in using the program in deterministic mode. Note that this experiment was done with
version 1.5, which used a different competition algorithm than the current version, so duplicating
the experiment will yield slightly different results.
REFERENCES
Firbank, L. G., and A. R. Watkinson. 1985. On the analysis of competition within 2-species
mixtures of plants. Journal of Applied Ecology 22:503-517.
Goldberg, D.E. and K. Landa. 1991. Competitive effect and response: hierarchies and correlated
traits in the early stages of competition. Journal of Ecology 79: 1013–1030.
Palmer, M.W. 1992. Variation in species richness: towards a unification of hypotheses. Folia
Geobotanica et Phytotaxonomica 29: 511-530.
13
APPENDIX: LOG FILE FOR A GEOGSIM EXPERIMENT
_____________________________________________________
GEOGSIM Log
4/6/2007 3:08 PM
Experiment 01
Purpose:
Explore effect of slight fragmentation on time to extinction of a weaker competitor in very small
(100 cell) landscapes. Null hypothesis: there is no difference in time to extinction of weaker
species between the two landscapes.
Description:
10 runs of 2 species in 2 different landscapes with unbalanced competition. Phi and dispersal are
equal for both species. Species are named “a” and “b".
Each landscape contains 100 habitat cells. Landscape01 is 10 x 10 and has no barriers;
landscape 02 is 12 x 12 and is split into four 5 x 5 blocks.
1. 4/6/2007 3:35 PM
Set up folders with this structure:
Copied all geogSim files to each folder.
2. 4/6/2007 3:40 PM
Created grid files using MS Excel (C:\Experiment_01\landscapes.xls).
Exported to tab-delimited text files (LS01.txt and LS02.txt) in new folder
(C:\Experiment_01\grids\).
Added headers to grid files and saved as Map.dat in 01 and 02 folders.
14
Map, landscape 01:
ncols 10
nrows 10
xllcorner -127.37922702362
yllcorner -363.73943236715
cellsize
4
NODATA_value 999
0
0
0
0
0
0
0
0
0
0
a
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
b
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
b
0
0
0
0
0
a
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
1
0
0
0
0
0
1
1
1
1
1
1
1
1
1
1
1
1
1
0
0
0
0
0
1
0
0
0
0
0
1
0
0
0
0
0
1
0
0
0
0
0
1
0
0
b
0
0
1
0
0
a
0
0
1
0
0
0
0
0
1
0
0
0
0
0
1
Map, landscape 02:
ncols 12
nrows 12
xllcorner -127.37922702362
yllcorner -363.73943236715
cellsize
4
NODATA_value 999
0
0
0
0
0
0
0
0
0
0
a
0
0
0
0
0
0
0
0
0
1
1
1
1
0
0
0
0
0
0
0
0
0
0
b
0
0
0
0
0
0
0
0
0
1
1
1
1
0
0
0
0
0
1
0
0
0
0
0
1
1
1
1
1
1
1
1
1
1
1
1
1
3. 4/6/2007 4:21 PM
Created parameter and species files
param.dat file:
-------------# parameters for sim:
#
# number of time steps
30
#
# random seed
591250
#
# alpha competition array
# 1 on 1, 2 on 1
# 1 on 2, 2 on 2
1.0,2.0
4.0,1.0
#
species.dat file:
-------------#
# species parameters:
#
# sp. name, std deviation, mean, phi
a,3.0,1.0,0.0,100
b,3.0,1.0,0.0,100
#
#
15
3. 4/6/2007 4:48 PM
Created master batch file (Exp01.bat) to run experiment:
cd 01
java -jar
java -jar
cd..
cd 02
java -jar
java -jar
PAUSE
pre-geogSim-util.jar species.dat map.dat params.dat Exp01-01 10
post-geogSim-util.jar
pre-geogSim-util.jar species.dat map.dat params.dat Exp01-02 10
post-geogSim-util.jar
Tested batch file with 2 runs. Worked fine. changed the number of runs parameter and ran
experiment.
4. 4/6/2007 5:05 AM
Run bat file for each folder.
Results:
Time to Extinction
16.0
14.0
Time Steps
12.0
10.0
8.0
6.0
4.0
2.0
0.0
1
2
Landscape
Time to extinction (circles) with 95% CI
Reject null hypothesis that there is no difference in persistence of weaker species between the
two landscapes.
16
Average populations of each species (closed circle = Sp. A; open circle = Sp. B; dashes = 95%
CI)
Landscape 01
120
100
Cells
80
60
40
20
0
0
2
4
6
8
10
Time Step
Landscape 02
120
100
Cells
80
60
40
20
0
0
2
4
6
8
10
Time Step
17