Maximum Entropy Modeling of Species Geographic Distributions ============================================================ INSTRUCTIONS FOR DOWNLOADING AND GETTING STARTED Miro Dudik (mdudik@cs.princeton.edu) Steven Phillips (phillips@research.att.com) Rob Schapire (schapire@cs.princeton.edu) Version 3.3.3k, October 2011 This file outlines the steps you should take to begin using maxent to model species geographic distributions. To download the program, or for background on maxent and its application to species distribution modeling, please see http://www.cs.princeton.edu/~schapire/maxent. Terms and Conditions -------------------- This software may be freely downloaded and used for all educational and research activities. This software may not be used for any commercial or for-profit purposes. The software is provided "as-is", and does not come with any warranty or guarantee of any kind. The software may not be further distributed. Downloading the Software ------------------------ The software consists of a jar file, maxent.jar, which can be used on any computer running Java version 1.5 or later. Note that if you are using a 64-bit computer, you will also need to be using a 64-bit version of Java. If you are using Microsoft Windows, you should also download the file maxent.bat, and save it in the same directory as maxent.jar. Maxent.bat assumes that your computer has at least 512 megabytes of memory. If this is not the case, you should edit the file (for example, using Notepad) to reduce the amount of memory it requests. Just replace the number "512" with a little less than the amount of memory your computer has. You also can increase the amount of memory available to the program in this fashion. If your computer has more than 512 megabytes of memory, you should increase the amount described in the file. For example, if your computer has a gigabyte of memory, replace the number "512" with "900" (leaving a little for other programs). However, if your computer is running Microsoft Windows, there is unfortunately an upper limit of about 1.3 gigabytes that Windows can give to Java. Getting Started --------------- If you are using Microsoft Windows, simply click on the file maxent.bat. Otherwise, enter "java -mx512m -jar maxent.jar" in a command shell (where "512" can be replaced by the amount of memory you want made available to the program). The program will start up, and further instructions can be obtained by pressing the "help" button. Maxent.jar can be given command line arguments, which is especially useful when running maxent in a batch (non-interactive) mode. The list of command line options is available by pressing "help" button after starting maxent. Common Problems Getting Started ------------------------------- 1. If clicking on maxent.bat causes a window to appear but immediately disappear, it is probably because of a problem with your Java installation. To diagnose this problem, you should open an ms-dos window (by clicking "start" then "run" and then typing "cmd"). Then change to the directory where the maxent.bat and maxent.jar files are and type "maxent.bat". You might get a response like this: Unable to access jarfile maxent.jar This usually happens because you used Microsoft Internet Explorer to download the maxent.jar file, and Explorer incorrectly renames the file maxent.zip. You need to rename the maxent.zip file back to maxent.jar. Alternatively, you might get a response like this: the java class could not be loaded. java.lang.UnsupportedClassVersionError: density/maxent (unsupported major.minor version 49.0) which means that the version of java that is installed on your PC is out of date. To verify this, open a command window and type "java -version". You'll probably find that it is older than 1.5, which is the oldest version recommended for use with Maxent. To get a new version, go to java.sun.com, and look for downloads for the Java runtime environment (JRE). Alternatively, you may probably get the response: 'java' is not recognized as an internal or external command, operable program or batch file. The problem is either that you don't have Java installed (you need to install from java.sun.com as above), or Java is not mentioned in your "path" variable. To fix the latter problem: 1. From the desktop, right click My Computer and click properties. 2. In the System Properties window, click on the Advanced tab. 3. In the Advanced section, click the Environment Variables button. 4. Finally, in the Environment Variables window, highlight the path variable in the Systems Variable section and click edit. Add the directory where the java executable is. For example, if you downloaded Java 1.6.0_13, it was probably installed in C:\Program Files\Java\jdk1.6.0_13, in which case you will add ";C:\Program Files\Java\jdk1.6.0_13\bin" to the end of the path variable, like in the following example: C:\Program Files;C:\Winnt;C:\Winnt\System32;C:\Program Files\Java\jdk1.6.0_13\bin 2. If the program gives "out-of-memory" or "heap space" errors, it may be because you are clicking on the maxent.jar file. You need to click on the maxent.bat file instead. If this is not the problem, click on the "help" button for more advice. Main changes in Version 3.3.3: ----------------------------- Added permutation importance to table of variable contributions Multivariate environmental suitability surfaces (MESS, formerly known as "Novel") integrated into html output Explain tool integrated into html output Updated tutorial Bug fixes Main changes in Version 3.3.2: ----------------------------- "Novel" tool to identify areas of novel climate conditions when projecting "Explain" tool to aid understanding of Maxent predictions Faster reading of ascii files Bug fixes Updated tutorial, including Novel and Explain tools A more detailed API for calling Maxent from other Java code Main changes in Version 3.3.0: ----------------------------- Replicated runs added, to allow cross-validation, bootstrapping and repeated subsampling. After a replicated run, a web page is made that analyzes and combines the results of the individual runs. Clamping pictures have changed. When projecting, the picture showing the effect of clamping now simply shows the difference between the predictions with and without clamping. Parameters are treated more uniformly, and many more are exposed in the Settings window and described in the Help window. Bug fixed in handling of bias files. The feature type buttons have a slightly different meaning, with "auto features" choosing a subset of the selected types. This allows you to limit the feature types used by auto features. More efficient memory usage, to avoid memory problems with large grids. Pictures of predictions are now created by default. Duplicate presence records are now removed by default. Projection onto SWD-format files and writing of background predictions both preserve x and y coordinates of points. The html output now gives the command line with all flags needed to repeat a run. A limited API for calling Maxent from other Java code. Main changes in Version 3.2.18: ------------------------------ Fixed bug that sometimes caused '?' values due to arithmetic overflow when computing clamping grids Response curve thumbnails now all use the same 0-1 y-axis scale What was new in Version 3.2.1: ----------------------------- Response curves are now in logistic (probability) space, rather than exponent (linear) space, so they're easier to interpret There's a second set of response curves and accompanying text, to show response of the species to variables individually rather than marginal responses The code that makes clamping pictures has been rewritten. The clamp amount now shows what effect clamping can have on the logistic prediction, rather than the exponent. There is support for .bil format In pictures of predictions, the legend now goes in the corner with least overlap with non-NODATA In .csv files, we detect ";" as separator (and in that case, also "," in place of "."), as made by French Excel File browsers now show .CSV files in addition to .csv The dontcache and responseCurvesExponent command-line arguments are described in help file. There is no longer a complaint about extra columns in SWD input files if those columns are deselected layers There is a warning if occurrence data is not in SWD format when background is in SWD format Fixed bug in writing _samplePredictions.csv file: training predictions were sorted by prediction value, but their lat/long weren't staying with them Fixed bug in .html: was writing wrong feature categories when auto features was overridden Fixed bug in project: clamping wasn't always keeping response constant outside the training range, e.g. for quadratic features What was new in version 3.1 --------------------------- Fixed bugs in: DIVA output format calculation of estimate of maximum achievable AUC processing of occurrences with partial environmental data writing of logistic values to _samplePredictions.csv file reporting of output type in .html files option to change number of background points Added logistic output to samplePredictions.csv and omission.csv files Added new entropy-based threshold to thresholds table in .html files Revised wording about maximum achievable AUC in .html files What was new in version 3.0 --------------------------- Variable contributions: The html output has a table that gives the percentage contribution of each variable to the Maxent model. This gives a new way (in addition to the jackknife) of interpreting the influence of each variable on the model. Logistic output format: There is a new default output grid format, called "logistic". Logistic values range from 0 to 1, and model the probability of presence of the species, assuming that sampling effort is similar to the effort expended to obtain the training samples. See the help button for more details. Clamping picture: Whenever a model is projected onto a different set of environmental variables, a picture is produced showing where clamping has occurred, colored according to the amount of clamping. DIVA data types. Compatibility problems have been resolved, so Maxent can now successfully read and write DIVA's .grd format. Increased categorical regularization. The default regularization of categorical features was causing over-fitting for some data sets, especially those with larger numbers of categories and training presences. Categorical regularization has therefore been increased, but is still adjustable using the "beta_categorical" flag. Better memory usage. Larger grids of environmental data can now be used without running out of memory. Faster file handling. By default, any .asc file used during training or projection will have a cached compressed version saved in a subdirectory called "maxent.cache". The cached version is then used to speed up future runs. ROC plot axis labels have been fixed. Bug fixed in jackknifing: previously, test performance of leave-one-out runs was too low when running with lots of training presences. New options to control clamping during projection. The flag "fadebyclamping" causes the prediction at a point to decrease when there is clamping there, with the amount of decrease determined by the amount of clamping. The "dontextrapolate" option causes the prediction to be zero wherever there is clamping. More data and details added to maxentResults.csv file. Information available from the "help" button -------------------------------------------- The help button gives details on topics including: Input data formats Control parameters Outputs A quick overview of the maximum entropy method Command line options Troubleshooting