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 a data.frame ready for impute via its covariates argument.

On first call, downloads the WorldClim 10-arc-minute raster stack (~130 MB compressed, ~500 MB unzipped) to worldclim_cache_dir. A sentinel file makes subsequent calls fully offline.

Per-species extracts are also cached (one RDS per species in worldclim_cache_dir/extracts/), so repeated calls for the same species list are instantaneous.

Since v0.9.1.9006 (2026-04-30) extraction operates on the raw per-occurrence point list when pull_gbif_centroids was called with store_points = TRUE. For legacy caches written by older pull_gbif_centroids (centroid-only) calls, extraction silently falls back to the species centroid.

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

character vector of species binomials.

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) { # \dontrun{
sp <- c("Quercus alba", "Pinus taeda", "Acer saccharum")
gbif_df <- pull_gbif_centroids(sp,
  cache_dir = "script/data-cache/gbif")
wc_df   <- pull_worldclim_per_species(
  species             = sp,
  gbif_cache_dir      = "script/data-cache/gbif",
  worldclim_cache_dir = "script/data-cache/worldclim")
# Combine for impute()
cov <- cbind(gbif_df[, c("centroid_lat", "centroid_lon")],
             wc_df[, grep("^bio", colnames(wc_df))])
# res <- impute(traits, tree, covariates = cov,
#               phylo_signal_gate = FALSE)  # <-- needed; see NEWS
} # }