Skip to contents

Fetch per-species bioclim covariates from WorldClim v2.1

Source: R/worldclim_covariates.R
pull_worldclim_per_species.Rd

Extends pull_gbif_centroids by extracting 19 WorldClim v2.1 bioclim variables at each species' GBIF occurrence points, aggregating per species (median + IQR), and returning species-level summaries. For one row per species, select the numeric bio* columns for climate predictors and keep row names matching species names in the trait data and tree. For repeated observations, see preprocess_traits for observation-level covariate alignment. Species with no usable GBIF points can have missing climate values. This helper does not fill missing or non-finite climate values: preprocess_traits rejects covariates containing NA, Inf, or -Inf, so handle them before fitting. The species column is an identifier and n_extracted is a diagnostic, so do not include them as climate predictors.

Rasters are checked and loaded for the requested resolution; if its cache lacks the completion marker or any of the 19 raster files, the function attempts to download the stack. Per-species extracts are cached by species name, not resolution. When changing resolution, use a separate worldclim_cache_dir or set refresh_cache = TRUE to avoid reusing extracts made at another resolution. Refreshing extracts does not force raster downloads. If loading the stack fails, existing cached extracts can still be used; a new extraction at usable GBIF locations needs a readable raster stack.

Extraction uses the raw per-occurrence point list when the GBIF cache contains it (request it with store_points = TRUE in pull_gbif_centroids). A centroid-only cache falls back to the species centroid. Requesting points refetches a centroid-only GBIF cache, but an existing WorldClim extract remains cached until refresh_cache = TRUE is used here.

Requires the optional terra package (in DESCRIPTION Suggests). If terra is not installed the function errors with an installation message.

Usage

pull_worldclim_per_species(
  species,
  gbif_cache_dir,
  worldclim_cache_dir,
  resolution = "10m",
  verbose = TRUE,
  refresh_cache = FALSE
)

Arguments

species

Supply a non-empty character vector of unique species names. Do not include missing or empty names; names are used to create cache keys and output row names.

gbif_cache_dir

character path, GBIF per-species cache directory (as written by pull_gbif_centroids).

worldclim_cache_dir

character path, directory for WorldClim rasters + per-species extract cache. Created if absent.

resolution

one of "10m" (default), "5m", "2.5m".

verbose

logical. Print progress every 50 species.

refresh_cache

logical. Force re-extract even when per-species cache exists.

Value

A data.frame with length(species) rows and columns:

  • species

  • bio1_median, bio1_iqr, ..., bio19_median, bio19_iqr

  • n_extracted (integer, number of valid occurrence points that contributed)

Rownames are set to species. Species with no GBIF hits get all-NA bio values and n_extracted = 0.

References

Fick SE, Hijmans RJ (2017). WorldClim 2: new 1-km spatial resolution climate surfaces for global land areas. International Journal of Climatology 37, 4302–4315.

See also

pull_gbif_centroids (B.1, required input), impute (consume as covariates).

Examples

if (FALSE) { # interactive()
# With fresh caches, this example contacts GBIF and may download the 19
# global WorldClim rasters. It needs internet access and the optional
# rgbif and terra packages.
sp <- c("Quercus alba", "Pinus taeda", "Acer saccharum")
# Use temporary caches for this R session. Choose a persistent directory
# if you want to reuse downloaded data after R restarts.
cache_root <- file.path(tempdir(), "pigauto-worldclim-example")
gbif_cache <- file.path(cache_root, "gbif")
worldclim_cache <- file.path(cache_root, "worldclim")
# store_points = TRUE refetches centroid-only GBIF entries when needed.
gbif_df <- pull_gbif_centroids(sp,
  cache_dir = gbif_cache, store_points = TRUE)
# Refresh old climate extracts. Occurrence points are used when available;
# centroid-only GBIF cache entries fall back to the species centroid.
wc_df <- pull_worldclim_per_species(
  species = sp,
  gbif_cache_dir = gbif_cache,
  worldclim_cache_dir = worldclim_cache,
  refresh_cache = TRUE)
# For one row per species, select climate columns and align by species.
wc_cov <- wc_df[, grep("^bio", names(wc_df)), drop = FALSE]
rownames(wc_cov) <- wc_df$species
gbif_cov <- gbif_df[match(wc_df$species, gbif_df$species),
                    c("centroid_lat", "centroid_lon"), drop = FALSE]
rownames(gbif_cov) <- wc_df$species
cov <- cbind(gbif_cov, wc_cov)
# This helper does not fill missing values. Resolve NA/Inf/-Inf before
# passing cov to impute().
}