perform_pca: Principal Component Analysis for raster layers

In kuenm2: Detailed Development of Ecological Niche Models

Principal Component Analysis for raster layers

Description

This function performs principal component analysis (PCA) with a set of raster variables.

Usage

perform_pca(raster_variables, exclude_from_pca = NULL, project = FALSE,
            projection_data = NULL, out_dir = NULL, overwrite = FALSE,
            progress_bar = FALSE, center = TRUE, scale = FALSE,
            variance_explained = 95, min_explained = 5)

Arguments

raster_variables	(SpatRaster) set of predictor variables that the function will summarize into a set of orthogonal, uncorrelated components based on PCA.
exclude_from_pca	(character) variable names within raster_variables that should not be included in the PCA transformation. Instead, these variables will be added directly to the final set of output variables without being modified. The default is NULL, meaning all variables will be used unless specified otherwise.
project	(logical) whether the function should project new data from different scenarios (e.g. future variables) onto the PCA coordinates generated by the initial analysis. If TRUE, the argument projection_data needs to be defined. Default is FALSE.
projection_data	an object of class prepared_projection returned by the prepare_projection() function. This file contains the paths to the raster files representing each scenario. Only applicable if project = TRUE. Default is NULL.
out_dir	(character) a path to a root directory for saving the raster files of each projection. Default = NULL.
overwrite	(logical) whether to overwrite SpatRaster if they already exists when projecting. Only applicable if write_files is set to TRUE. Default is FALSE.
progress_bar	(logical) whether to display a progress bar during processing projections. Only applicable if project = TRUE. Default is FALSE
center	(logical) whether the variables should be zero-centered. Default is TRUE.
scale	(logical) whether the variables should be scaled to have unit variance before the analysis takes place. Default is FALSE.
variance_explained	(numeric) the cumulative percentage of total variance that must be explained by the selected principal components. Default is 95.
min_explained	(numeric) the minimum percentage of total variance that a principal component must explain to be retained. Default is 5.

Value

A list containing the following elements:

• env: A SpatRaster object that contains the orthogonal components derived from the PCA. PCs correspond to the variables used to perform the analysis.

• pca: an object of class prcomp, containing the details of the PCA analysis. See prcomp().

• variance_explained_cum_sum: The cumulative percentage of total variance explained by each of the selected principal components. This value indicates how much of the data's original variability is captured by the PCA transformation.

• projection_directory: the root directory where projection files were saved. Not NULL only if project was set to TRUE. This directory contains the projected raster files for each scenario.

Examples

# PCA with current variables
# Import raster layers
var <- terra::rast(system.file("extdata", "Current_variables.tif",
                               package = "kuenm2"))

# PCA
pca_var <- perform_pca(raster_variables = var, exclude_from_pca = "SoilType",
                       center = TRUE, scale = TRUE)

pca_var

# Project PCA for new scenarios (future)
# First, organize and prepare future variables
# Set the input directory containing the raw future climate variables
# For this example, the data is located in the "inst/extdata" folder.
in_dir <- system.file("extdata", package = "kuenm2")

# Create a "Future_raw" folder in a temporary directory and copy the variables.
out_dir_future <- file.path(tempdir(), "Future_raw1")

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

# Prepare projections
pr <- prepare_projection(variable_names = c("bio_1", "bio_7", "bio_12",
                                            "bio_15", "SoilType"),
                         future_dir = out_dir_future,
                         future_period = c("2041-2060", "2081-2100"),
                         future_pscen = c("ssp126", "ssp585"),
                         future_gcm = c("ACCESS-CM2", "MIROC6"),
                         raster_pattern = ".tif*")

# Create folder to save projection results
out_dir <- file.path(tempdir(), "PCA_projections")
dir.create(out_dir, recursive = TRUE)

# Perform and project PCA for new scenarios (future)
proj_pca <- perform_pca(raster_variables = var, exclude_from_pca = "SoilType",
                        project = TRUE, projection_data = pr,
                        out_dir = out_dir, center = TRUE, scale = TRUE)

proj_pca$projection_directory  # Directory with projected PCA-variables

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