GRASS logo

NAME

r.maxent.train - Create and train a Maxent model

KEYWORDS

modeling, Maxent

SYNOPSIS

r.maxent.train
r.maxent.train --help
r.maxent.train [-ybgwecflqpthanjdsxviu] samplesfile=name environmentallayersfile=name [togglelayertype=string] [projectionlayers=name] [suffix=string] [nodata=integer] outputdirectory=name [samplepredictions=name] [backgroundpredictions=name] [predictionlayer=name] [outputformat=string] [betamultiplier=float] [randomtestpoints=integer] [testsamplesfile=name] [replicatetype=string] [replicates=integer] [maximumiterations=integer] [convergencethreshold=float] [lq2lqptthreshold=integer] [l2lqthreshold=integer] [hingethreshold=integer] [beta_threshold=float] [beta_categorical=float] [beta_lqp=float] [beta_hinge=float] [defaultprevalence=float] [maxent=name] [threads=integer] [memory=memory in MB] [precision=integer] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-y
Create a vector point layer from the sample predictions
Import the file(s) with sample predictions as point feature layer.
-b
Create a vector point layer with predictions at background points
Create a vector point layer with predictions at background points
-g
Create response curves.
Create graphs showing how predicted relative probability of occurrence depends on the value of each environmental variable.
-w
Write response curve data to file
Write output files containing the data used to make response curves, for import into external plotting software.
-e
Extrapolate
Predict to regions of environmental space outside the limits encountered during training.
-c
Do not apply clamping
Do not apply clamping when projecting.
-f
Fade effect clamping
Reduce prediction at each point in projections by the difference between clamped and non-clamped output at that point.
-l
Disable linear features
Do not use linear features for the model (they are used by default).
-q
Disable quadratic features
Do not use quadratic features for the model (they are used by default).
-p
Disable product features
Do not use product features for the model (they are used by default).
-t
Use product features
By default, threshold features are not used. Use this flag to enable them.
-h
Disable hinge features
Do not use hinge features for the model (they are used by default).
-a
Do not use automatic selection of feature classes
By default, Maxent automatically selects which feature classes to use, based on number of training samples. Use this flag to disable autoselection of features.
-n
Don't add sample points to background if conditions differ
By default, samples that have a combination of environmental values that isn't already present in the background are added to the background samples. Use this flag to avoid that.
-j
Use jackknife validation
Measure importance of each environmental variable by training with each environmental variable first omitted, then used in isolation.
-d
Keep duplicate presence records.
Keep duplicate presence records. If environmental data are in grids, duplicates are records in the same grid cell. Otherwise, duplicates are records with identical coordinates.
-s
Use a random seed
If selected, a different random seed will be used for each run, so a different random test/train partition will be made and a different random subset of the background will be used, if applicable.
-x
Add all samples to the background
Add all samples to the background, even if they have combinations of environmental values that are already present in the background
-v
Show the Maxent user interface
Use this flag to show the Maxent interface. Note that when you select this option, Maxent will not start before you hit the start option.
-i
Copy maxent.jar to addon directory
Copy the maxent.jar (path provided with the 'maxent' parameter) to the addon scripts directory.
-u
Overwrites maxent.jar in addon directory
Copy the maxent.jar (path provided with the 'maxent' parameter) to the addon scripts directory. If the file already exists in the addon directory, it is overwritten.
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

samplesfile=name [required]
Sample file presence locations
Please enter the name of a file containing presence locations for one or more species.
environmentallayersfile=name [required]
Sample file with background locations
Please enter the file name of the SWD file with environmental variables (can be created with v.maxent.swd or r.out.maxent_swd).
togglelayertype=string
Prefix that identifies categorical data
Toggle continuous/categorical for environmental variables whose names begin with this prefix (default: all continuous)
projectionlayers=name
Location of folder with set of environmental variables.
Location of an set of rasters representing the same environmental variables as used to create the Maxent model. They will be used to create a prediction layer based on the trained model.
suffix=string
Suffix for name(s) of prediction layer(s)
Add a suffix to the name(s) of imported prediction layer(s)
nodata=integer
Nodata values
Value to be interpreted as nodata values in SWD sample data
Default: -9999
outputdirectory=name [required]
Directory where outputs will be written.
Directory where outputs will be written. This should be different from the environmental layers directory.
samplepredictions=name
Name of sample prediction layer
Give the name of sample prediction layer. If you leave this empty, the default name given by Maxent will be used.
backgroundpredictions=name
Name of background prediction layer
Give the name of background prediction layer. If you leave this empty, the default name given by Maxent will be used.
predictionlayer=name
Name of raster prediction layer
Give the name of raster prediction layer. If you leave this empty, the default name given by Maxent will be used.
outputformat=string
Representation probability
Representation of probabilities used in writing output grids. See Help for details.
Options: cloglog, logistic, cumulative, raw
Default: cloglog
betamultiplier=float
Multiply all automatic regularization parameters by this number.
Multiply all automatic regularization parameters by this number. A higher number gives a more spread-out distribution.
Default: 1.0
randomtestpoints=integer
Percentage of random test points
Percentage of presence localities to be randomly set aside as test points, used to compute the AUC, omission, etc.
Default: 0
testsamplesfile=name
Test presence locations
Use the presence localities in this csv file to compute statistics (AUC, omission, etc.).
replicatetype=string
Number of replicates in cross-validation
If replicates > 1, do multiple runs using crossvalidate,bootstrap or subsample. See the Maxent help file for the difference.
Options: crossvalidate, bootstrap, subsample
Default: crossvalidate
replicates=integer
Number of replicates in cross-validation
If replicates > 1, do multiple runs of this type: Crossvalidate: samples divided into replicates folds; each fold in turn used for test data. Bootstrap: replicate sample sets chosen by sampling with replacement. Subsample: replicate sample sets chosen by removing random test percentage without replacement to be used for evaluation.
Options: 1-20
Default: 1
maximumiterations=integer
Maximum iterations optimization
Stop training after this many iterations of the optimization algorithm.
Default: 500
convergencethreshold=float
Convergence threshold
Stop training when the drop in log loss per iteration drops below this number.
Default: 0.00005
lq2lqptthreshold=integer
Threshold for product and threshold features
Number of samples at which product and threshold features start being used.
Default: 80
l2lqthreshold=integer
Threshold for quadratic feature
Number of samples at which quadratic features start being used.
Default: 10
hingethreshold=integer
Threshold for hinge feature
Number of samples at which hinge features start being used.
Default: 15
beta_threshold=float
Regularization parameter for treshold features
Regularization parameter to be applied to all threshold features; negative value enables automatic setting.
Default: -1.0
beta_categorical=float
Regularization parameter for categorical features
Regularization parameter to be applied to all categorical features; negative value enables automatic setting.
Default: -1.0
beta_lqp=float
Regularization parameter for lin, quad and prod features
Regularization parameter to be applied to all linear, quadratic and product features; negative value enables automatic setting.
Default: -1.0
beta_hinge=float
Regularization parameter for hinge features
Regularization parameter to be applied to all linear, quadratic and product features; negative value enables automatic setting.
Default: -1.0
defaultprevalence=float
Default prevalence of the species
Default prevalence of the species: probability of presence at ordinary occurrence points. See Elith et al., Diversity and Distributions, 2011 for details.
Options: 0-1
Default: 0.5
maxent=name
Location Maxent jar file
Give the path to the Maxent executable file (maxent.jar)
threads=integer
Number of processor threads to use.
Number of threads for parallel computing
Default: 1
memory=memory in MB
Maximum memory to be used (in MB)
Maximum memory to be used by Maxent (in MB)
Default: 300
precision=integer
Precision suitability map
Set the required precision (in the form of number of decimal digits) of the species suitability raster layer (leave empty for default).

Table of contents

DESCRIPTION

With r.maxent.train a Maxent presence only model can be created using the Maxent software. As input, the addon requires two comma-separated files, one with the species locations and another of background points locations. Both need to include columns with the X, Y and sample values of the environmental variables that you want to use as predictor variables. You can use the r.out.maxent_swd or v.maxent.swd addons to create these files. For more details about the structure of these files, see the Maxent website.

The only other requirement is to provide an output folder. With these inputs, a Maxent model will be created. If you also provide a folder with environmental raster layers with names corresponding to the names of the environmental variables in the SWD files, the module will create a prediction (suitability distribution) raster layer as well.

Note that the Maxent software generates ASCII files without projection information. That means you need to make sure yourself that the environmental layers you provide are in the same reference coordinate system as your current mapset. An easy way to ensure this is by using the v.maxent_swd from the same mapset to create those input environmental layers for Maxent. See the example workflow in the Examples.

The addon provides access to nearly all parameters available in the Maxent software. On the above-mentioned website, you can find a tutorial that explains most of these options. For the other options, see the Maxent help file.

NOTES

This addon requires the Maxent software. You can download the software from the Maxent website. The software includes a Maxent.jar file. The first time you run the addon, you need to use the maxent parameter to set the path to the Maxent.jar file. Set the -i flag to copy the jar file to the addon/script directory. On subsequent runs, you do not need to set the maxent parameter anymore.

If you want to update the Maxent.jar file, use the -u flag. Removing the Maxent.jar file needs to be done manually. Go to the GRASS GIS addon directory, and delete the Maxent.jar file. To find the addon directory, open GRASS GIS and on the command line, type: 

echo
$GRASS_ADDON_BASE

The r.maxent.train addon runs Maxent in the background. If you want to check the Maxent settings first, you can set the -v flag to open the Maxent user interface with all parameters filled in. You will need to hit the Run button to actually run Maxent.

Besides the files directly generated by Maxent, the addon creates the maxent_explanatory_variable_names.csv file. This file contains the names of the model explanatory variables. You can use this when you quickly want to check the names of the explanatory variables, e.g., when using r.maxent.predict.

Examples

1) Sample dataset

The examples below use a dataset that you can download from here. It includes vector point layer with observation locations of the pale-throated sloth (Bradypus tridactylus) from GBIF, a number of bioclim raster layers from WorldClim, the IUCN RedList range map of the species, and a boundary layer of the South American countries from NaturalEarth.

The zip file contains a folder sampledata. This is a location with two subfolders PERMANENT and southamerica. If you are not familiar with the concept of Locations and Mapsets, please first read the explanation about the GRASS GIS database.

Unzip the file, start up GRASS GIS, open the GRASS GIS database to which you copied the folder sampledata, switch to the Location sampledata and then open the mapset southamerica.

2) Preparing input data

You can use the v.maxent.swd to create the required input layers. The code below creates the SWD file with the locations where the species has been recorded (species_output) and a SWD file with randomly created background point locations (bgr_ouput). The SWD files contain for each location the values of the raster layers selected with the evp_maps parameter. With the parameter export_rasters you tell the addon to export the raster layers as well. 
v.maxent.swd -t \
 species=Bradypus_tridactylus \
 evp_maps=bio02,bio03@southamerica,bio08,bio09,bio13,bio15,bio17 \
 evp_cat=sa_eco_l2 \
 alias_cat=landuse \
 nbgp=10000 \
 bgr_output=bgrd_swd.csv \
 species_output=spec_swd.csv \
 export_rasters=envlayers

3) Train the model

Use the output of v.maxent.swd as input for rmaxent.train. First create a sub-folder output_model1. The outputs will be written to this folder.

The projectionlayers parameter is optional. When set, it produces a raster prediction layer that reflects the potential distribution based on the projection layers. This is primarily useful for model evaluation. I.e., you typically use it to generate a potential suitability map using the same conditions applied during model creation, which can then be compared to the observed distribution. For final predictions in future scenarios or different locations, use the r.maxent.prediction module.

With the -y and -b flags the point layers with the sample predictions and the predictions at the background point locations are created. Their values correspond to the values of the raster prediction layer. 

r.maxent.train -y -b \
  samplesfile=spec_swd.csv \
  environmentallayersfile=bgrd_swd.csv \
  togglelayertype=landuse \
  projectionlayers=envlayers \
  samplepredictions=model_1_samplepred \
  backgroundpredictions=model_1_bgrdpred \
  predictionlayer=model_1_suitability_current \
  outputdirectory=output_model1

When r.maxent.train is finished, go to the output folder and open the Bradypus_tridactylus.html file for an explanation of the different model outputs and model evaluation statistics. For a more detailed explanation, see the training manual on the Maxent website.

In your current mapset, you'll find the raster prediction layer, and the sample and background point layers with the predicted values.

Output layers in grass gis
The example creates the prediction raster layer 'model_1_suitability_current', the sample point layer 'model_1_samplepred' and the background point layer 'model_bgrdpred' (for the latter, ony part of the map is shown here).

You can use the addon r.maxent.predict to perform predictions based on future conditions or for a different area.

REFERENCES

SEE ALSO

See also

AUTHOR

Paulo van Breugel, https://ecodiv.earth

HAS green academy University of Applied Sciences
Innovative Biomonitoring research group
Climate-robust Landscapes research group

SOURCE CODE

Available at: r.maxent.train source code (history)

Latest change: Tuesday Nov 12 17:15:21 2024 in commit: 2070d84d70f7e77d166ff0bd805f470b921a0ac6

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2024 GRASS Development Team, GRASS GIS 8.5.0dev Reference Manual