Title:	Ecological Niche Modeling using Presence-Absence Data
Version:	0.2.1
Maintainer:	Luis F. Arias-Giraldo <lfarias.giraldo@gmail.com>
Date:	2025-06-12
Description:	A set of tools to perform Ecological Niche Modeling with presence-absence data. It includes algorithms for data partitioning, model fitting, calibration, evaluation, selection, and prediction. Other functions help to explore signals of ecological niche using univariate and multivariate analyses, and model features such as variable response curves and variable importance. Unique characteristics of this package are the ability to exclude models with concave quadratic responses, and the option to clamp model predictions to specific variables. These tools are implemented following principles proposed in Cobos et al., (2022) <doi:10.17161/bi.v17i.15985>, Cobos et al., (2019) <doi:10.7717/peerj.6281>, and Peterson et al., (2008) <doi:10.1016/j.ecolmodel.2007.11.008>.
License:	GPL (≥ 3)
Encoding:	UTF-8
RoxygenNote:	7.3.2
URL:	https://github.com/Luisagi/enmpa
BugReports:	https://github.com/Luisagi/enmpa/issues
Imports:	doSNOW, ellipse, foreach, graphics, methods, mgcv, parallel, Rcpp, snow, stats, terra, utils, vegan
LazyData:	true
Depends:	R (≥ 3.5.0)
LinkingTo:	Rcpp
NeedsCompilation:	yes
Packaged:	2025-06-12 21:13:24 UTC; luisagi
Author:	Luis F. Arias-Giraldo [aut, cre], Marlon E. Cobos [aut], A. Townsend Peterson [ctb]
Repository:	CRAN
Date/Publication:	2025-06-12 21:30:02 UTC

enmpa: Ecological Niche Modeling using Presence-Absence Data

Description

enmpa contains a set of tools to perform detailed Ecological Niche Modeling using presence-absence data.

Details

It includes algorithms for data partitioning, model fitting, calibration, evaluation, selection, and prediction. Other functions help to explore model features as such variable response curves and variable importance.

Main functions in enmpa

calibration_glm, evaluation_stats, fit_glms, fit_selected, get_formulas, independent_eval1, kfold_partition, model_selection model_validation, niche_signal, optimize_metrics, predict_glm, predict_selected, response_curve, resp2var, var_importance, jackknife, plot_jk

Author(s)

Maintainer: Luis F. Arias-Giraldo lfarias.giraldo@gmail.com (ORCID)

Authors:

• Marlon E. Cobos manubio13@gmail.com (ORCID)

Other contributors:

• A. Townsend Peterson town@ku.edu (ORCID) [contributor]

See Also

Useful links:

• https://github.com/Luisagi/enmpa

• Report bugs at https://github.com/Luisagi/enmpa/issues

Example of results obtained from GLM calibration using enmpa

Description

An object of the class enmpa_calibration storing the results from GLM calibration.

Usage

cal_res

Format

An object of class enmpa_calibration with results from the function ⁠\link{calibration_glm}⁠.

Examples

data("cal_res", package = "enmpa")

str(cal_res)

GLM calibration with presence-absence data

Description

Creates candidate models based on distinct parameter settings, evaluates models, and selects the ones that perform the best.

Usage

calibration_glm(data, dependent, independent, weights = NULL,
                response_type = "l", formula_mode = "moderate",
                minvar = 1, maxvar = NULL, user_formulas = NULL,
                cv_kfolds = 5, partition_index = NULL, seed = 1,
                n_threshold = 100, selection_criterion = "TSS",
                exclude_bimodal = FALSE, tolerance = 0.01,
                out_dir = NULL, parallel = FALSE,
                n_cores = NULL, verbose = TRUE)

Arguments

Details

Model evaluation is done considering the ability to predict presences and absences,as well as model fitting and complexity. Model selection consists of three steps: 1) a first filter to keep the models with ROC AUC >= 0.5 (statistically significant models), 2) a second filter to maintain only models that meet the selection_criterion ("TSS": TSS >= 0.4; or "ESS": maximum Accuracy - tolerance), and 3) from those, pick the ones with delta AIC <= 2.

formula_mode options determine what strategy to iterate the predictors defined in type for creating models:

• light.– returns simple iterations of complex formulas.

• moderate.– returns a comprehensive number of iterations.

• intensive.– returns all possible combination. Very time-consuming for 6 or more independent variables.

• complex.– returns only the most complex formula.

Value

An object of the class enmpa_calibration containing: selected models, a summary of statistics for all models, results obtained in cross-validation for all models, original data used, weights, and data-partition indices used.

Examples

# Load species occurrences and environmental data.
data("enm_data", package = "enmpa")
head(enm_data)

# Calibration using linear (l), quadratic (q), products(p) responses.
cal_res <- calibration_glm(data = enm_data, dependent = "Sp",
                           independent = c("bio_1", "bio_12"),
                           response_type = "lpq", formula_mode = "moderate",
                           selection_criterion = "TSS", cv_kfolds = 3,
                           exclude_bimodal = TRUE, verbose = FALSE)
print(cal_res)
summary(cal_res)

head(cal_res$calibration_results)
head(cal_res$summary)
head(cal_res$selected)
head(cal_res$data)

Example data used to run model calibration exercises

Description

A dataset containing information on presence and absence, and independent variables used to fit GLM models.

Usage

enm_data

Format

A data frame with 5627 rows and 3 columns.

Sp

numeric, values of 0 = absence and 1 = presence.

bio_1

numeric, temperature values.

bio_12

numeric, precipitation values.

Examples

data("enm_data", package = "enmpa")
head(enm_data)

Constructor of S3 objects of class enmpa_calibration

Description

Constructor of S3 objects of class enmpa_calibration

Usage

new_enmpa_calibration(selected, summary, calibration_results, data,
                      partitioned_data, weights = NULL)

Arguments

Value

An S3 object of class enmpa_calibration.

Constructor of S3 objects of class enmpa_fitted_models

Description

Constructor of S3 objects of class enmpa_fitted_models

Usage

new_enmpa_fitted_models(glms_fitted, selected, data, weights = NULL)

Arguments

Value

An S3 object of class enmpa_fitted_models.

Summary of evaluation statistics for candidate models

Description

Calculate median and standard deviation of evaluation results for all candidate models considering cross-validation kfolds.

Usage

evaluation_stats(evaluation_results, bimodal_toexclude = FALSE)

Arguments

Value

A data.frame with the mean and standard deviation for all metrics considering cross-validation kfolds.

Examples

# data
data("cal_res", package = "enmpa")
all_res <- cal_res$calibration_results[, -1]

# statistics for all evaluation results
evaluation_stats(all_res, bimodal_toexclude = TRUE)

Fitting selected GLMs models

Description

Functions to facilitate fitting multiple GLMs.

Usage

fit_selected(glm_calibration)

fit_glms(formulas, data, weights = NULL, id = NULL)

Arguments

Value

A list of fitted GLMs.

For fit_selected, an enmpa ⁠fitted models⁠ object.

Examples

# GLM calibration results
data(cal_res, package = "enmpa")

# Fitting selected models
sel_fit <- fit_selected(cal_res)

sel_fit

# Custom formulas
forms <- c("Sp ~ bio_1 + I(bio_1^2) + I(bio_12^2)",
           "Sp ~ bio_12 + I(bio_1^2) + I(bio_12^2)")

# Fitting models
fits <- fit_glms(forms, data = cal_res$data)

fits$ModelID_1

Get GLM formulas according to defined response types

Description

Generate GLM formulas for independent variables predicting a dependent variable, taking into account response types required. All possible combinations of variables can be created using arguments of the function.

Usage

get_formulas(dependent, independent, type = "l", mode = "moderate",
             minvar = 1, maxvar = NULL)

get_formulas_main(dependent, independent, type = "l",
                  complex = FALSE, minvar = 1, maxvar = NULL)

aux_var_comb(var_names, minvar = 2, maxvar = NULL)

aux_string_comb(string)

Arguments

Details

mode options determine what strategy to iterate the predictors defined in type for creating models:

• light.– returns simple iterations of complex formulas.

• moderate.– returns a comprehensive number of iterations.

• intensive.– returns all possible combination. Very time-consuming for 6 or more independent variables.

• complex.– returns only the most complex formula.

Value

A character vector containing the resulting formula(s).

Examples

# example variables
dep <- "sp"
ind <- c("temp", "rain", "slope")

# The most complex formula according to "type"
get_formulas(dep, ind, type = "lqp", mode = "complex")

# mode = 'light', combinations according to type
get_formulas(dep, ind, type = "lqp", mode = "light")

# mode = 'light', combinations according to type
get_formulas(dep, ind, type = "lqp", mode = "intensive")

Evaluate final models using independent data

Description

Final evaluation steps for model predictions using an independent dataset (not used in model calibration).

Usage

independent_eval1(prediction, threshold, test_prediction = NULL,
                  lon_lat = NULL)

independent_eval01(prediction, observation, lon_lat = NULL)

Arguments

Value

A data.frame or list containing evaluation results.

Examples

# Independent test data based on coordinates (lon/lat WGS 84) from presence
# and absences records
data("test", package = "enmpa")
head(test)

# Loading a model prediction
pred <- terra::rast(system.file("extdata", "proj_out_wmean.tif",
                                package = "enmpa"))
terra::plot(pred)

# Evaluation using presence-absence data
independent_eval01(prediction = pred, observation = test$Sp,
                   lon_lat = test[, 2:3])

# Evaluation using presence-only data
test_p_only <- test[test$Sp == 1, ]
th_maxTSS   <- 0.1274123            # threshold based on the maxTSS

independent_eval1(prediction = pred, threshold = th_maxTSS,
                  lon_lat = test_p_only[, 2:3])

Jackkniffe test for variable contribution

Description

The Jackknife function providing a detailed reflection of the impact of each variable on the overall model, considering four difference measures: ROC-AUC, TSS, AICc, and Deviance.

Usage

jackknife(data, dependent, independent, user_formula = NULL, cv = 3,
          response_type = "l", weights = NULL)

Arguments

Value

list including model performance metrics (ROC-AUC, TSS, AICc, and deviance) for the complete model, model performance when excluding a specific predictor, and the independent contribution of that predictor to the model.

Examples

# Load data
data("enm_data", package = "enmpa")

jk <- jackknife(data = enm_data,
                dependent = "Sp",
                independent = c("bio_1", "bio_12"),
                user_formula = NULL,
                cv = 3, response_type = "lpq")
jk

# plot JK's results
plot_jk(jk, metric = "TSS")
plot_jk(jk, metric = "ROC_AUC")
plot_jk(jk, metric = "AIC")
plot_jk(jk, metric = "Residual_deviance")

K-fold data partitioning

Description

Creates indices to partition available data into k equal-sized subsets or folds, maintaining the global proportion of presence-absences in each fold.

Usage

kfold_partition(data, dependent, k = 2, seed = 1)

Arguments

Value

A list of vectors with the indices of rows corresponding to each fold.

Examples

# example data
data <- data.frame(species = c(rep(0, 80), rep (1,20)),
                   variable1 = rnorm(100),
                   variable2 = rpois(100, 2))

# create partition indices
kfolds <- kfold_partition(data, dependent = "species", k = 2)

# data for partition 1
data[kfolds$Fold_1, ]

Selection of best candidate models considering various criteria

Description

Applies a series of criteria to select best candidate models.

Usage

model_selection(evaluation_stats, criterion = "TSS", exclude_bimodal = FALSE,
                tolerance = 0.01)

Arguments

Value

A data.frame with one or more selected models.

Examples

# data
data("cal_res", package = "enmpa")
eval_stats <- cal_res$summary[, -1]

# selecting best model
selected_mod <- model_selection(eval_stats, exclude_bimodal = TRUE)

Model validation options

Description

Model evaluation using entire set of data and a k-fold cross validation approach. Models are assessed based on discrimination power (ROC-AUC), classification ability (accuracy, sensitivity, specificity, TSS, etc.), and the balance between fitting and complexity (AIC).

Usage

model_validation(formula, data, family = binomial(link = "logit"),
                 weights = NULL, cv = FALSE, partition_index = NULL,
                 k = NULL, dependent = NULL, n_threshold = 100,
                 keep_coefficients = FALSE, seed = 1)

Arguments

Value

A data.frame with results from evaluation.

Examples

# Load species occurrences and environmental data.
data("enm_data", package = "enmpa")
head(enm_data)

# Custom formula
form <- c("Sp ~ bio_1 + I(bio_1^2) + I(bio_12^2)")

# Model evaluation using the entire set of records
model_validation(form, data = enm_data)

# Model evaluation using a k-fold cross-validation (k = 3)
model_validation(form, data = enm_data, cv = TRUE, k = 3, dependent = "Sp")

Niche Signal detection using one or multiple variables

Description

Identifies whether a signal of niche can be detected using one or multiple variables. This is an implementation of the methods developed by Cobos & Peterson (2022) doi:10.17161/bi.v17i.15985 that focuses on identifying niche signals in presence-absence data.

Usage

niche_signal(data, condition, variables, method = "univariate",
             permanova_method = "mahalanobis", iterations = 1000,
             set_seed = 1, verbose = TRUE, ...)

niche_signal_univariate(data, condition, variable, iterations = 1000,
                        set_seed = 1, verbose = TRUE)

niche_signal_permanova(data, condition, variables, permutations = 999,
                       permanova_method = "mahalanobis", verbose = TRUE, ...)

Arguments

Value

A list with results from analysis depending on method.

Examples

# Load species occurrences and environmental data.
data("enm_data", package = "enmpa")
head(enm_data)

# Detection of niche signal using an univariate non-parametric test
sn_bio1 <- niche_signal(data = enm_data, variables = "bio_1",
                        condition = "Sp", method = "univariate")
sn_bio1

sn_bio12 <- niche_signal(data = enm_data, variables = "bio_12",
                         condition = "Sp", method = "univariate")
sn_bio12

Find threshold values to produce three optimal metrics

Description

The metrics true skill statistic (TSS), sensitivity, specificity are explored by comparing actual vs predicted values to find threshold values that produce sensitivity = specificity, maximum TSS, and a sensitivity value of 0.9.

Usage

optimize_metrics(actual, predicted, n_threshold = 100)

Arguments

Value

A list containing a data.frame with the resulting metrics for all threshold values tested, and a second data.frame with the results for the threshold values that produce sensitivity = specificity (ESS), maximum TSS (maxTSS), and a sensitivity value of 0.9 (SEN90).

Examples

# example data
act <- c(rep(1, 20), rep(0, 80))
pred <- c(runif(20, min = 0.4, max = 0.7), runif(80, min = 0, max = 0.5))

# run example
om <- optimize_metrics(actual = act, predicted = pred)
om$optimized

Plot variable importance

Description

Visualization of the results obtained with the function var_importance.

Usage

plot_importance(x, xlab = NULL, ylab = "Relative contribution",
                main = "Variable importance", extra_info = TRUE, ...)

Arguments

Value

A plot

Examples

# Load species occurrences and environmental data.
data("enm_data", package = "enmpa")

# Custom formulas
forms <- c("Sp ~ bio_1 + I(bio_1^2) + I(bio_12^2)",
           "Sp ~ bio_12 + I(bio_1^2) + I(bio_12^2)")

# Fitting models
fits <- fit_glms(forms, data = enm_data)

# Variable importance for single models
vi_1 <- var_importance(fits$ModelID_1)
plot_importance(x = vi_1)

vi_2 <- var_importance(fits$ModelID_2)
plot_importance(x = vi_2)

# Variable importance for multiple models
vi_c <- var_importance(fits)
plot_importance(x = vi_c)

Jackkniffe plot for variable contribution

Description

The jackknife figure shows the impact of each variable on the full model, providing detailed information about the function and significance of each variable. Light blue indicates the impact on the model if the variable is not included, while dark blue indicates the independent contribution of the variable to the model.

Usage

plot_jk(x, metric = "ROC_AUC", legend = TRUE,
        colors = c("cyan", "blue", "red"),
        xlab = NULL, main = NULL)

Arguments

Plot Niche Signal results

Description

Plots to interpret results from niche_signal tests (Cobos & Peterson (2022) doi:10.17161/bi.v17i.15985).

Usage

plot_niche_signal(niche_signal_list, statistic = "mean",
                  variables = NULL, ellipses = FALSE, level = 0.99,
                  breaks = "Sturges", main = "", xlab = NULL, ylab = NULL,
                  h_col = "lightgray", h_cex = 0.8, lty = 2, lwd = 1,
                  l_col = c("blue", "black"), e_col = c("black", "red"),
                  pch = 19, pt_cex = c(1.3, 0.8), pt_col = c("black", "red"),
                  ...)

plot_niche_signal_univariate(niche_signal_univariate_list, statistic = "mean",
                             breaks = "Sturges", main = "", xlab = NULL,
                             ylab = "Frequency", h_col = "lightgray",
                             h_cex = 0.8, lty = 2, lwd = 1,
                             l_col = c("blue", "black"), ...)

plot_niche_signal_permanova(niche_signal_permanova_list, variables = NULL,
                           ellipses = FALSE, level = 0.99, main = "",
                           xlab = NULL, ylab = NULL,
                           e_col = c("black", "red"), lty = 2, lwd = 1,
                           pch = 19, pt_cex = c(1.3, 0.8),
                           pt_col = c("black", "red"), ...)

Arguments

Value

A plot.

Examples

# Load species occurrences and environmental data.
data("enm_data", package = "enmpa")
head(enm_data)

# Detection of niche signal using an univariate non-parametric test
sn_bio1 <- niche_signal(data = enm_data,
                        variables = "bio_1",
                        condition = "Sp",
                        method = "univariate")

plot_niche_signal(sn_bio1, variables = "bio_1")

sn_bio12 <- niche_signal(data = enm_data,
                         variables = "bio_12",
                         condition = "Sp",
                         method = "univariate")

plot_niche_signal(sn_bio12, variables = "bio_12")

Extension of glm predict to generate predictions of different types

Description

Obtains predictions from a fitted generalized linear model objects. It also allows the clamping option to restrict extrapolation in areas outside the calibration area.

Usage

predict_glm(
  model,
  newdata,
  data = NULL,
  extrapolation_type = "E",
  restricted_vars = NULL,
  type = "response"
)

Arguments

Value

A SpatRaster object or a vector with predictions.

Examples

# Load fitted model
data("sel_fit", package = "enmpa")

# Load raster layers to be projected
env_vars <- terra::rast(system.file("extdata", "vars.tif", package = "enmpa"))

# Prediction
pred <- predict_glm(sel_fit$glms_fitted$ModelID_7, newdata = env_vars,
                    data = sel_fit$data)
terra::plot(pred)

Predictions for the models selected after calibration

Description

Wrapper function that facilitates the prediction of those models selected as the most robust. In addition, it allows the calculation of consensus models, when more than one model are selected.

Usage

predict_selected(fitted, newdata, extrapolation_type = "E",
                 restricted_vars = NULL, type = "response", consensus = TRUE)

Arguments

Value

A list with predictions of selected models on the newdata and fitted selected model(s). Consensus predictions are added if multiple selected models exits and if newdata is a SpatRaster object.

Examples

# Load a fitted selected model
data(sel_fit, package = "enmpa")

# Load raster layers to be projected
env_vars <- terra::rast(system.file("extdata", "vars.tif", package = "enmpa"))

# Predictions (only one selected mode, no consensus required)
preds <- predict_selected(sel_fit, newdata = env_vars, consensus = FALSE)

# Plot prediction
terra::plot(preds$predictions)

Print a short version of elements in 'calibration' and 'fitted models' objects

Description

Print a short version of elements in 'calibration' and 'fitted models' objects

Usage

## S3 method for class 'enmpa_calibration'
print(x, ...)

## S3 method for class 'enmpa_fitted_models'
print(x, ...)

Arguments

Partial ROC calculation

Description

proc applies partial ROC tests to model predictions.

Usage

proc_enm(test_prediction, prediction, threshold = 5, sample_percentage = 50,
         iterations = 500)

Arguments

Details

Partial ROC is calculated following Peterson et al. (2008) doi:10.1016/j.ecolmodel.2007.11.008.

Value

A list with the summary of the results and a data.frame containing the AUC values and AUC ratios calculated for all iterations.

Examples

# Loading a model prediction
pred <- terra::rast(system.file("extdata", "proj_out_wmean.tif",
                                package = "enmpa"))

# Simulated data
test <- runif(100, min = 0.3, max = 0.8)

# partial ROC calculation
pr <- proc_enm(test, pred, threshold = 5, sample_percentage = 50,
               iterations = 500)

Two-Way interaction response plot

Description

A view of the species probability into a two-dimensional environmental space.

Usage

resp2var(model, variable1 , variable2, modelID = NULL, data = NULL, n = 1000,
         new_data = NULL, extrapolate = FALSE, add_bar = TRUE,
         add_limits = FALSE, color.palette	= NULL, xlab = NULL, ylab = NULL,
         ...)

Arguments

Details

The function calculates probabilities by focusing on each combination of the two supplied environmental variable while keeping all other variables constant at their mean values.

Value

A plot with the response interaction of two environmental dimensions for variable1 and variable2, and don't return anything.

Examples

# Load a fitted selected model
data(sel_fit, package = "enmpa")

# Two-Way interaction response plot in the calibration limits

resp2var(sel_fit, variable1 = "bio_1", variable2 = "bio_12", xlab = "BIO-1",
ylab = "BIO-12", modelID = "ModelID_7")

# Two-Way interaction response plot allowing extrapolation
resp2var(sel_fit, variable1 = "bio_1", variable2 = "bio_12", xlab = "BIO-1",
ylab = "BIO-12", modelID = "ModelID_7", extrapolate = TRUE)

Variable response curves for GLMs

Description

A view of variable responses in models. Responses based on single or multiple models can be provided.

Usage

response_curve(fitted, variable, data = NULL, modelID = NULL,  n = 100,
               new_data = NULL,  extrapolate = TRUE, xlab = NULL,
               ylab = "Probability", col = "red", ...)

Arguments

Details

The function calculates these probabilities by focusing on a single environmental variable while keeping all other variables constant at their mean values.

When responses for multiple models are to be plotted, the mean and confidence intervals for the set of responses are calculated using a GAM.

Value

A plot with the response curve for a variable.

Examples

# Load a fitted selected model
data(sel_fit, package = "enmpa")

# Response curve for single models
response_curve(sel_fit$ModelID_7, variable = "bio_1")

# Response curve when model(s) are in a list (only one model in this one)
response_curve(sel_fit, variable = "bio_12")

Example of selected models fitted

Description

An object of the class enmpa_fitted_models containing fitted selected model(s) and the information from model evaluation for such model(s).

Usage

sel_fit

Format

A list with four elements.

glms_fitted

a fitted glm (ModelID_7).

selected

a data.frame with results from evaluation of ModelID_7

data

a data.frame containing information on presence and absence, and independent variables used to fit GLM models.

weights

a vector with the weights for observations.

Examples

data("sel_fit", package = "enmpa")

Summary of 'calibration' and 'fitted models'

Description

Summary of 'calibration' and 'fitted models'

Usage

## S3 method for class 'enmpa_calibration'
summary(object, ...)

## S3 method for class 'enmpa_fitted_models'
summary(object, ...)

Arguments

Value

A printed summary.

Example data used to test models

Description

A dataset containing information on presence and absence, and independent variables used to fit GLM models.

Usage

test

Format

A data frame with 100 rows and 3 columns.

Sp

numeric, values of 0 = absence and 1 = presence.

lon

numeric, longitude values.

lat

numeric, latitude values.

Examples

data("test", package = "enmpa")
head(test)

Variable importance for GLMs

Description

Calculates the relative importance of predictor variables based on the concept of explained deviance. This is achieved by fitting a GLMs multiple times, each time leaving out a different predictor variable to observe its impact on the model's performance.

Usage

var_importance(fitted, modelID = NULL, data = NULL)

Arguments

Details

The process begins by fitting the full GLM model, which includes all predictor variables. Subsequently, separate GLM models are fitted, excluding one variable at a time to assess the influence of its absence on the model's performance. By systematically evaluating the effect of removing each predictor variable, the function provides valuable insights into their individual contributions to the model's overall performance and explanatory power.

Value

A data.frame containing the relative contribution of each variable. An identification for distinct models is added if fitted contains multiple models.

Examples

# Load a fitted selected model
data(sel_fit, package = "enmpa")

# Variable importance for single models
var_importance(sel_fit, modelID = "ModelID_7")

# Variable importance for multiple models (only one model in this list)
var_importance(sel_fit)