Package {envar}

Type: Package
Title: Download and Process Environmental Variables
Version: 0.1.0
Description: Provides a unified interface to download, harmonise and extract a wide range of environmental and socio-economic variables from established open data web services (such as 'WorldClim' https://www.worldclim.org/, 'CHELSA' https://chelsa-climate.org/ and 'Bio-ORACLE' https://www.bio-oracle.org/, among others) for use in macroecology and biogeography. The package handles spatial subsetting to a study area, reprojection to a common coordinate reference system, and extraction of values at sampling points, so that predictors from heterogeneous sources can be assembled within a single reproducible workflow. Helper functions for collinearity checking and variable exploration are also included.
License: GPL-3
Language: en-US
Encoding: UTF-8
LazyData: true
LazyDataCompression: xz
Imports: terra, dplyr, httr, sf, rnaturalearth, usdm, corrplot, cli, fs, utils, digest, rangeBuilder
RoxygenNote: 7.3.2
Config/Needs/website: terra, dplyr, sf, pkgdown, usdm, corrplot, rangeBuilder
Suggests: knitr, rmarkdown, rnaturalearthdata
VignetteBuilder: knitr
URL: https://animalbiodiversitylab.github.io/envar/, https://github.com/animalbiodiversitylab/envar
BugReports: https://github.com/animalbiodiversitylab/envar/issues
Depends: R (≥ 3.5.0)
NeedsCompilation: no
Packaged: 2026-07-22 21:50:06 UTC; andre
Author: Andrea Simoncini ORCID iD [aut, cre], Michele Bertoncini ORCID iD [aut], Andrea Cerofolini ORCID iD [aut], Andrea Dalpasso ORCID iD [aut], Mattia Falaschi ORCID iD [aut], Gentile Francesco Ficetola ORCID iD [aut], Elia Lo Parrino ORCID iD [aut]
Maintainer: Andrea Simoncini <simonciniandre@gmail.com>
Repository: CRAN
Date/Publication: 2026-07-31 14:30:02 UTC

envar: Download and Process Environmental Variables

Description

logo

Provides a unified interface to download, harmonise and extract a wide range of environmental and socio-economic variables from established open data web services (such as 'WorldClim' https://www.worldclim.org/, 'CHELSA' https://chelsa-climate.org/ and 'Bio-ORACLE' https://www.bio-oracle.org/, among others) for use in macroecology and biogeography. The package handles spatial subsetting to a study area, reprojection to a common coordinate reference system, and extraction of values at sampling points, so that predictors from heterogeneous sources can be assembled within a single reproducible workflow. Helper functions for collinearity checking and variable exploration are also included.

Author(s)

Maintainer: Andrea Simoncini simonciniandre@gmail.com (ORCID)

Authors:

See Also

Useful links:

Pipe operator

Description

Re-exported from dplyr. See dplyr::%>% for details. This lets users chain envar functions, e.g. par_set(country = "Italy") %>% worldclim(vars = "bio1").

Usage

lhs %>% rhs

Arguments

lhs

A value or the magrittr placeholder.

rhs

A function call using the magrittr semantics.

Value

The result of calling rhs(lhs).

Alpine region

Description

A spatial dataset (class "sf", "data.frame") containing the borders of the European Alps region, retrieved from the Alpine Convention website (https://www.alpconv.org/fr/page-daccueil/). Used for examples and testing within the envar package.

Usage

Alps

Format

An sf object :

name

European Alps

geometry

sfc_MULTIPOLYGON geometry

Source

Alpine Convention

Apollo butterfly occurrences

Description

A "data.frame" containing the occurrence data of Apollo butterfly (Parnassius apollo), downloaded from the Global Biodiversity Information Facility website (www.gbif.org), on December 10, 2025. Used for examples and testing within the envar package.

Usage

Apollo

Format

A data.frame object :

X

longitude in WGS84

Y

latitude in WGS84

Source

GBIF

Europe

Description

Europe shapefile from the GADM, the Global Administrative Areas database.

Usage

Europe

Format

An sf object :

name

Europe

geometry

sfc_MULTIPOLYGON geometry

Source

GADM

Download and process Global Accessibility Indicators

Description

This function downloads, processes, and extracts variables from the Global Accessibility Indicators dataset. Each variable corresponds to a global raster representing the travelling time (in minutes) to cities or ports of specific sizes.

Usage

accessibility(x, vars, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Cities

Ports

Citation:
Nelson A, Weiss DJ, van Etten J et al (2019). "A suite of global accessibility indicators." Scientific Data 6, 266. https://doi.org/10.1038/s41597-019-0265-5

Note: Data extent is [-180, 180, -60, 85].

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


processed <- par_set(country = "Italy", crs = 3035) %>% 
accessibility(vars=c("large cities", "ports1"))

Download and process Global Aridity Index and Potential Evapotranspiration (ET0)

Description

This function downloads, processes, and extracts variables from the Global Aridity Index and ET0 Database v3. Each variable corresponds to a global raster representing aridity index or potential evapotranspiration values.

Usage

aridity(x, vars, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Annual Variables

Monthly Aridity Index

Monthly Potential Evapotranspiration (ET0)

Citation:
Zomer RJ, Xu J, Trabucco A (2022). "Version 3 of the Global Aridity Index and Potential Evapotranspiration Database." Scientific Data 9, 409. https://doi.org/10.1038/s41597-022-01493-1

Note: Data is downloaded from Figshare (Article ID 7504448).

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


processed <- par_set(country= "Italy", crs=3035) %>% 
aridity(vars=c("aridity index annual", "et0 january"))

Download Bio-ORACLE marine data

Description

This function downloads, processes, and extracts variables from the Bio-ORACLE v3.0 dataset.

Usage

biooracle(
  x,
  vars,
  realm = "surface",
  years = "2000-2010",
  ssp = NULL,
  algorithm = "mean",
  ...
)

Arguments

x

The output from 'par_set()' defining the area or locations. It must have been created with ‘res = 6' (Bio-ORACLE’s native 0.05-degree grid).

vars

Character vector of one or more variables or synonyms to download.

realm

Character. One of "surface" (default), "benthic_minimum", "benthic_average", or "benthic_maximum".

years

Character. The time period for the data in "YYYY-YYYY" format. Use "2000-2010" or "2010-2020" for baseline current conditions (default is "2000-2010"). For future projections, specify the decade (e.g., "2040-2050", "2090-2100") and provide the 'ssp' argument.

ssp

numeric or character. Shared Socioeconomic Pathway (119, 126, 245, 370, 460, 585). Required if 'years' is in the future (>= 2020).

algorithm

Character. Statistic to apply (max, mean, min, ltmax, ltmin, range). Default "mean".

...

Additional arguments.

Details

Available variables (working synonyms in parentheses and ""):

Citation:
Assis J, Fernández Bejarano SJ, Salazar VW, Schepers L, Gouvêa L, Fragkopoulou E, Leclercq F, Vanhoorne B, Tyberghein L, Serrão EA, Verbruggen H, De Clerck O (2024). "Bio-ORACLE v3.0. Pushing marine data layers to the CMIP6 Earth system models of climate change research." Global Ecology and Biogeography, 33, e13813. https://doi.org/10.1111/geb.13813

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Resolution

Bio-ORACLE layers are distributed on a 0.05-degree grid (~5.5 km at the equator). Because res is a multiplier of the 30 arc-second base grid, the value that reproduces this grid exactly is res = 6 (6 \times 30''= 0.05^{\circ}). You must therefore call par_set() with res = 6; any other value (including the default) raises an error.

Examples


# Example 1: Current conditions (Baseline)
current_env <- par_set(country = "Italy", crs = 3035, res = 6) %>%
  biooracle(vars = c("temperature", "salinity"),
            years = "2000-2010")

# Example 2: Future projections (2050, SSP 585)
future_env <- par_set(country = "Italy", crs = 3035, res = 6) %>%
  biooracle(vars = c("temperature", "salinity"),
            years = "2040-2050",
            ssp = 585)

Download CHELSA climate data

Description

This function downloads, processes, and extracts variables from the CHELSA (Climatologies at High Resolution for the Earth's Land Surface Areas) dataset.

Usage

chelsa(
  x,
  vars,
  years = NULL,
  months = NULL,
  gcm = NULL,
  rcp = NULL,
  ssp = NULL,
  cruts_years = NULL,
  ...
)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

years

A character or numeric vector of years or year ranges (e.g., "1981-2010", 2015).

months

A numeric vector (1–12) specifying which months to download. If NULL and 'years' are single years, all 12 months are downloaded.

gcm

General Circulation Model(s) for future projections.

rcp

Representative Concentration Pathway, given as the radiative-forcing level (e.g., 2.6, 4.5, 6.0, 8.5). For CMIP5 projections (year ranges "2041-2060", "2061-2080") it selects the RCP directly. For CMIP6/BIOCLIM+ projections it is combined with ssp to build the scenario code (e.g., ssp = 5 and rcp = 8.5 request the ssp585 scenario).

ssp

Shared Socioeconomic Pathway family for CMIP6/BIOCLIM+ data (e.g., 1, 2, 3, 5). Combined with rcp as described above. A complete code such as "585" may also be supplied directly (with rcp = NULL).

cruts_years

Numeric vector. Years to download from CHELSAcruts (must be 1901–2016).

...

Additional arguments (currently unused).

Details

Available variables

Please note the distinction between "Monthly" time-series data and "Climatologies". Unlike other functions in this package, there is only one code-name for each variable and no working synonyms. The meaning of each variable code-name is provided in parentheses.

Monthly Time-Series (Available from 1979 onwards)

Climatologies & Derived Indices (1981-2010, 2011-2040, 2041-2070, 2071-2100)

Cloud Cover

Climate Moisture Index

Relative Humidity

Potential Evapotranspiration

Solar Radiation

Wind Speed

Vapor Pressure Deficit

Growing Season Characteristics (TREELIM model)

Growing Degree Days (GDD)

Snow and Frost

Biological Productivity

Climate Classifications

Citation:
Standard bioclimatic variables: Karger D, Conrad O, Böhner J et al (2017). "Climatologies at high resolution for the earth’s land surface areas." Scientific Data 4, 170122. https://doi.org/10.1038/sdata.2017.122

BIOCLIM+ dataset: Brun P, Zimmermann NE, Hari C, Pellissier L, Karger DN (2022). "Global climate-related predictors at kilometer resolution for the past and future." Earth System Science Data 14, 5573-5603. https://doi.org/10.5194/essd-14-5573-2022

Note: Users should verify the terms of use for CHELSA data provided at https://chelsa-climate.org/

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples



# climatic values for one specific year/month
processed <- par_set(zooregion = "Madagascan") %>%
chelsa(vars=c("tas"), years = 2018, months = 1)

# climatic values for a long period (real "climate"), if months are not specified
# all the months are downloaded (12 layers per variable)
processed <- par_set(country = "Iceland") %>%
chelsa(vars=c("pr", "tas"), years = "1981-2010", months = 1)

# bioclimatic variables are available only over these extended periods, and not
# for the single years
processed <- par_set(country = "Iceland") %>%
chelsa(vars=c("bio1"), years = "1981-2010", months = 1)

# to download a specified set of variables, leave only "bio" and then the
# package will ask which variables to download (all 19 or a selection) in the console
processed <- par_set(country = "Iceland") %>%
chelsa(vars=c("bio"), years = "1981-2010", months = 1)

# climatic values for the future (SSP, RCP and GCM must be specified)
processed <- par_set(country = "Italy", crs = 3035) %>%
chelsa(vars=c("pr", "tas"), years = "2041-2070", months = 1,
 ssp = 5, rcp = 8.5, gcm = "GFDL-ESM4")

Clear the envar download cache

Description

Removes all files stored in the persistent download cache used when 'cache = TRUE' in [par_set()]. This is useful to free disk space or to force a fresh download of every variable.

Usage

clear_cache()

Value

Invisibly, the path of the cache directory that was cleared.

Download and process Köppen-Geiger climate classification maps

Description

This function downloads, processes, and extracts variables from the High-resolution (1 km) Köppen-Geiger maps dataset. Each variable corresponds to a global GeoTIFF representing climate classification zones based on historical data or future CMIP6 projections.

Usage

climatezones(x, vars = "zones", years = "1991-2020", ssp = NULL, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector. Defaults to "zones". Accepted aliases include: "koppengeiger", "climate", "climatezones", "koppen".

years

Character vector of time periods. Defaults to "1991-2020". Accepts formats with underscores or hyphens (e.g., "1901-1930" or "1901_1930").

ssp

Numeric or character vector of Shared Socioeconomic Pathways. Required for future projections (e.g., 126, 585).

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Time Periods (years argument):

Historical

Future

SSP Scenarios (ssp argument, required for future periods):

Citation:
Beck HE, McVicar TR, Vergopolan N, Berg A, Lutsko NJ, Dufour A, Zeng Z, Jiang X, van Dijk AIJM, Miralles DG (2023). "High-resolution (1 km) Köppen-Geiger maps for 1901-2099 based on constrained CMIP6 projections." Scientific Data 10, 724. https://doi.org/10.1038/s41597-023-02549-6

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


processed <- par_set(country= "Italy", crs=3035) %>% 
climatezones(vars="zones", years="1991-2020")

Download and process EarthEnv Global Cloud Cover layers

Description

This function downloads, processes, and extracts variables from the EarthEnv Global Cloud Cover dataset. Each variable corresponds to a global Cloud-Optimized GeoTIFF (COG) representing cloud cover dynamics.

Usage

cloudcover(x, vars, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Metrics

Seasonality

Monthly Means

Citation:
Wilson AM, Jetz W (2016). "Remotely sensed high-resolution global cloud dynamics for predicting ecosystem and biodiversity distributions." PLoS Biol 14(3): e1002415. https://doi.org/10.1371/journal.pbio.1002415

Note: Please cite original sources of primary datasets where appropriate.

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


processed <- par_set(country= "Italy", crs=3035) %>% 
cloudcover(vars=c("mean annual", "january"))

Check Variable Correlation and Multi-collinearity

Description

'corr_check()' is an optional function for the 'envar' package workflow. It allows you to check for variable correlation and multi-collinearity among the variables over the study area. It can be used before or after 'extr_check()'.

Usage

corr_check(x, pearson = NULL, vif = NULL)

Arguments

x

A 'SpatRaster', 'data.frame', or a list containing 'data' or 'extracted_df' (e.g., output from 'extr_check()').

pearson

Numeric or 'NULL'. Threshold for the absolute Pearson correlation coefficient above which variables are flagged with a warning. By default ('NULL') a default threshold of '0.7' is used; supply a value (e.g. '0.6') to be warned about variable pairs whose absolute correlation exceeds it instead.

vif

Numeric or 'NULL'. Threshold for the Variance Inflation Factor above which variables are flagged with a warning. By default ('NULL') a default threshold of '3' is used; supply a value (e.g. '5') to be warned about variables whose VIF exceeds it instead.

Details

Citation:
Wei T, Simko V (2021). "R package 'corrplot': Visualization of a Correlation Matrix." GitHub. https://github.com/taiyun/corrplot

Naimi B, Hamm NA, Groen TA, Skidmore AK, Toxopeus AG (2014). "Where is positional uncertainty a problem for species distribution modelling?" Ecography 37, 191-203. https://doi.org/10.1111/j.1600-0587.2013.00205.x

Regardless of whether 'pearson'/'vif' thresholds are set, the function writes two files: the correlation plot ('Corr_plot.png') and a table of VIF values ('VIF_table.csv'). In an interactive R session it asks, at the console, for the directory in which to store them every time it is called. In non-interactive sessions (e.g. scripts or 'R CMD check') a temporary directory is used and no prompt is shown. Their paths are returned as 'plot_path' and 'vif_path'.

Value

A 'list' object containing:

Examples

# corr_check() runs offline on the small example raster bundled with the
# package (a real WorldClim extract for Switzerland), so it needs no download:
switzerland <- terra::rast(
  system.file("extdata", "switzerland.tif", package = "envar")
)
cc <- corr_check(switzerland)
cc$summary

# It also accepts a plain data.frame of predictor values:
set.seed(1)
example_df <- data.frame(bio1 = rnorm(40), bio12 = rnorm(40))
example_df$bio11 <- example_df$bio1 + rnorm(40, sd = 0.2)  # correlated with bio1
corr_check(example_df)$summary


# The typical workflow chains corr_check() after downloading variables.
# Example 1: Basic usage after environmental variable extraction
processed_bilayer_corr_check <- par_set(country = "Italy", crs=3035, buffer = 10) %>% 
  melc(vars=c("ice")) %>% 
  chelsa(vars=c("pr"), months= 12, year=2015) %>% 
  corr_check()

# Example 2: Chain with extr_check() (corr_check before extr_check)
result <- par_set(country = "Italy") %>% 
  chelsa(vars = c("bio1", "bio12")) %>% 
  corr_check() %>%
  extr_check(calib_points = my_points)

# Example 3: Chain with extr_check() (extr_check before corr_check)
result <- par_set(country = "Italy") %>%
  chelsa(vars = c("bio1", "bio12")) %>%
  extr_check(calib_points = my_points) %>%
  corr_check()

# Example 4: Custom thresholds for high correlation (>0.7) and VIF (>5)
result <- par_set(country = "Italy") %>%
  chelsa(vars = c("bio1", "bio12")) %>%
  corr_check(pearson = 0.7, vif = 5)

Download and process EarthEnv land cover variables

Description

This function downloads, processes, and extracts variables from the EarthEnv Consensus Land Cover dataset. Each variable corresponds to a global raster representing a specific land cover class at 1-km resolution.

Usage

earthenvlandcover(x, vars, discover = TRUE, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

discover

Logical. If 'TRUE' (default), downloads the version integrated with the DISCover dataset. If 'FALSE', downloads the version without DISCover integration.

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Citation:
Tuanmu MN, Jetz W (2014). "A global 1-km consensus land-cover product for biodiversity and ecosystem modeling." Global Ecology and Biogeography 23, 1031-1045. https://doi.org/10.1111/geb.12182

Note: Users should verify the terms of use for EarthEnv data provided at https://www.earthenv.org/

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


processed <- par_set(country= "Italy", crs=3035) %>% 
earthenvlandcover(vars=c("snow ice"))

Check for Environmental Extrapolation

Description

This function evaluates whether environmental conditions in the study area fall outside the range of conditions observed at calibration points. This helps identify areas where Species Distribution Model (SDM) predictions may be unreliable due to extrapolation.

Usage

extr_check(
  x,
  calib_points,
  calib_crs = "EPSG:4326",
  type = c("strict", "combinatorial")
)

Arguments

x

A 'SpatRaster', 'data.frame', or a list containing the output from previous pipeline steps (e.g., from 'corr_check()').

calib_points

A 'data.frame' with columns 'X' and 'Y' containing the coordinates of the calibration points. These are the locations where presence/absence or occurrence data were collected for model training.

calib_crs

Character or numeric. The Coordinate Reference System of the calibration points. Can be an EPSG code (e.g., '"EPSG:4326"', '4326'), an ESRI code, a PROJ4 string, or WKT. Default is '"EPSG:4326"' (WGS84).

type

Character vector specifying the type(s) of extrapolation to check. Options are '"strict"', '"combinatorial"', or 'c("strict", "combinatorial")' (default).

  • '"strict"': Uses 1 bin per variable (detects univariate extrapolation).

  • '"combinatorial"': Uses 5 bins per variable (detects multivariate novelty).

Details

Extrapolation types

Extrapolation can occur in two ways:

This function uses the environmental overlap mask approach from Zurell et al. (2012), here implemented natively within 'envar' (adapted from the 'eo_mask' method described in that work). It uses 1 bin per variable for strict extrapolation detection and 5 bins per variable for combinatorial extrapolation detection.

Citations:
Elith J, Kearney M, Phillips S (2010). "The art of modelling range-shifting species." Methods in Ecology and Evolution 1, 330-342. https://doi.org/10.1111/j.2041-210X.2010.00036.x

Zurell D, Elith J, Schroeder B (2012). "Predicting to new environments: tools for visualizing model behaviour and impacts on mapped distributions." Diversity and Distributions 18, 628-634. https://doi.org/10.1111/j.1472-4642.2012.00887.x

Value

A 'list' containing:

Examples

# extr_check() runs offline on the small example raster bundled with the
# package (a real WorldClim extract for Switzerland). Here we flag cells whose
# climate is novel relative to the Apollo occurrences that fall in Switzerland:
switzerland <- terra::rast(
  system.file("extdata", "switzerland.tif", package = "envar")
)
calib <- subset(Apollo, X >= 5.9 & X <= 10.5 & Y >= 45.8 & Y <= 47.8)
checked <- extr_check(switzerland, calib_points = calib, type = "strict")
checked$extrapolation


# Example 1: Check extrapolation after getting environmental variables
result <- par_set(country = "Italy") %>%
  melc(vars = c("tree", "water")) %>%
  chelsa(vars = "bio1", years = "1981-2010", month = 1) %>%
  extr_check(calib_points = my_occurrence_data)

# Example 2: Chain with corr_check()
result <- par_set(pointsdf = Apollo[1:10,]) %>%
  melc(vars = c("ice")) %>%
  chelsa(vars = "bio1", years = "1981-2010", month = 1) %>%
  corr_check() %>%
  extr_check(calib_points = calibration_data, type = "strict")

# Example 3: Check only combinatorial extrapolation
result <- par_set(country = "Germany") %>%
  worldclim(vars = c("bio1", "bio12")) %>%
  extr_check(calib_points = occ_points, type = "combinatorial")

Download and process EarthEnv Freshwater Environmental Variables

Description

This function downloads, processes, and extracts variables from the Near-global freshwater-specific environmental variables dataset. These variables are available at 1 km resolution and capture upstream catchment characteristics, including topography, land cover, soil, and climate.

Usage

freshwater(x, vars, year = NULL, month = NULL, algorithm = NULL, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

year

Numeric. Selected year(s) for extraction. Note that most EarthEnv freshwater variables are static layers (2015 version); this argument is primarily for consistency.

month

Numeric. Selected month(s) (1-12) for extraction. Only applicable to monthly variables (e.g., tmin, tmax, prec).

algorithm

Character. Aggregation method to filter specific bands.

  • For Elevation and Slope: "min" (Band 1), "max" (Band 2), "range" (Band 3), "avg" (Band 4).

  • For Flow Accumulation: "length" (Band 1), "acc" (Band 2).

  • For other variables: matches the string in the layer name.

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Temperature

Precipitation

Hydroclimatic

Topography

Land cover

Geology & Soil

Quality control

Citation:
Domisch S, Amatulli G, Jetz W (2015). "Near-global freshwater-specific environmental variables for biodiversity analyses in 1 km resolution." Scientific Data 2, 150073. https://doi.org/10.1038/sdata.2015.73

Note: Please cite original sources of primary datasets where appropriate.

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


# Topography with algorithm filtering (keeping only the average band)
processed <- par_set(country = "Switzerland", crs = 3035) %>% 
  freshwater(vars = c("elevation", "slope"), algorithm = "avg")

# Monthly Climate (January and July)
processed <- par_set(country = "Italy", crs = 3035) %>% 
  freshwater(vars = "tmin", month = c(1, 7))

Download and process Global Future Land Use/Cover layers (2020-2100)

Description

This function downloads, processes, and extracts simulated global land use and land cover (LULC) data for the period 2020-2100.

Usage

gcamlandcover(x, vars = "landcover", ssp = 126, year = 2020, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer.

vars

Character. Currently unused/ignored as this function returns the landcover map defined by 'year' and 'ssp', but kept for consistency. Default is "landcover".

ssp

Numeric or Character. The SSP scenario code (126, 245, 370, 434, 585). Ignored if 'year' is 2020.

year

Numeric. The year of simulation (2020, 2030, 2050, 2070, 2100).

...

Additional arguments (currently unused).

Details

The data represents 1 km resolution LULC maps. The original data is in World Mercator projection and will be automatically reprojected to the CRS defined in 'par_set()'.

Land cover codes

Available Years

Available SSPs (Shared Socioeconomic Pathways)

Citation:
Zhang T, Cheng C, Wu X (2023). "Mapping the spatial heterogeneity of global land use and land cover from 2020 to 2100 at a 1 km resolution." Scientific Data 10, 748. https://doi.org/10.1038/s41597-023-02637-7

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack. If 'par_set()' contained spatial points without buffer: a 'data.frame'.

Examples


# Get Baseline (2020)
processed <- par_set(country= "Italy", crs=4326) %>% 
  gcamlandcover(year = 2020)

# Get Future (SSP5-8.5 in 2050)
processed <- par_set(country= "Italy", crs=4326) %>% 
  gcamlandcover(ssp = 585, year = 2050)

Download and process Historical Real GDP and Electricity Consumption

Description

This function downloads, processes, and extracts variables from the global 1km gridded revised real gross domestic product and electricity consumption dataset (1992–2019).

Usage

gdppast(x, vars, year, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of variables to download ("gdp" or "electricity").

year

Numeric vector of years to download. Available range: 1992-2019.

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Economic Metrics

Energy Metrics

Years available

Citation:
Chen J, Gao M, Cheng S et al (2022). "Global 1 km x 1 km gridded revised real gross domestic product and electricity consumption during 1992–2019 based on calibrated nighttime light data." Scientific Data 9, 202. https://doi.org/10.1038/s41597-022-01322-5

Note: Please cite original sources of primary datasets where appropriate.

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


# Get GDP for 2000 and 2010
processed <- par_set(country= "Italy", crs=3035) %>% 
  gdppast(vars="gdp", year=c(2000, 2010))

# Get Electricity and GDP for 2019
processed <- par_set(country= "Vietnam") %>% 
  gdppast(vars=c("electricity", "gdp"), year=2019)

Download and process Global Simulation Land Use/Cover (GEOSOS) 1 km variables

Description

This function downloads, processes, and extracts variables from the Global Land-Use and Land-Cover Change Product (2010-2100). The dataset provides global 1 km resolution rasters based on different IPCC scenarios.

Usage

geososlandcover(x, vars, scenario = "A1B", year = 2010, discover = TRUE, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

scenario

Character. The IPCC scenario: "A1B", "A2", "B1", or "B2". Ignored if year is 2010.

year

Numeric or character. The year of the product: 2010, 2050, or 2100.

discover

Logical. Kept for compatibility (currently unused).

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Land Cover Classification

Simulation Parameters

Citation:
Li X, Chen G, Liu X, Liang X, Wang S, Chen Y, Pei F, Xu X (2017). "A new global land-use and land-cover change product at a 1-km resolution for 2010 to 2100 based on human–environment interactions." Annals of the American Association of Geographers 107(5), 1040–1059. https://doi.org/10.1080/24694452.2017.1303357

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


# Example 1: Download land cover for Italy in 2050 under scenario A1B
processed <- par_set(country = "Italy", crs = 3035) %>% 
  geososlandcover(vars = c("land cover"), year = 2050, scenario = "A1B")
  
# Example 2: Extract baseline (2010) values for specific points
points_df <- data.frame(ID = 1:2, x = c(12, 13), y = c(42, 43))
extracted <- par_set(data = points_df, crs = 4326) %>%
  geososlandcover(vars = "lc", year = 2010)

Download and process IUCN Habitat Classification layers

Description

This function downloads, processes, and extracts variables from the IUCN Global Habitat Classification Fractions dataset (Jung et al., 2020). The data is available at Level 1 (broad) and Level 2 (detailed) classifications.

Usage

habitat(x, vars, level = 1, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

level

Integer. The classification level to download. 1 (broad) or 2 (detailed). Defaults to 1.

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Level 1 (Broad Categories)

Level 2 (Detailed Categories - Selection)

Citation:
Jung M, Dahal PR, Butchart SHM, Donald PF, De Lamo X, Lesiv M, Kapos V, Rondinini C, Visconti P (2020). "A global map of terrestrial habitat types." Scientific Data 7, 256. https://doi.org/10.1038/s41597-020-00599-8

Note: Please cite original sources of primary datasets where appropriate.

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


# Example 1: Level 1 extraction (Forest and Artificial)
processed <- par_set(country = "Italy", crs = 3035) %>% 
  habitat(vars = c("Forest", "Artificial"), level = 1)

# Example 2: Level 2 extraction (Specific biomes)
processed_l2 <- par_set(country = "Brazil", crs = 3035) %>% 
  habitat(vars = c("Mangrove", "Tropical moist lowland forest"), level = 2)

Download and process EarthEnv habitat heterogeneity layers

Description

This function downloads, processes, and extracts variables from the EarthEnv habitat heterogeneity dataset (1-km resolution). Each variable corresponds to a global Cloud-Optimized GeoTIFF (COG) representing different metrics of habitat heterogeneity derived from remote sensing data.

Usage

heterogeneity(x, vars, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

First-order statistics

Second-order statistics (texture metrics)

Citation:
Tuanmu M-N, Jetz W (2015). "A global, remote sensing-based characterization of terrestrial habitat heterogeneity for biodiversity and ecosystem modeling." Global Ecology and Biogeography, 24, 1329-1339. https://doi.org/10.1111/geb.12365

Note: Please cite original sources of primary datasets where appropriate.

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


# Example 1: Download Shannon Index and Coefficient of Variation for the Alps
processed <- par_set(shape = Alps, crs = 3035) %>% 
  heterogeneity(vars = c("shannon", "cv"))

Download and process Hybrid Global Annual 1-km IGBP Land Cover Maps

Description

This function downloads, processes, and extracts land cover variables from the Hybrid Global Annual 1-km IGBP Land Cover Maps dataset (Luo et al., 2024). The data covers the period from 2000 to 2020.

Usage

hybridlandcover(x, vars = NULL, year = 2000, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

year

Integer. The year for which to download the land cover map (2000-2020). Defaults to 2000.

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Citation:
Luo Y, Zhu Z, Zhao W, Li M, Chen J, Zhao P, Sun L, Zhang Y, Duanmu Z, Chen J (2024). "Hybrid Global Annual 1-km IGBP Land Cover Maps for the Period 2000–2020." Journal of Remote Sensing, 4, 0122. https://doi.org/10.34133/remotesensing.0122

Note: You must specify the 'year' argument (integer between 2000 and 2020).

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


processed <- par_set(country= "Italy", crs=3035) %>% 
  hybridlandcover(vars="landcover", year=2015)

Download and process MacroEcological Land Cover (MELC)

Description

This function downloads, processes, and extracts variables from the MELC 1 km Land Cover dataset, designed for biogeography and ecological modelling. Each variable corresponds to a global raster representing a specific land cover class or diversity index derived from very high-resolution imagery of the ESA.

Usage

melc(x, vars, discover = TRUE, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

discover

Logical. If TRUE, creates a discovery map (unused in current implementation but kept for compatibility).

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Land Cover Classes

Diversity & Metrics

Citation:
Lo Parrino E, Simoncini A, Ficetola GF, Falaschi M (2025). "Global 1 km land cover for macroecological modelling from very high resolution imagery." Figshare. https://doi.org/10.6084/m9.figshare.30665069

Note: Users should verify the terms of use provided at https://figshare.com/s/4e7dee46628b530aee03

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


processed <- par_set(country= "Italy", crs=3035) %>% 
  melc(vars=c("tree", "water"))

Initialize the Environmental Variable Retrieval Pipeline

Description

par_set() is the entry point for the envar package workflow. It defines the spatial extent, resolution, and coordinate reference system (CRS) for the study area.

Usage

par_set(
  country = NULL,
  continent = NULL,
  shape = NULL,
  ecoregion = NULL,
  biome = NULL,
  realm = NULL,
  zooregion = NULL,
  zoorealm = NULL,
  mountain_region = NULL,
  mountain_region_cmec = NULL,
  glacier_region_19 = NULL,
  glacier_region_20 = NULL,
  freshwater_ecoregion = NULL,
  marine_ecoregion = NULL,
  marine_realm = NULL,
  marine_province = NULL,
  pelagic_province = NULL,
  pelagic_biome = NULL,
  pelagic_realm = NULL,
  pointsdf = NULL,
  alpha_hull = FALSE,
  buffer = 0,
  res = NULL,
  path = NULL,
  crs = "EPSG:4326",
  set_na = FALSE,
  scale = "medium",
  land = FALSE,
  cache = TRUE
)

Arguments

country

Character. The English name of a country (e.g., "Italy", "Viet Nam"). Used to generate the extent if shape is NULL.

continent

Character. The English name of a continent (e.g., "Europe", "Africa"). Used to generate the extent if shape and country are NULL.

shape

An sf object representing the study area. This can be:

  • Polygons: defining a region of interest.

  • Points: defining specific sampling locations.

If shape is provided, country and continent are ignored.

ecoregion

Character. The name of a terrestrial ecoregion from Dinerstein et al. (2017). Uses the ECO_NAME column from the Ecoregions2017 dataset.

biome

Character. The name of a biome from Dinerstein et al. (2017). Uses the BIOME_NAME column from the Ecoregions2017 dataset.

realm

Character. The name of a biogeographic realm from Dinerstein et al. (2017). Uses the REALM column from the Ecoregions2017 dataset.

zooregion

Character. The name of a zoogeographic region from Holt et al. (2013). Uses the Regions column from the CMEC dataset.

zoorealm

Character. The name of a zoogeographic realm from Holt et al. (2013). Uses the Realm column from the CMEC newRealms dataset.

mountain_region

Character. The name of a mountain region from the GMBA Mountain Inventory v2.0 (Snethlage et al. 2022). Uses the MapName column.

mountain_region_cmec

Character. The name of a mountain region from the Center for Macroecology, Evolution, and Climate definition of mountain areas (Rahbek et al. 2019). Uses the Name column.

glacier_region_19

Character. The name of a glacier region based on RGI v6.0 (2017) first-order regions. Uses the RGI_CODE column.

glacier_region_20

Character. The name of a glacier region based on GTN-G 2023 first-order regions. Uses the o1region column.

freshwater_ecoregion

Character or Numeric. The FEOW_ID of a freshwater ecoregion from Abell et al. (2008). Uses the FEOW_ID column from the FEOW dataset.

marine_ecoregion

Character. The name of a marine ecoregion from Spalding et al. (2007). Uses the ECOREGION column from the MEOW dataset (TYPE == "MEOW").

marine_realm

Character. The name of a marine realm from Spalding et al. (2007). Uses the REALM column from the MEOW dataset (TYPE == "MEOW").

marine_province

Character. The name of a marine province from Spalding et al. (2007). Uses the PROVINC column from the MEOW dataset (TYPE == "MEOW").

pelagic_province

Character. The name of a pelagic province from Spalding et al. (2012). Uses the PROVINC column from the PPOW dataset (TYPE == "PPOW").

pelagic_biome

Character. The name of a pelagic biome from Spalding et al. (2012). Uses the BIOME column from the PPOW dataset (TYPE == "PPOW").

pelagic_realm

Character. The name of a pelagic realm from Spalding et al. (2012). Uses the REALM column from the PPOW dataset (TYPE == "PPOW").

pointsdf

Data.frame with columns X and Y representing point coordinates.

alpha_hull

Logical. If TRUE, creates an alpha hull polygon around the occurrence points using the getDynamicAlphaHull function from the rangeBuilder package (Rabosky et al. 2016) to model species distribution ranges. The initialAlpha is set to 2 and gradually increased until a polygon captures at least 99% of occurrence records. This method optimizes the balance between identifying distinct clusters as unique polygons and avoiding excessive fragmentation (Roll et al. 2017). Can be used in conjunction with buffer (applied after alpha hull creation) and land (intersects result with land boundary). Default is FALSE.

References:

  • Rabosky ARD, et al. (2016). BAMMtools: an R package for the analysis of evolutionary dynamics on phylogenetic trees. Methods in Ecology and Evolution 7:701-707.

  • Roll U, et al. (2017). The global distribution of tetrapods reveals a need for targeted reptile conservation. Nature Ecology & Evolution 1:1677-1682.

buffer

Numeric. A buffer distance in kilometers to expand or shrink the extent. The buffer is always specified in kilometers regardless of the target CRS - the function automatically converts to the appropriate units internally (degrees for geographic CRS like EPSG:4326, meters for projected CRS like EPSG:3035 or ESRI:54009).

  • Positive values: Expand the area outward by this distance.

  • Negative values: Shrink the area inward by this distance (useful for excluding coastal/border areas where data may have different characteristics).

  • For points with positive buffer: A circular buffer of this radius is drawn around each point, effectively converting the study area into polygons.

  • Default is 0.

res

Numeric. The target spatial resolution multiplier.

  • This controls the cell size of the output raster stack.

  • Must be a positive number >= 1 (e.g., 1, 5, 10). It is usually an integer, but fractional multipliers are allowed to match a dataset's native grid. For instance biooracle() requires res = 6, which reproduces Bio-ORACLE's native 0.05° (~5.5 km) grid exactly.

  • Default is 1 (30 arc-seconds or 0.008333333° at the equator).

  • Higher values will multiply the original 30 arcsec resolution by the specified factor.

path

directory to store the result of the download/processing. Default to NULL (no output is stored locally). It works only if no corr_check() is specified. Specify the path including the file name and the extension (e.g. "../Out/rastername.tif" if the final export is a SpatRaster; or "../Out/extracteddataframe.csv" if the output is a data.frame).

crs

Character or Numeric. The Coordinate Reference System for the final output.

  • Can be an EPSG code with or without prefix (e.g., 4326, 3035, "EPSG:4326"), an ESRI code (e.g., 54009, "ESRI:54009"), a PROJ4 string, or WKT.

  • If NULL, the pipeline uses the standard default WGS84 (EPSG:4326).

  • If specified, all downstream environmental layers will be projected to this CRS after processing.

  • Note: ESRI codes (53000-54999, 100000+) are automatically recognized and prefixed with "ESRI:" internally.

set_na

Logical, with default FALSE. If TRUE, any cell that is NA in at least one raster is set to be NA in all rasters of the final SpatRaster object. It is useful only when the output is a SpatRaster and not a point extraction.

scale

Character with value "small", "medium", or "large". It represents the scale at which the country/continent shapefile are retrieved using the rnaturalearthdata package. Large implies a better definition of the borders of the shapefile (scale 1:10). The default is "medium". It is useful only when setting the argument country or continent.

land

Logical, with default FALSE. If TRUE, the extent is intersected with the global land boundary from Natural Earth (at the scale defined by the scale argument). This is useful for clipping marine/pelagic regions to land only, or for ensuring that buffered areas do not extend into the ocean. Note: This does not apply to point extractions (pointsdf without buffer).

cache

Logical, with default TRUE. If TRUE, each source file downloaded by the downstream functions (e.g. chelsa(), worldclim(), topography()) is stored in a persistent per-user cache directory. If the download pipeline is interrupted (for example by a lost connection) and then re-launched, it resumes from where it stopped, reusing files that were already retrieved instead of downloading them again. Set to FALSE to use a temporary directory that is cleared at the end of the R session. The cache can be emptied at any time with clear_cache.

Details

This function does not download data itself. Instead, it creates a standardized spatial template (grid) or processes point locations that are passed to downstream functions (like chelsa(), worldclim(), topography(), etc.) to ensure all retrieved variables are perfectly aligned and stacked.

Value

A list object (class envar_par) containing:

How it works

  1. Extent Definition: You can define the study area using a shapefile (sf object), a country name, a continent name, or various biogeographic boundary types.

  2. Resolution: The res argument sets the target resolution as a multiplier of the base 30 arc-seconds (~1 km at equator).

  3. Buffering: An optional buffer can be applied to expand the study area or create a sampling radius around points. The buffer is always specified in kilometers, regardless of the target CRS. The function automatically converts to the appropriate units (degrees for geographic CRS, meters for projected CRS).

  4. Output:

    • If the input is a polygon (or country/continent), it returns a list containing a target SpatRaster grid and a vector mask.

    • If the input is points (without a buffer), it returns the point coordinates for extraction.

    • If the input is points with a buffer, it creates a polygon geometry around the points and returns a grid, allowing you to download raster data for the area surrounding your points.

Resampling and reprojection

Downstream functions align every layer to the target grid defined here using terra::resample()/terra::project(). Continuous layers are resampled with bilinear interpolation, while categorical (factor) layers automatically use nearest-neighbour to avoid creating invalid class codes. You can force a specific method for all layers with, e.g., options(envar.resample_method = "near") (accepted values are any terra resampling method, or "auto" for the default behaviour described above).

Examples


# Basic usage with a country
italy_grid <- par_set(country = "Italy")

# Download with a shapefile
processed_alps <- par_set(shape = "Alps") %>% 
melc(vars=c("ice"))

# With a projected CRS and positive buffer (expand by 10 km)
italy_buffered <- par_set(country = "Italy", crs = 3035, buffer = 10)

# With a negative buffer (shrink by 10 km to exclude coastal areas)
italy_inland <- par_set(country = "Italy", crs = 3035, buffer = -10)

# Points with buffer to create extraction area
points_area <- par_set(pointsdf = Apollo, buffer = 10, crs = 4326)

# Using alpha hull to define species range from occurrence points
species_range <- par_set(pointsdf = species_occurrences, alpha_hull = TRUE)

# Alpha hull with buffer (buffer applied after alpha hull creation)
species_range_buffered <- par_set(pointsdf = species_occurrences, alpha_hull = TRUE, buffer = 50)

# Alpha hull clipped to land boundary
species_range_land <- par_set(pointsdf = species_occurrences, alpha_hull = TRUE, land = TRUE)

# Alpha hull with buffer and land intersection
species_range_full <- par_set(pointsdf = species_occurrences, alpha_hull = TRUE,
                               buffer = 25, land = TRUE)

# Using zoogeographic regions
palearctic <- par_set(zoorealm = "Palearctic")

# Using mountain regions
alps_gmba <- par_set(mountain_region = "European Alps")

# Using glacier regions
arctic_glaciers <- par_set(glacier_region_20 = "Arctic Canada North")

# Using freshwater ecoregions
danube <- par_set(freshwater_ecoregion = 404)

# Using marine ecoregions
mediterranean <- par_set(marine_realm = "Temperate Northern Atlantic")

# Using pelagic provinces
atlantic_pelagic <- par_set(pelagic_realm = "Atlantic Warm Water")

# Clip marine realm to land only
land_only <- par_set(marine_realm = "Temperate Northern Atlantic", land = TRUE)

Download and process Global PFT Land Cover Projections (SSPs-RCPs)

Description

This function downloads, processes, and extracts land cover variables from the Global 7-land-types LULC projection dataset based on plant functional types (PFT) with a 1-km resolution under socio-climatic scenarios (Chen et al., 2022).

Usage

pftlandcover(x, vars = NULL, year = 2025, ssp = 585, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

year

Integer. The year of the projection (2020-2100, step 5). Defaults to 2025.

ssp

Integer or Character. The SSP-RCP scenario code (119, 126, 245, 370, 434, 460, 534, 585). Defaults to 585.

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Land Cover

Citation:
Chen G, Li X, Liu X (2022). "Global land projection based on plant functional types with a 1-km resolution under socio-climatic scenarios." Scientific Data 9, 125. https://doi.org/10.1038/s41597-022-01208-6

Note: If the 'vars' argument is left empty, the function will default to downloading the land cover map.

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


# Download SSP5-RCP8.5 projection for 2050
processed <- par_set(country= "Italy", crs=3035) %>% 
  pftlandcover(vars="landcover", year=2050, ssp=585)

Download and process Global Population Projections (SSP)

Description

This function downloads, processes, and extracts variables from the Global Population Projections dataset (Wang et al., 2022). It provides 1-km grid population distributions from 2020 to 2100 under five Shared Socioeconomic Pathways (SSPs).

Usage

population(x, vars, year = 2020, ssp = 1, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

year

Numeric vector. Years to download. Available from 2020 to 2100 in 5-year intervals (e.g., c(2020, 2050)).

ssp

Numeric vector. Shared Socioeconomic Pathways to download (1, 2, 3, 4, or 5).

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Citation:
Wang X, Meng X, Long Y (2022). "Projecting 1 km-grid population distributions from 2020 to 2100 globally under shared socioeconomic pathways." Scientific Data 9, 563. doi:10.1038/s41597-022-01675-x

Note: Please cite original sources of primary datasets where appropriate.

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


processed <- par_set(country = "Italy", crs = 3035) %>% 
  population(vars = "population", year = 2050, ssp = 2)

Download and process WDPA Protected Area layers

Description

This function downloads, processes, and extracts variables from the World Database of Protected Areas (WDPA). Each variable corresponds to a global raster representing different IUCN Management Categories of protected areas.

Usage

protection(x, vars, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

IUCN Management Categories

Citation:
Protected Planet (2025). "World Database of Protected Areas (WDPA)." [UNEP-WCMC]. https://www.protectedplanet.net/en

Note: Users should ensure they comply with the terms of use of the WDPA when using these data for commercial or research purposes.

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


# Example 1: Download National Parks and All Protected Areas for Italy
processed <- par_set(country= "Italy", crs=3035) %>% 
protection(vars=c("national park", "WDPA_ALL"))

Download and process Harmonized World Soil Database v2.0

Description

This function downloads, processes, and extracts variables from the Harmonized World Soil Database v2.0 (HWSD v2.0). The variable corresponds to a global raster file at 1 km resolution representing soil types.

Usage

soil(x, vars = NULL, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process. Defaults to "hwsd" if left empty.

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Soil Data

Citation:
FAO, IIASA (2023). "Harmonized World Soil Database v2.0." Food and Agriculture Organization of the United Nations, Rome and International Institute for Applied Systems Analysis, Laxenburg, Austria. https://www.fao.org/soils-portal/data-hub/soil-maps-and-databases/harmonized-world-soil-database-v20/en/

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


processed <- par_set(country= "Italy", crs=3035) %>% 
soil(vars=c("soil"))

Download and process Soil Bioclimatic and Temperature layers

Description

This function downloads, processes, and extracts soil bioclimatic variables and monthly soil temperatures from the Global Soil Temperature dataset (Lembrechts et al., 2022).

Usage

soilclimate(x, vars, depth = "0-5", ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

depth

Character string defining the soil depth range. Options are "0-5" (default) or "5-15".

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Bioclimatic Variables

Monthly Mean Soil Temperatures

Citation:
Lembrechts JJ et al. (2022)."Global maps of soil temperature." Global Change Biology 28, 3110-3144. doi:10.1111/gcb.16060

Note: Please cite original sources of primary datasets where appropriate.

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


processed <- par_set(country= "Italy", crs=3035) %>% 
soilclimate(vars=c("SBIO1", "SBIO10"), depth="5-15")

Download and process SPECTRE environmental threat layers

Description

This function downloads, processes, and extracts variables from the SPECTRE — Spatially Explicit ECosysTem ThREats dataset. Each variable corresponds to a global Cloud-Optimized GeoTIFF (COG) representing a different anthropogenic or climatic threat.

Usage

spectre(x, vars, ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Land Use and Human Pressure

Forest Loss

Light Pollution

Climate Change

Citation:
Branco VV, Capinha C, Rocha J, Correia L, Cardoso P (2024). "SPECTRE: standardized global spatial data on terrestrial SPecies and ECosystems ThREats." Global Ecology and Biogeography, 34, e13949. doi:10.1111/geb.13949

Note: Many SPECTRE variables are derived from external primary datasets. Users should consult and cite the original sources listed in the SPECTRE supplementary materials.

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


processed <- par_set(country= "Italy", crs=3035) %>% 
  spectre(vars=c("forest loss", "light at night"))

Download and process EarthEnv Topography layers

Description

This function downloads, processes, and extracts variables from the EarthEnv Topography dataset. This dataset provides global, cross-scale topographic variables suitable for biodiversity and ecosystem modeling.

Usage

topography(x, vars, algorithm = "md", topo_source = "GMTED", ...)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

algorithm

Character. The aggregation method/algorithm to use.

  • Common options: "md" (median, default), "mn" (mean), "min", "max", "sd".

  • Note: These codes directly affect the downloaded filename (e.g., _1KMmd_).

topo_source

Character. The source of the data.

  • "GMTED" (Global Multi-resolution Terrain Elevation Data) - Default.

  • "SRTM" (Shuttle Radar Topography Mission).

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

[Topography Variables]

Citation:
Amatulli G, Domisch S, Tuanmu M-N, Parmentier B, Ranipeta A, Malczyk J, Jetz W (2018). "A suite of global, cross-scale topographic variables for environmental and biodiversity modeling." Scientific Data 5, 180040. https://doi.org/10.1038/sdata.2018.40

Note: Please cite original sources of primary datasets where appropriate.

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


# Example 1: Download elevation and slope for Italy
processed <- par_set(country = "Italy", crs = 3035) %>% 
  topography(vars = c("elevation", "slope"))

Download and process WorldClim Climate Data (Historical & Future)

Description

This function downloads, processes, and extracts variables from the WorldClim climate dataset. Each variable corresponds to a global raster representing climate variables at approximately 1-km resolution. It supports both Historical (v2.1, 1970-2000) and Future (CMIP6) data.

Usage

worldclim(
  x,
  vars,
  years = NULL,
  months = NULL,
  gcm = NULL,
  rcp = NULL,
  ssp = NULL,
  ...
)

Arguments

x

The output from 'par_set()' defining the area or locations for extraction, the reference system, and the buffer. Leave this empty and use 'par_set()' to define parameters for download.

vars

Character vector of one or more variables to download and process.

years

Character vector of years or periods. For Historical: use "1970-2000" or "historical". For Future: use "2021-2040", "2041-2060", "2061-2080", "2081-2100".

months

Numeric vector (1-12) specifying which months to download. Only applies to monthly historical variables. Ignored for bioclimatic variables, elevation, or future data.

gcm

Character vector of General Circulation Models (for Future data).

rcp

Numeric or character vector of Representative Concentration Pathways, given as the radiative-forcing level (e.g., 2.6, 4.5, 7.0, 8.5). Combined with ssp to build the CMIP6 scenario code (e.g., ssp = 5 and rcp = 8.5 download the ssp585 scenario). If NULL, ssp is assumed to already encode the full scenario (e.g., "585").

ssp

Numeric or character vector of Shared Socioeconomic Pathway families (e.g., 1, 2, 5). Combined with rcp as described above. A complete code such as "585" may also be supplied directly (with rcp = NULL).

...

Additional arguments (currently unused).

Details

Available variables (working synonyms in parentheses):

Temperature

Precipitation

Physical

Bioclimatic

Citation:
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. https://doi.org/10.1002/joc.5086

Value

If 'par_set()' contained a raster/polygon/points with buffer: a 'SpatRaster' stack of processed variables. If 'par_set()' contained spatial points or data.frame of points without buffer: a 'data.frame' of x, y, and extracted values.

Examples


processed <- par_set(country = "Italy", crs = 3035) %>% 
  worldclim(vars = c("tmin", "bio1"), years = "1970-2000")