Skip to contents

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,
                       parallel = FALSE, ncores = NULL,
                       progress_bar = FALSE, progress_type = "timer",
                       use_lb = 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. Default is TRUE.

from_parameters

(logical) whether to compute the variance originating from model parameterizations. Default is TRUE.

from_gcms

(logical) whether to compute the variance originating from general circulation models (GCMs). Default is TRUE.

consensus

(character) the consensus measure to use for calculating variability across models and GCMs. Available options are 'median' and 'mean'. Default is 'median'.

write_files

(logical) whether to write the raster files containing the computed variance to disk. Default is FALSE.

output_dir

(character) the directory path where the resulting raster files containing the computed variance will be saved. Only relevant if write_files = TRUE. Default is NULL.

return_rasters

(logical) whether to return a list containing all the SpatRasters with the computed variance. Default is TRUE.

parallel

(logical) whether to compute variability across scenarios in parallel. Default is FALSE.

ncores

(numeric) number of cores to use for parallel processing. Default is NULL and uses available cores - 1. Only applicable if parallel = TRUE.

progress_bar

(logical) whether to display a progress bar during processing. Default is FALSE.

progress_type

(character) type of the progress bar. See pbapply::pbtypes() for available progress bar types depending on operating system. Default is "timer".

use_lb

(logical) whether to use load balancing when running in parallel. Default is FALSE.

verbose

(logical) whether to display messages during processing. Default is TRUE.

overwrite

(logical) whether to overwrite SpatRaster files if they already exist. Only applicable if write_files = 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, along with root_directory. If write_files = TRUE, the object can be used to import these files later with 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)
#> 
  |                                                  | 0 % ~calculating  
  |+++++++                                           | 12% ~00s          
  |+++++++++++++                                     | 25% ~00s          
  |+++++++++++++++++++                               | 38% ~00s          
  |+++++++++++++++++++++++++                         | 50% ~00s          
  |++++++++++++++++++++++++++++++++                  | 62% ~00s          
  |++++++++++++++++++++++++++++++++++++++            | 75% ~00s          
  |++++++++++++++++++++++++++++++++++++++++++++      | 88% ~00s          
  |++++++++++++++++++++++++++++++++++++++++++++++++++| 100% elapsed=00s  
#> 
#> Variables successfully organized in directory:
#> /tmp/RtmpANcSCA/Future_raw5

# 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)
#> 
  |                                                  | 0 % ~calculating  
  |+++++++++++++++++                                 | 33% ~01s          
  |++++++++++++++++++++++++++++++++++                | 67% ~00s          
  |++++++++++++++++++++++++++++++++++++++++++++++++++| 100% elapsed=01s  

# Step 5: Compute variance from distinct sources
v <- projection_variability(model_projections = p, from_replicates = FALSE)
#> Calculating variability from distinct models: scenario 1 of 2
#> Calculating variability from distinct models: scenario 2 of 2
#> Calculating variability from distinct GCMs: scenario 2 of 2

terra::plot(v$Present$from_parameters)  # From models with distinct parameters

terra::plot(v$`Future_2041-2060_ssp126`$from_parameters)  # From models

terra::plot(v$`Future_2041-2060_ssp126`$from_gcms)  # From GCMs