When you click the Run button, the Preferences window disappears and is replaced by the Simulation window. The horizontal bar is a simple time clock that lets you estimate how long a run will take. Each time the bar increments, approximately 4% of the iterations have been completed.
If you want to end the simulation prematurely, without completing it, click on the Abort Simulation button or the X button in the upper right hand corner of the window. This will stop everything and take you back to the original opening menu. The simulation window also tells you the matrix size and the current iteration number.
After BioGeoSim has finished all of the iterations and calculations, the simulation window disappears and is replaced by a series of tab notebooks. Each tab window contains an important element of your output.
[ Top of Page ]
The most recent version of BioGeoSim can be downloaded from:
http://www.garyentsminger.com/biogeosim/biogeosim.htmBioGeoSim is an interactive computer program for analyzing biogeography simulation models. BioGeoSim uses a gridded map of a biogeographic domain, simulates the placement of species geographic ranges within the domain, and then compares observed and expected species richness in each grid cell. BioGeoSim performs Monte Carlo randomizations to create null assemblages, then statistically compares the patterns in these randomized communities with those in the real data matrix. These null model tests have wide applicability in both applied and basic ecology.
This help file will introduce you to the program and teach you how to use BioGeoSim for null model tests with your own data.
BioGeoSim was used in the development of the following publication:
Rahbek, C., N.J. Gotelli, R.K. Colwell, G.L. Entsminger, T.F.L.V.B. Rangel, and G.R. Graves. 2007. Predicting continental patterns of bird species richness with spatially explicit models. Proceedings of the Royal Society B 274: 165-174.
This paper gives details on the application of the model and its philosophical justification. It's available as a free .pdf download at the BioGeoSim home site:
http://www.garyentsminger.com/biogeosim/biogeosim.htm[ Top of Page ]
Nicholas J. Gotelli is a faculty member in the Department of Biology, University of Vermont. He is the author of A Primer of Ecology (1995, 1998; 2001; Sinauer Associates) and, with Gary R. Graves, of Null Models in Ecology (1996; Smithsonian Institution Press), and, with Aaron Ellison, of A Primer of Ecological Statistics (2004; Sinauer Associates).
Gary L. Entsminger is a writer, computer programmer, and natural historian. He programmed BioGeoSim (2004-2007) and EcoSim (1995-2004). Recently, he wrote several book length reports on vital signs monitoring and database management for the National Park Service (2004-2007). In addition, he has written over 100 articles for computing journals and eight books about programming, including The Tao of Objects (1990, 1995; M&T Books), Secrets of the Visual Basic Masters (1992, 1994; Howard W. Sams), The Way of Delphi (1996; Prentice-Hall), and The Way of Java (1997; Prentice-Hall).
Carsten Rahbek is a Professor at the University of Copenhagen, Denmark, and the director of the Center for Macroecology. His main research interests are patterns of species distribution, species range sizes, species assemblages, species richness and what determines such patterns. Recent focus has been on the role of scale and conceptual formulation and practical design of null- and predictive models that allow direct testing of hypotheses related to patterns of diversity.
Robert K. Colwell is Board of Trustees Distinguished Professor at the University of Connecticut, where he works with biogeographical theory and models, biodiversity informatics and statistics. His field studies concern the ecology and evolution of species interactions, particularly in the tropics.
Gary R. Graves is a natural historian who studies the biology of wood warblers and hybridization in hummingbirds using genetic, stable isotope, behavioral, morphological, and demographic data. In a broader context, he employs multiple approaches to the study of biogeography and speciation of Neotropical birds.
[ Top of Page ]
Although BioGeoSim is software and not a journal publication, you should cite it just as you would a research article. This will ensure that the authors receive credit for their contribution and make it easier for other researchers to repeat your work using BioGeoSim. The correct citation format is:
Gotelli, N.J., G.L. Entsminger, C. Rahbek, R.K. Colwell, and G.R. Graves. 2007. BioGeoSim. Version 1.0. Acquired Intelligence Inc. & Kesey-Bear.
http://www.garyentsminger.com/biogeosim/biogeosim.htm
We know that journal and book editors can be picky, but we'd really appreciate it if you could tuck the BioGeoSim website address in your citation. This will allow your readers to find the software more easily. BioGeoSim is a copyrighted product, but you may freely copy and use it.
The most recent version of BioGeoSim can be downloaded from:
http://www.garyentsminger.com/biogeosim/biogeosim.htm[ Top of Page ]
We are anxious to get your feedback and to hear about your experiences with BioGeoSim. Your comments and suggestions are most welcome and will help us to improve BioGeoSim. Please contact us:
Gary Entsminger[ Top of Page ]
BioGeoSim's main screen displays an empty 6 x 6 data spreadsheet. You can enter values directly into this spreadsheet and use the arrow and tab keys to move between different cells. We anticipate that most data sets analyzed in BioGeoSim will be created by other programs, but you can also enter them by hand through the editor.
[ Top of Page ]
BioGeoSim allows you to cut and paste text from a variety of output and input screens. This makes it relatively exchange data and results between BioGeoSim and other programs.
Click the right mouse button to access copy, paste, and cut functions within BioGeoSim. Most windows that contain text allow simple cutting and pasting from a menu displayed by clicking the right mouse button.
[ Top of Page ]
The absolute data matrix limits are approximately 240,000 cells, or approximately 800 by 300 rows and columns. In addition, each null model has its own specific limits. BioGeoSim can also be limited by the amount of memory in your PC. If BioGeoSim seems to be running slowly (it shouldn't!), close one or more of the programs you're also running. That should help. Also, if you're running very large simulations with BioGeoSim, after you're finished, exit BioGeoSim entirely and restart it to free up all available memory. BioGeoSim seems to be very stable, and we have successfully run large simulations that have taken as long as 10 days to complete.
[ Top of Page ]
We've tried to provide users with a rich palette of simulation options. However, we recognize that novice users may not be certain which choices are best. Each BioGeoSim preferences window appears with default values pre-selected. In the help section, we explain why we chose these particular options.
We encourage users to experiment with the different options. As with any statistical tool, BioGeoSim can be abused or misused by an ignorant researcher. Don't rely mindlessly on the default values; they may not be appropriate for your particular data set or question! The Caveats section of this help file points out important assumptions and common pitfalls in these kinds of analyses.
BioGeoSim 'remembers' the settings that you request from one run to the next. However, BioGeoSim will provide a fresh random number seed for each run unless you give it a specific random number seed. Press the reset defaults button in the preferences window if you want to reestablish all of BioGeoSim's default settings for a particular module.
[ Top of Page ]
[ Top of Page ]
You can invoke the BioGeoSim Text Editor (the Edit Matrix As Text functionality) by selecting the Edit | Edit Matrix As Text menu item. When you call the Text Editor, your data appears in a notebook style editor window. You can easily cut, copy, paste and delete data within this window. But be careful to follow the rules for BioGeoSim's data format as you edit. To carry out editing functions, click the right mouse button, which will bring up a menu of standard editing functions (cut, paste, copy, delete, & select all). You can also select Edit | Tabs to Spaces from the edit menu of the text editor, which is a very useful feature for importing data from spreadsheets.
When you're finished editing, select the Close Editor item from the menu of the Text Editor. BioGeoSim will then ask if you want to retain your editing changes. BioGeoSim then returns you to the main BioGeoSim window where you see that your data have been updated in the main grid.
If you want to make these changes permanent, be sure to save them to disk when you return to the main BioGeoSim window. Data modified in the Text Editor are not automatically saved to disk.
[ Top of Page ]
[ Top of Page ]
BioGeoSim's Open and Save File Dialogs look for data files that have the .TXT extension.
[ Top of Page ]
Use the Open command under the File menu to open an existing data file. This file could be one you previously created and named with BioGeoSim or an ASCII text file that you created with another program. As long as you use a plain text file and put the data in the correct format (data separated by spaces), BioGeoSim will be able to open it. If the data aren't in the correct format, BioGeoSim will probably open the file, but you'll probably need to edit the data. You will need to load several files for a BioGeoSim analysis, and the file loading is handled with buttons that become available with the Analyze menu item.
BioGeoSim expects imported data to be in a particular format. Specifically, each file (domain maps and species maps) is in the form of a rectangular (or square) matrix, with each cell in the matrix corresponding a point in a gridded map. Input files should not have any row or column labels or any information other than the gridded data. This restriction is important so that BioGeoSim can properly read the size of each matrix that you give it. Thus, a small species map with four rows and five columns should, in correct format, look like:
0 0 1 1 1
0 0 1 1 1
0 1 1 1 1
1 1 1 1 0
Notice that each data point (i.e., each cell) is separated from the next cell by a single space. As explained later, domain maps can have non-negative real numbers and species maps can have 0s or 1s. Negative numbers are now allowed in any of the maps, and BioGeoSim will not complete its analysis if it detects a negative number in the data!
[ Top of Page ]
We've found that one of life's greatest headaches is getting data out of spreadsheet packages and into other applications. Although you can certainly export a data file from your spreadsheet and then import it into BioGeoSim, we have tried to make it easy for you to just cut and paste your data directly. Here's how you should do it:
1. Open a new data matrix in BioGeoSim.
2. Use the menu command "Edit matrix as text" (CTRL E) to open the text editor window.
3. Open your Excel spreadsheet and select your data matrix.
4. Copy your data matrix (CTRL C in most Windows applications).
5. Go back to BioGeoSim and position the cursor where you want your data in the text editor window.
6. Paste in your data (CTRL V, as in most Windows applications).
7. From the edit menu in BioGeoSim, select "Tabs to spaces" (CTRL T) to strip out the tabs that Excel adds to your data.
That's all there is to it! It is often helpful to move back and forth between the text editor window and the data matrix window. The "transpose matrix" function that is available from the data matrix window is very helpful for setting the data columns temporarily as data rows, which can then be copied, deleted, or moved easily in the text editor window.
As always, make sure you remember that BioGeoSim is looking for a single space or a comma as a delimiter between adjacent cells in your data matrix.
[ Top of Page ]
To install BioGeoSim, BioGeoSimHelp, and the sample data files:
Create a directory on your hard disk. Name it whatever you like. We suggest you name it 'BioGeoSim'.
Then copy the self-extracting file, BioGeoSim.exe on the BioGeoSim disk to the directory you create.
Then run BioGeoSim.exe. It will extract all system, Help, and tutorial data files to the proper folders.
Note that BioGeoSim requires no special setting of CONFIG.SYS or *.INI files. Nor does BioGeoSim create temporary folders or files elsewhere.
Also note that if you have a screen saver installed, and if it isn't well behaved, you might encounter problems when BioGeoSim is simulating large data sets. If your screen saver behaves weirdly or crashes, turn it off while you're running large, time-consuming simulations. Normally there are no conflicts between BioGeoSim and well-behaved screen savers.
[ Top of Page ]
The null model generates a number of pseudo-assemblages by randomizing the input matrix. The Iterations option determines this number. The Default is set to 100, a small number, because the classic null model test for goodness-of-fit is usually not of primary interest in these model analyses. The more iterations you use, the greater the precision of the estimate of the tail probability. This is because BioGeoSim calculates tail probabilities by tabulating the number of times the observed statistic is greater than or less than that in the pseudo-communities.
If 1000 iterations are used, we would reject the null hypothesis if the observed value was less than or equal to 50 of the 1000 values generated for the null communities. If only 100 iterations were used, the rejection point would be if the observed was less than or equal to the simulated in 5 out of the 100 iterations.
[ Top of Page ]
We recognize that many academic ecologists use Macintosh computers, and we would have liked to have produced a version of BioGeoSim for the Mac. However, we wanted to develop BioGeoSim as quickly as possible and for the widest possible audience. Thus, we chose the PC and the Windows operating environment.
We developed BioGeoSim with Delphi, a powerful object-oriented programming environment that uses the underlying Object Pascal language. This state-of-the-art development tool is not available for the Mac. Without it, it would have taken us much longer to produce the version of BioGeoSim you're using.
However, all is not lost for Mac users who have access to a PC! BioGeoSim can use data files created on the Mac in Word, Excel, or any other program that allows you to save ASCII text files. These files can then be transferred to a PC disk and imported directly into BioGeoSim. Similarly, BioGeoSim output and transition matrices can be saved to ASCII text files that can then be read by a Macintosh computer.
[ Top of Page ]
Data can be entered into BioGeoSim in two ways. You can:
* Create a data set directly within BioGeoSim
* Import a text file that contains a data set
Once the data is in BioGeoSim, you can perform basic editing functions within the spreadsheet-style or grid editor, or you can manipulate the data in a notebook-style text window by Editing Data as Text.
[ Top of Page ]
Here are the menu items you will encounter on the main BioGeoSim menu. The first word is the menu header, and the word after the slash is the menu command.
File | New
This command creates a fresh 6 x 6 data matrix in the main BioGeoSim screen.
File | Open
This command lets you open a previously saved file from disk.
File | Close
This command lets you save (and name) your data file to disk.
File | Save As
This command lets you save a data file under a new name. This is useful if you're editing or experimenting with your data set and need to save several different versions.
File | About
This command tells you the full file name and the dimensions of the matrix.
File | Exit
This command closes BioGeoSim and returns you to Windows.
Edit | Resize Matrix
This takes you to a dialog box that lets you specify the dimensions of the matrix. New rows or columns are added as necessary, with default species and site names added. If you specify matrix dimensions that are smaller than the current matrix, BioGeoSim strips off the extra rows and columns from the end of the matrix.
Edit | Transpose Matrix
exchanges all of the rows in the data set with all of the columns.
Edit | Edit Matrix as Text
takes you to the text editor, which allows you to edit your data more extensively in a notepad-style window.
Edit | Edit Matrix as Text | Edit | Tabs To Spaces
converts tabs in your data set to single spaces, which is a godsend when trying to import Excel spreadsheets.
Convert
opens a second program "Little Bear", which contains routines for reformatting the output from BioGeoSim for additional analysis in other programs.
Analyze
takes you to several tabs with options for setting up the simulation model and loading the data files.
Help | Help Topics
takes you to the main window of the help file (which you are currently reading).
Help | About
shows you the current version number of BioGeoSim that you are using.
[ Top of Page ]
We've designed BioGeoSim to have an intuitive graphical interface. The program opens onto a data matrix controlled by five pull-down menus:
File
Edit
Convert
Analyze
Help
Use the File and Edit menus to import, edit, and manipulate the basic data files. The Analysis menu leads to the different BioGeoSim options and modules. Convert opens a second program, Little Bear, for manipulating BioGeoSim Output, and Help takes you to this file and the About Us screen.
Once you select Analyze, the data window disappears, and you're presented with a Preferences window that contains a number of options for the simulation you're running. You can change these options to customize the simulation or use the defaults that BioGeoSim provides. BioGeoSim 'remembers' your changes from one run to the next, so you can easily experiment with the options and see how they affect the results. Clicking the Restore Defaults button resets the BioGeoSim default choices.
You can also cancel the simulation or access this help file from the Preferences window. Once you have selected the options you want, the Run button starts the simulation. The Preferences window disappears and a Simulation window pops up while the program is running. It contains information about the simulation and keeps you posted about its progress. An abort button lets you terminate the simulation at any point.
When the simulation is completed, the simulation window disappears and is replaced by a series of tabbed notebooks. By clicking on different tabs, you can quickly jump back and forth from one window to the next. The tabs are arranged to be read consecutively from left to right.
[ Top of Page ]
Each time you run a simulation, BioGeoSim generates a new sequence of random numbers by reading a random number seed from the internal time clock. To repeat a sequence with the same set of randomizations, use the same seed. This will produce an identical sequence. Otherwise, you'll get a different sequence of random numbers. The results will be similar, but not exactly the same.
The default value for the random number seed is zero, which instructs BioGeoSim to go the clock for a new value. You can enter a specific seed (an integer from 1 to 2,147,483,647) for a particular run. Each time you run a new simulation, the random number seed is recorded in the summary window, so you have a complete record of your results.
[ Top of Page ]
Use the Edit | Resize Matrix command to add or delete rows or columns. These column and row operations always take place at the end of the matrix. Thus, BioGeoSim adds or deletes the last rows or the last columns in the data set.
[ Top of Page ]
If you check this box, BioGeoSim will write each of the simulated matrices to separate files. BioGeoSim will automatically generate these file names for you (sim1.txt, sim2.txt...). The number of matrices saved will equal the specified number of iterations. This file will have the same format as the original data file, and the dimensions of each matrix will be the same as the dimensions of the original input matrix.
CAUTION: Checking this option will slightly slow the operation of BioGeoSim, but more important: it will consume substantial disk space! Unless you have some other plans for the simulated matrices, there is no need to generate them and save them to disk.
If you just want to see one of the simulated matrices, you will be able to do that in the output tabs. If you would like to look at a few matrices, you could set the iterations to a modest number, and then save them to disk. It is unlikely you would ever want to save 1000 simulated matrices unless you plan to write your own program that uses these matrices for some other purpose that is not covered by BioGeoSim´s standard output.
[ Top of Page ]
The Simulation tab shows you the most recent simulated matrix that was created by BioGeoSim. By clicking back and forth between the Input and Simulation tabs, you can examine this randomized matrix and convince yourself that BioGeoSim has randomized the data the way that you wanted it to.
Different preference choices will change the appearance and structure of the simulated matrix. Also note that the contents of the simulated matrix will change each time you run the simulation, unless you've re-entered a particular random number seed.
[ Top of Page ]
Most BioGeoSim modules produce a p-value that tells you how extreme your observation is relative to the histogram of observations from the simulated communities. To allow you to compare results meaningfully among different studies, most modules also generate a standardized effect size. This effect size appears within the Summary display and is calculated as:
(Observed index - Simulated index)/(Standard deviation of simulated indices)
Thus, your observed index is rescaled as the number of standard deviation units above or below the mean of the simulated values. Negative standardized effect sizes indicate that the observed index was less than the mean of the simulated indices; positive values indicate that the observed index was greater than the mean of the simulated indices. The approximate 95% confidence intervals for the standardized effect size are -1.96 to 1.96. However, you should always report the probability value that BioGeoSim calculates directly from the histogram itself.
The rationale for the standardized effect size follows directly from meta-analysis. In meta-analysis, a standardized comparison of experimental data is made between a "control" and a "treatment" group, with an estimate of the pooled variance for these treatments. Of course, in a null model analysis, there is no "experiment." However, we can think of the simulated matrices as a type of "control" for the effects of species interactions, and the observed matrix as the "treatment" that may show the effects of those interactions.
One potential disadvantage of using the standardized effect size is that the histograms of simulated values that BioGeoSim generates often are not normally distributed, even though this is an assumption underlying the calculation. But this disadvantage is offset by having a standardized index that measures the effect size from different studies on a common scale.
[ Top of Page ]
This tab summarizes all of the important results from the previous output tabs. It also contains an essential 'paper trail' of your simulation. It lists the BioGeoSim module, the input file name, number of iterations, random number seed, and all the options that were selected in the Preferences window. With this information, you can recreate any null model output that you have generated.
The content of the Summary tab will contain the observed metric calculated for the input matrix, and summary statistics (mean, median, variance) on the variables calculated from the simulated matrices. The Summary tab contains its own text editor, so you can delete unneeded results and annotate the output extensively.
The Summary tab does not contain the expected species richness per cell, but that can be saved as a separate file to work with in a graphics or statistics program. The Little Bear program will convert BioGeoSim output into a variet of formats for subsequent analysis.
[ Top of Page ]
BioGeoSim requires the Windows 2000 (or later) operating system and as much memory as possible for large similations. We recommend at least 1 GB of RAM. The more the merrier. In short, BioGeoSim should run on any PC that runs Windows 2000 (or later) effectively. It is a very efficient program which allocates only the memory it needs and releases it each time it finishes a simulation.
If you plan to save the simulated matrices, you will need additional disk storage space corresponding to the size of the input matrix times the number of iterations.
The time it takes to run a module will vary greatly depending on the options and number of iterations you specify and the dimensions of the input matrix. Large data sets, high numbers of iterations and/or certain simulation options could cause simulations to run for several minutes or even hours and days. In this case, BioGeoSim operates in the background of Windows, so you can use your computer for other tasks while BioGeoSim works.
[ Top of Page ]
The BioGeoSim Data and Tutorial Help is a set of integrated .htm files. You can run BioGeoSim Help by selecting Help from any of the several Help buttons within BioGeoSim or by running BioGeoSim Help as a stand alone help file. To run stand alone Help, load BioGeoSim tutorial.htm into your Browser.
The BioGeoSim Data/Tutorial Help System includes the following topics:
Introduction to Module
Data Format
Defaults
Options
Output
Caveats
Module Tutorial
Literature Cited
A navigator link at the bottom of the Help screen in each module will return you to the initial list of topics.
[ Top of Page ]