kuenm_ceval: Evaluation of candidate Maxent models during calibration

In manubio13/ku.enm: Detailed development of ecological niche models using Maxent

Evaluation of candidate Maxent models during calibration

Description

kuenm_ceval evaluates candidate models in terms of statistical significance (partial ROC), prediction ability (omission rates), and model complexity (AICc). After evaluation, this function selects the best models based on user-defined criteria.

Usage

kuenm_ceval(path, occ.joint, occ.tra, occ.test, batch, out.eval,
            threshold = 5, rand.percent = 50, iterations = 500,
            kept = TRUE, selection = "OR_AICc", parallel.proc = FALSE)

Arguments

path	(character) directory in which folders containig calibration models are being created or were created.
occ.joint	(character) the name of csv file with training and testing occurrences combined; columns must be: species, longitude, latitude.
occ.tra	(character) the name of the csv file with the training occurrences; columns as in occ.joint.
occ.test	(character) the name of the csv file with the evaluation occurrences; columns as in occ.joint.
batch	(character) name of the batch file (bash for Unix) with the code to create all candidate models for calibration.
out.eval	(character) name of the folder where evaluation results will be written.
threshold	(numeric) the percentage of training data omission error allowed (E); default = 5.
rand.percent	(numeric) the percentage of data to be used for the bootstraping process when calculating partial ROCs; default = 50.
iterations	(numeric) the number of times that the bootstrap is going to be repeated; default = 500.
kept	(logical) if FALSE, all candidate models will be erased after evaluation, default = TRUE.
selection	(character) model selection criterion, can be "OR_AICc", "AICc", or "OR"; OR = omission rates. Default = "OR_AICc", which means that among models that are statistically significant and that present omission rates below the threshold, those with delta AICc up to 2 will be selected. See details for other selection criteria.
parallel.proc	(logical) if TRUE, pROC calculations will be performed in parallel using the available cores of the computer. This will demand more RAM and almost full use of the CPU; hence, its use is more recommended in high-performance computers. Using this option will speed up the analyses only if models are large RasterLayers or if iterations are more than 5000. Default = FALSE.

Details

This function is used after or during the creation of Maxent candidate models for calibration.

Other selecton criteria are described below: If "AICc" criterion is chosen, all significant models with delta AICc up to 2 will be selected If "OR" is chosen, the 10 first significant models with the lowest omission rates will be selected.

Value

A list with three dataframes containing results from the calibration process and a scatterplot of all models based on the AICc values and omission rates. In addition, a folder, in the working directory, containing a csv file with information about models meeting the user-defined selection criterion, another csv file with a summary of the evaluation and selection process, an extra csv file containing all the statistics of model performance (pROC, AICc, and omission rates) for all candidate models, a png scatterplot of all models based on the AICc values and rates, and an HTML file sumarizing all the information produced after evaluation for helping with further interpretation.

Examples

# To run this function the kuenm_cal function needs te be used first. This previous function will
# create the models that kuenm_ceval evaluates.

# Variables with information to be used as arguments.
occ_joint <- "aame_joint.csv"
occ_tra <- "aame_train.csv"
batch_cal <- "Candidate_models"
out_dir <- "Candidate_Models"
occ_test <- "aame_test.csv"
out_eval <- "Calibration_results"
threshold <- 5
rand_percent <- 50
iterations <- 100
kept <- TRUE
selection <- "OR_AICc"
paral_proc <- FALSE # make this true to perform pROC calculations in parallel

cal_eval <- kuenm_ceval(path = out_dir, occ.joint = occ_joint, occ.tra = occ_tra, occ.test = occ_test, batch = batch_cal,
                        out.eval = out_eval, threshold = threshold, rand.percent = rand_percent, iterations = iterations,
                        kept = kept, selection = selection, parallel.proc = paral_proc)

manubio13/ku.enm documentation built on Jan. 5, 2024, 5:55 a.m.