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