Saving and loading letsR objects

Overview

Objects generated by letsR, including PresenceAbsence objects and the outputs of functions such as lets.envpam() and lets.attrpam(), may contain spatial rasters stored as SpatRaster objects from the terra package. Because these objects may reference external data or memory resources, saving them directly using the base R save() function may not preserve their contents correctly.

To ensure reliable serialization, letsR provides two functions: lets.save() and lets.load(). These functions work similarly to the base R save() and load() functions, but automatically handle spatial raster components. All SpatRaster elements are prepared for serialization when saving and reconstructed when loading, preserving the original object structure.

Saving and loading a PresenceAbsence object

We first demonstrate how to save and load a geographic PresenceAbsence object using the example dataset included in letsR.

library(letsR)

# Load example data
data("PAM")

# Save the PresenceAbsence object
lets.save(PAM, file = "PAM.RData")

# Load the saved object
PAM <- lets.load("PAM.RData")

Saving and loading an environmental PAM

The same approach applies to objects generated by lets.envpam(), which contain presence-absence matrices in environmental and geographic spaces, together with their respective richness rasters.

We use the temperature and precipitation datasets included in letsR to construct an environmental PAM.

# Load environmental data
data("temp")
data("prec")

temp <- terra::unwrap(temp)
prec <- terra::unwrap(prec)

# Extract environmental variables for geographic cells
envs <- lets.addvar(
  PAM,
  c(temp, prec),
  onlyvar = TRUE
)

colnames(envs) <- c("Temperature", "Precipitation")

# Create environmental PAM
envpam <- lets.envpam(PAM, envs, n_bins = 30)

# Save the environmental PAM
lets.save(envpam, file = "envPAM.RData")

# Load the saved object
envpam <- lets.load("envPAM.RData")

Saving and loading an attribute PAM

Objects generated by lets.attrpam() can also be saved and loaded using the same functions. In this example, we simulate two correlated traits for 100 species and construct a presence-absence matrix in attribute space.

set.seed(123)

# Simulate species traits
n <- 100
Species <- paste0("sp", 1:n)
trait_a <- rnorm(n)
trait_b <- trait_a * 0.2 + rnorm(n)

traits <- data.frame(Species, trait_a, trait_b)

# Create attribute PAM
pam_att <- lets.attrpam(traits, n_bins = 10)

# Save the attribute PAM
lets.save(pam_att, file = "attrPAM.RData")

# Load the saved object
pam_att <- lets.load("attrPAM.RData")

Final considerations

The lets.save() and lets.load() functions automatically identify and handle SpatRaster components, regardless of their names or number. All other object components, including presence-absence matrices, species names, and attributes, are preserved.

This provides a consistent approach for storing and restoring letsR objects across geographic, environmental, and attribute spaces.