BioClim: Computation of Bioclimatic Variables

In ErikKusch/KrigR: Downloading, Aggregating, and Kriging of ECMWF CDS-Data

Computation of Bioclimatic Variables

Description

This function queries download of required essential climate variables from the [Climate Data Store](https://cds.climate.copernicus.eu/#!/home) hosted by the [Copernicus Climate Change Service (C3S)](https://cds.climate.copernicus.eu/about-c3s) for retrieval of climate data and subsequent calculation of bioclimatic variables for user-defined regions and time-frames.

Usage

BioClim(
  Temperature_Var = "2m_temperature",
  Temperature_DataSet = "reanalysis-era5-land",
  Temperature_Type = NA,
  Water_Var = "volumetric_soil_water_layer_1",
  Water_DataSet = "reanalysis-era5-land-monthly-means",
  Water_Type = "monthly_averaged_reanalysis",
  Y_start,
  Y_end,
  TZone = "UTC",
  Extent,
  Buffer = 0.5,
  Dir = getwd(),
  FileName,
  FileExtension = ".nc",
  Compression = 9,
  API_User,
  API_Key,
  TChunkSize = 6000,
  TryDown = 10,
  TimeOut = 36000,
  Cores = 1,
  verbose = TRUE,
  Keep_Raw = FALSE,
  Keep_Monthly = FALSE,
  closeConnections = TRUE
)

Arguments

Temperature_Var	CDS-contained climate variable targeting temperature information. Recommended values: "2m_temperature".
Temperature_DataSet	Character. Which dataset to query data from. See currently supported datasets by calling Meta.List. For now, this function is conceptualised to support "reanalysis-era5-land".
Temperature_Type	Either NA or Character. Which kind of sub-type to query per data set. See Meta.QucikFacts for options per dataset.
Water_Var	CDS-contained climate variable targeting water availability information. Recommended values: "volumetric_soil_water_layer_X" (where X is an integer of either 1, 2, 3, 4), "total_precipitation".
Water_DataSet	Character. Which dataset to query water availability data from. See currently supported datasets by calling Meta.List. For now, this function is conceptualised to support "reanalysis-era5-land".
Water_Type	Either NA or Character. Which kind of sub-type to query per water availability data set. See Meta.QucikFacts for options per dataset.
Y_start	Year ('YYYY') at which to start time series of downloaded data.
Y_end	Year ('YYYY') at which to stop time series of downloaded data.
TZone	Character. Time zone in which to represent and evaluate time dimension of data. See the output of OlsonNames() for a full overview of supported specifications. Default is UTC.
Extent	Optional, download data according to desired spatial specification. If missing/unspecified, total area of queried data set is used. Can be specified either as a raster object, an sf object, a terra object, or a data.frame. If Extent is a raster or terra object, data will be queried according to rectangular extent thereof. If Extent is an sf (MULTI-)POLYGON object, this will be treated as a shapefile and the output will be cropped and masked to this shapefile. If Extent is a data.frame of geo-referenced point records, it needs to contain Lat and Lon columns around which a buffered shapefile will be created using the Buffer argument.
Buffer	Optional, Numeric. Identifies how big a circular buffer to draw around points if Extent is a data.frame of points. Buffer is expressed as centessimal degrees.
Dir	Character/Directory Pointer. Directory specifying where to download data to.
FileName	Character. A file name for the produced file.
FileExtension	Character. A file extension for the produced file. Supported values are ".nc" (default) and ".tif" (better support for metadata).
Compression	Integer between 1 to 9. Applied to final .nc file that the function writes to hard drive. Same as compression argument in terra::writeCDF(). Ignored if FileExtension = ".tif".
API_User	Character; ECMWF cds user number.
API_Key	Character; ECMWF cds API key.
TChunkSize	Numeric. Number of layers to bundle in each individual download. Default is 6000 to adhere to most restrictive CDS limits: https://cds.climate.copernicus.eu/live/limits.
TryDown	Optional, numeric. Legacy, ignored when querying data from new CDS (https://cds-beta.climate.copernicus.eu/; this happens when the package version of ecmwfr is >= 2.0.0). How often to attempt the download of each individual file that the function queries from the CDS. This is to circumvent having to restart the entire function when encountering connectivity issues.
TimeOut	Numeric. Legacy, ignored when querying data from new CDS (https://cds-beta.climate.copernicus.eu/; this happens when the package version of ecmwfr is >= 2.0.0). The timeout for each download in seconds. Default 36000 seconds (10 hours).
Cores	Numeric. How many cores to use when carrying out temporal aggregation. Default is 1.
verbose	Logical. Whether to print/message function progress in console or not.
Keep_Raw	Logical. Whether to retain raw downloaded data or not. Default is FALSE.
Keep_Monthly	Logical. Whether to keep monthly netcdf files of raw data aggregated to temporal resolution of months. Default FALSE.
closeConnections	Logical. Whether to close all connections at the end of function execution. When executing this function often after another, this can be very useful to avoid errors.

Value

A SpatRaster object containing the queried bioclimatic data, and a NETCDF (.nc) file in the specified directory.

The SpatRaster contains metadata/attributes as a named vector that can be retrieved with terra::metags(...):

• Citation - A string which to use for in-line citation of the data product obtained with BioClim.

• KrigRCall.X - Arguments passed to the BioClim function that produced the file (API credentials are omitted from these metadata).

Examples

## Not run: 
CN_ext <- terra::rast(system.file("extdata", "CentralNorway.nc", package = "KrigR"))
CN_BC <- BioClim(
  Temperature_Var = "2m_temperature",
  Temperature_DataSet = "reanalysis-era5-land",
  Temperature_Type = NA,
  Water_Var = "volumetric_soil_water_layer_1",
  Water_DataSet = "reanalysis-era5-land-monthly-means",
  Water_Type = "monthly_averaged_reanalysis",
  Y_start = 1970,
  Y_end = 1979,
  TZone = "CET",
  Extent = CN_ext,
  Dir = getwd(),
  FileName = "CN_BC",
  FileExtension = ".nc",
  Compression = 9,
  API_User = API_User,
  API_Key = API_Key,
  TChunkSize = 6000, TryDown = 10, TimeOut = 36000,
  Cores = parallel::detectCores(),
  verbose = TRUE,
  Keep_Raw = FALSE, Keep_Monthly = FALSE
)

## End(Not run)

ErikKusch/KrigR documentation built on Feb. 17, 2025, 2:09 p.m.