projection_variability: Explores variance coming from distinct sources in model...

In kuenm2: Detailed Development of Ecological Niche Models

Explores variance coming from distinct sources in model predictions

Description

Calculates variance in model predictions, distinguishing between the different sources of variation. Potential sources include replicates, model parameterizations, and general circulation models (GCMs).

Usage

projection_variability(model_projections, from_replicates = TRUE,
                       from_parameters = TRUE, from_gcms = TRUE,
                       consensus = "median", write_files = FALSE,
                       output_dir = NULL, return_rasters = TRUE,
                       progress_bar = FALSE, verbose = TRUE,
                       overwrite = FALSE)

Arguments

model_projections	a model_projections object generated by the project_selected() function. This object contains the file paths to the raster projection results and the thresholds used for binarizing the predictions.
from_replicates	(logical) whether to compute the variance originating from replicates.
from_parameters	(logical) whether to compute the variance originating from model parameterizations.
from_gcms	(logical) whether to compute the variance originating from general circulation models (GCMs)
consensus	(character) (character) the consensus measure to use for calculating changes. Available options are 'mean', 'median', 'range', and 'stdev' (standard deviation). Default is 'median'.
write_files	(logical) whether to write the raster files containing the computed variance to the disk. Default is FALSE.
output_dir	(character) the directory path where the resulting raster files containing the computed changes will be saved. Only relevant if write_results = TRUE.
return_rasters	(logical) whether to return a list containing all the SpatRasters with the computed changes. Default is TRUE. Setting this argument to FALSE returns a NULL object.
progress_bar	(logical) whether to display a progress bar during processing. Default is TRUE.
verbose	(logical) whether to display messages during processing. Default is TRUE.
overwrite	whether to overwrite SpatRaster if they already exists. Only applicable if write_files is set to TRUE. Default is FALSE.

Value

An object of class variability_projections. If return_rasters = TRUE, the function returns a list containing the SpatRasters with the computed variances, categorized by replicate, model, and GCMs. If write_files = TRUE, it also returns the directory path where the computed rasters were saved to disk, and the object can then be used to import these files later with the import_results() function. If both return_rasters = FALSE and write_files = FALSE, the function returns NULL

See Also

organize_future_worldclim(), prepare_projection(), project_selected(), import_results()

Examples

# Step 1: Organize variables for current projection
## Import current variables (used to fit models)
var <- terra::rast(system.file("extdata", "Current_variables.tif",
                               package = "kuenm2"))

## Create a folder in a temporary directory to copy the variables
out_dir_current <- file.path(tempdir(), "Current_raw5")
dir.create(out_dir_current, recursive = TRUE)

## Save current variables in temporary directory
terra::writeRaster(var, file.path(out_dir_current, "Variables.tif"))


# Step 2: Organize future climate variables (example with WorldClim)
## Directory containing the downloaded future climate variables (example)
in_dir <- system.file("extdata", package = "kuenm2")

## Create a folder in a temporary directory to copy the future variables
out_dir_future <- file.path(tempdir(), "Future_raw5")

## Organize and rename the future climate data (structured by year and GCM)
### 'SoilType' will be appended as a static variable in each scenario
organize_future_worldclim(input_dir = in_dir, output_dir = out_dir_future,
                          name_format = "bio_", static_variables = var$SoilType)

# Step 3: Prepare data to run multiple projections
## An example with maxnet models
## Import example of fitted_models (output of fit_selected())
data(fitted_model_maxnet, package = "kuenm2")

## Prepare projection data using fitted models to check variables
pr <- prepare_projection(models = fitted_model_maxnet,
                         present_dir = out_dir_current,
                         future_dir = out_dir_future,
                         future_period = "2041-2060",
                         future_pscen = "ssp126",
                         future_gcm = c("ACCESS-CM2", "MIROC6"),
                         raster_pattern = ".tif*")

# Step 4: Run multiple model projections
## A folder to save projection results
out_dir <- file.path(tempdir(), "Projection_results/maxnet3")
dir.create(out_dir, recursive = TRUE)

## Project selected models to multiple scenarios
p <- project_selected(models = fitted_model_maxnet, projection_data = pr,
                      out_dir = out_dir)

# Step 5: Compute variance from distinct sources
v <- projection_variability(model_projections = p, from_replicates = FALSE)

#terra::plot(v$Present$from_replicates)  # Variance from replicates, present projection
terra::plot(v$Present$from_parameters)  # From models with distinct parameters
#terra::plot(v$`Future_2041-2060_ssp126`$from_replicates)  # From replicates in future projection
terra::plot(v$`Future_2041-2060_ssp126`$from_parameters)  # From models
terra::plot(v$`Future_2041-2060_ssp126`$from_gcms)  # From GCMs

kuenm2 documentation built on April 21, 2026, 1:07 a.m.