r.maxent.train - GRASS GIS manual

Note: This document is for an older version of GRASS GIS that will be discontinued soon. You should upgrade, and read the current manual page.

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] [--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 an alternate set of environmental variables.; Location of an alternate set of environmental variables. Maxent models will be projected onto these variables. The result will be imported in grass gis.
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

DESCRIPTION
NOTES
Examples
REFERENCES
SEE ALSO
AUTHOR

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 optionally. If you set it, a raster prediction layer will be created that represent the potential suitability distribution under current conditions (the conditions used to train the model).

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.

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

Steven J. Phillips, Miroslav Dudík, Robert E. Schapire. 2020: Maxent software for modeling species niches and distributions (Version 3.4.1). Available from url: https://biodiversityinformatics.amnh.org/open_source/maxent and https://github.com/mrmaxent/Maxent
Steven J. Phillips, Miroslav Dudík, Robert E. Schapire. 2004: A maximum entropy approach to species distribution modeling. In Proceedings of the Twenty-First International Conference on Machine Learning, pages 655-662, 2004.
Steven J. Phillips, Robert P. Anderson, Robert E. Schapire. 2006: Maximum entropy modeling of species geographic distributions. Ecological Modelling, 190:231-259, 2006.
Jane Elith, Steven J. Phillips, Trevor Hastie, Miroslav Dudík, Yung En Chee, Colin J. Yates. 2011: A statistical explanation of MaxEnt for ecologists. Diversity and Distributions, 17:43-57, 2011.

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: Monday Jun 24 15:24:04 2024 in commit: ed8af2507854cdbc4ca37087dd43927d6329c0d4