Skip to contents

Fetch species range-centroid covariates from GBIF

Source: R/gbif_centroids.R
pull_gbif_centroids.Rd

Pulls occurrence records from the Global Biodiversity Information Facility (GBIF) for each species in species, aggregates them to a median latitude / longitude centroid. The returned data.frame contains species identifiers, centroid coordinates, and occurrence counts.

Usage

pull_gbif_centroids(
  species,
  cache_dir = NULL,
  occurrence_limit = 500L,
  sleep_ms = 100L,
  verbose = TRUE,
  refresh_cache = FALSE,
  store_points = FALSE
)

Arguments

species

non-empty character vector of unique species names. Do not include missing or empty names. These names are used for GBIF lookups, output row names, and (when caching) cache-key generation.

cache_dir

directory to cache per-species RDS files. NULL (default) disables caching — not recommended for production use.

occurrence_limit

integer, maximum number of occurrences to fetch per species (default 500; paginated if > 300).

sleep_ms

integer, polite delay between API calls in milliseconds (default 100).

verbose

logical, print progress every 50 species.

refresh_cache

logical, force re-fetch even when cache exists.

store_points

logical. When TRUE, persists the raw filtered lat/lon occurrence points in each species' cache RDS under the points field. Used by pull_worldclim_per_species for per-occurrence bioclim extraction. Default FALSE stores centroid summaries without the raw point list. Requesting points refetches an existing centroid-only GBIF cache when the point list is absent.

Value

A data.frame with columns species, centroid_lat, centroid_lon, n_occurrences. Rownames are set to species. NA centroids are returned for species with no GBIF hits; the caller should decide how to handle them (typical: drop or impute).

Details

With the default cache_dir = NULL, results are not cached, so a later call queries GBIF again for each species. Set cache_dir to a writable directory to reuse stored results; the example below uses "script/data-cache/gbif".

For each species: resolve taxon via name_backbone, fetch up to occurrence_limit records via occ_search (paginated at 300 per GBIF call), filter out records with hasGeospatialIssues = TRUE and basisOfRecord in c("FOSSIL_SPECIMEN", "LIVING_SPECIMEN"), drop out-of-range coordinates, then take the median latitude and longitude as the species centroid.

Species with zero post-filter records receive NA centroids; their rows are still included in the returned data.frame so it aligns with the input species list.

For cache files written by pigauto, refresh_cache = FALSE reuses a readable entry when its saved species name exactly matches the request. A live GBIF query is needed when no matching cache entry is available or refresh_cache = TRUE. GBIF is also queried again for that species when store_points = TRUE and the saved points field is absent or NULL. With cache_dir = NULL, each call queries GBIF instead of using a cache. These live-query paths require the optional rgbif package.

A cached result can still contain an NA centroid. That can mean pigauto could not match the species name, GBIF returned no records, or all records were excluded by pigauto's filters. Older cache entries may also reflect failed requests, including incomplete non-NA centroids or points when a later occurrence page failed. Set refresh_cache = TRUE to retry affected entries; this requires a live GBIF query and the optional rgbif package. A failed name lookup or occurrence request now stops with an error without caching a partial result or replacing an existing cache entry. Occurrence requests are retried before stopping.

See also

impute. For geographic covariates, select only centroid_lat and centroid_lon. With one row per species, keep species row names so coordinates match the species in the traits and tree. With repeated observations, repeat each species' coordinates in trait-row order. Resolve missing or non-finite coordinates before fitting.

Examples

if (FALSE) { # interactive()
sp <- c("Quercus alba", "Pinus taeda", "Acer saccharum")
cov <- pull_gbif_centroids(sp, cache_dir = "script/data-cache/gbif")
cov_num <- cov[, c("centroid_lat", "centroid_lon"), drop = FALSE]
}