readme.txt

Maximum Entropy Modeling of Species Geographic Distributions
============================================================

INSTRUCTIONS FOR DOWNLOADING AND GETTING STARTED

Miro Dudik          (mdudik@microsoft.com)
Steven Phillips     (mrmaxent@gmail.com)
Rob Schapire        (schapire@microsoft.com)

Version 3.4.3, November 2020

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://biodiversityinformatics.amnh.org/open_source/maxent.


Terms and Conditions
--------------------
This software is distributed under the MIT License.


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.4.4:
-----------------------------
   Minor bug fix.
   
Main Changes in Version 3.4.3:
-----------------------------
   Fixed a bug that was causing abrupt changes in response curves for some floating -point predictor variables,
     due to the "add samples to background" option not adding all samples for floating-point predictors.

Main Changes in Version 3.4.2:
-----------------------------
   Fixed bug that causes nodoclamp flag not to work for dismo's predict method for MaxEnt objects
   
   
Main Changes in Version 3.4.1:
-----------------------------
   Fixed bug that caused regularization multiplier to be have increasing effect over multiple runs


Main Changes in Version 3.4.0:
-----------------------------
   Added cloglog output transformation, and made it the default output format
   Threshold features are no longer used in default settings


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