r.maxent.train: a new addon to train a model using Maxent (#1012)

* r.maxent.train: a new addon to train a model using Maxent

The addon, essentially a wrapper to the Maxent software, can be used for the training of a Maxent model. It complements the addons v.maxent.swd, r.out.maxent_swd and r.maxent.lambda. Together they allow one to carry out a good part of the model workflow, from data preparation to training to prediction. An additional addon to use the model outcome for predictions using alternative prediction layers, also using Maxent in the background, is in development.

Co-authored-by: Stefan Blumentrath <stefan.blumentrath@gmx.de>
Co-authored-by: Edouard Choinière <27212526+echoix@users.noreply.github.com>
Co-authored-by: Veronica Andreo <veroandreo@gmail.com>

src/raster/r.maxent.train/Makefile

@@ -0,0 +1,7 @@
+MODULE_TOPDIR = ../..
+
+PGM = r.maxent.train
+
+include $(MODULE_TOPDIR)/include/Make/Script.make
+
+default: script

src/raster/r.maxent.train/r.maxent.train.html

@@ -0,0 +1,236 @@
+<h2>DESCRIPTION</h2>
+
+With <em>r.maxent.train</em> a Maxent presence only model can be 
+created using the <em>Maxent software</em>. 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 <a 
+href="r.out.maxent_swd.html">r.out.maxent_swd</a> or <a 
+href="v.maxent.swd.html">v.maxent.swd</a> addons to create these files. 
+For more details about the structure of these files, see the <a 
+href="https://biodiversityinformatics.amnh.org/open_source/maxent/">Maxent 
+website</a>.
+
+<p>
+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. 
+
+<p>
+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 <em>v.maxent_swd</em> from the same mapset to create those 
+input environmental layers for Maxent. See the example workflow in 
+the Examples.
+
+<p>
+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.
+
+
+<h2>NOTES</h2>
+
+This addon requires the Maxent software. You can download the software 
+from the <a 
+href="https://biodiversityinformatics.amnh.org/open_source/maxent">Maxent 
+website</a>. The software includes a <em>Maxent.jar</em> file. The 
+first time you run the addon, you need to use the <b>maxent</b> 
+parameter to set the path to the Maxent.jar file. Set the <b>-i</b> 
+flag to copy the jar file to the addon/script directory. On subsequent 
+runs, you do not need to set the <b>maxent</b> parameter anymore.
+
+<p>
+If you want to update the Maxent.jar file, use the <b>-u</b> 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:
+
+<div class="code">
+<pre>echo 
+$GRASS_ADDON_BASE
+</pre>
+</div>
+
+<p>
+The <em>r.maxent.train</em> addon runs Maxent in the background. If 
+you want to check the Maxent settings first, you can set the 
+<em>-v</em> flag to open the Maxent user interface with all parameters 
+filled in. You will need to hit the <i>Run</i> button to actually run 
+Maxent.
+
+<p>
+Besides the files directly generated by <i>Maxent</i>, the addon 
+creates the <i>maxent_explanatory_variable_names.csv</i> 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 <em>r.maxent.predict</em>.
+
+
+<h2>Examples</h2>
+
+<h3>1) Sample dataset</h3>
+
+The examples below use a dataset that you can download <a 
+href="https://ecodiv.earth/share/reader_SDM/grassmaxent_sampledata.zip">from 
+here</a>. It includes <a href="">vector point layer</a> with 
+observation locations of the pale-throated sloth (<i>Bradypus 
+tridactylus</i>) from <a 
+href="https://doi.org/10.15468/dl.br8b4a">GBIF</a>, a number of bioclim 
+raster layers from <a 
+href="https://www.worldclim.org/data/worldclim21.html">WorldClim</a>, 
+the <a href="https://www.iucnredlist.org/species/3037/210442660">IUCN 
+RedList range map</a> of the species, and a boundary layer of the South 
+American countries from  <a 
+href="https://www.naturalearthdata.com/downloads/50m-cultural-vectors/">NaturalEarth</a>. 
+
+<p>
+The zip file contains a folder <i>sampledata</i>. This is a location 
+with two subfolders <i>PERMANENT</i> and <i>southamerica</i>. If you 
+are not familiar with the concept of <i>Locations</i> and 
+<i>Mapsets</i>, please first read the <a 
+href="https://grass.osgeo.org/grass83/manuals/grass_database.html">explanation</a> 
+about the GRASS GIS database.
+
+<p>
+Unzip the file, start up GRASS GIS, open the GRASS GIS database to 
+which you copied the folder <i>sampledata</i>, switch to the Location 
+<i>sampledata</i> and then open the mapset <i>southamerica</i>. 
+
+<h3>2) Preparing input data</h3>
+
+You can use the <em>v.maxent.swd</em> to create the required input 
+layers. The code below creates the SWD file with the locations where 
+the species has been recorded (<b>species_output</b>) and a SWD file 
+with randomly created background point locations (<b>bgr_ouput</b>). The 
+SWD files contain for each location the values of the raster layers 
+selected with the <b>evp_maps</b> parameter. With the parameter 
+<b>export_rasters</b> you tell the addon to export the raster layers as 
+well.
+
+<div class="code">
+<pre>
+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
+</pre>
+</div>
+
+<h3>3) Train the model</h3>
+
+Use the output of <em>v.maxent.swd</em> as input for 
+<em>rmaxent.train</em>. First create a sub-folder <i>output_model1</i>. 
+The outputs will be written to this folder.
+
+<p>
+The <b>projectionlayers</b> 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).
+
+<p>
+With the <b>-y</b> and <b>-b</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.
+
+<div class="code">
+<pre>
+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
+</pre>
+</div>
+
+<p>
+When <em>r.maxent.train</em> is finished, go to the output folder and 
+open the <i>Bradypus_tridactylus.html</i> file for an explanation of 
+the different model outputs and model evaluation statistics. For a more 
+detailed explanation, see the training manual on the <a 
+href="https://biodiversityinformatics.amnh.org/open_source/maxent/">Maxent 
+website</a>.
+
+<p>
+In your current mapset, you'll find the raster prediction layer, and 
+the sample and background point layers with the predicted values. 
+
+<p>
+<div align="left" style="margin: 10px"> <a href="r_maxent_train.png"> 
+<img src="r_maxent_train.png" alt="Output layers in grass gis" 
+border="0"> </a><br><i>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).</i> </div>
+
+
+<p>
+You can use the addon <em>r.maxent.predict</em> to perform predictions 
+based on future conditions or for a different area.
+
+<h2>REFERENCES</h2>
+
+<ul>
+<li>Steven J. Phillips, Miroslav Dud&iacute;k, Robert E. Schapire. 
+2020: Maxent software for modeling species niches and distributions 
+(Version 3.4.1). Available from url: <a 
+href="https://biodiversityinformatics.amnh.org/open_source/maxent"> 
+https://biodiversityinformatics.amnh.org/open_source/maxent</a> and <a 
+href="https://github.com/mrmaxent/Maxent">https://github.com/mrmaxent/Maxent</a></li>
+<li>Steven J. Phillips, Miroslav Dud&iacute;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.</li>
+<li>Steven J. Phillips, Robert P. Anderson, Robert E. Schapire. 2006: 
+Maximum entropy modeling of species geographic distributions. 
+Ecological Modelling, 190:231-259, 2006.</li>
+<li>Jane Elith, Steven J. Phillips, Trevor Hastie, Miroslav 
+Dud&iacute;k, Yung En Chee, Colin J. Yates. 2011: A statistical 
+explanation of MaxEnt for ecologists. Diversity and Distributions, 
+17:43-57, 2011.</li>
+</ul>
+
+
+<h2>SEE ALSO</h2>
+
+See also 
+
+<ul>
+<li><a href="v.maxent.swd.html">v.maxent.swd</a>, creating species and 
+background swd files and prediction rasters that can be used directly 
+by the <em>r.maxent.train</em> addon (or the Maxent software itself) to 
+create species distribution models.</li>
+<li><a href="r.out.maxent_swd.html">r.out.maxent_swd</a>, creating 
+species and background swd files based on species distribution data in 
+raster format.</li>
+<li><a href="r.maxent.predict.html">r.maxent.predict</a>, creating a 
+suitability layer based on a set of environmental layers and a Maxent 
+model, e.g., created using the r.maxent.train addon.</li>
+</ul>
+
+<h2>AUTHOR</h2>
+
+Paulo van Breugel, <a href="https://ecodiv.earth">https://ecodiv.earth</a><br>
+
+<p>
+HAS green academy University of Applied Sciences<br>
+<a 
+href="https://www.has.nl/en/research/professorships/innovative-bio-monitoring-professorship/">Innovative 
+Biomonitoring research group</a><br>
+<a 
+href="https://www.has.nl/en/research/professorships/climate-robust-landscapes-professorship/">Climate-robust 
+Landscapes research group</a>