Package 'ag5Tools'

Downloads AgERA5 data from the Copernicus Climate Change Service - Copernicus Climate Data Store

Description

The data is downloaded from Copernicus Climate Change Service (C3S) using the Copernicus Climate Data Store (CDSAPI) Python library https://github.com/ecmwf/cdsapi

This function provides programmatic access to the AgERA5 dataset. For more information about the data license, please visit: https://cds.climate.copernicus.eu/api/v2/terms/static/licence-to-use-copernicus-products.pdf

To download the data you should have a valid CDS account, an CDS API key. Please follow the instructions at: https://cds.climate.copernicus.eu/api-how-to to create a file to store your API key. You do not need to install Python or the cdsapi, Ag5Tools will do it if required.

Usage

ag5_download(
  variable,
  statistic = NULL,
  year,
  month,
  day,
  time = NULL,
  version = "1_1",
  path
)

Arguments

variable	character The variable to be downloaded. See details
statistic	character Only required for some variables. See details for options.
year	numeric (Integer) Year to download. Should be between 1979 - 2022
month	numeric Month to be requested. Use month = "all" download all the months for the requested year.
day	numeric Days of the month for the requested data. Use day = "all" to download all days from requested month
time	Character Only required for "2m_relative_humidity".
version	Character Version 1_1 is currently the default and recommended See details for available options.
path	Character Target folder in an local hardrive e.g. "C:/agera5". The folder should exist and the user should have write permission.

Value

No return value, called for side effects.

AgERA5 variables available for download:

• cloud_cover

• liquid_precipitation_duration_fraction

• snow_thickness_lwe

• solar_radiation_flux

• 2m_temperature

• 2m_dewpoint_temperature

• precipitation_flux

• solid_precipitation_duration_fraction

• snow_thickness

• vapour_pressure

• 10m_wind_speed

• 2m_relative_humidity

Statistics for variable "2m_temperature"

Variable "2m_temperature" requires to indicate at least one of the following options in statistic:

• 24_hour_maximum

• 24_hour_mean

• 24_hour_minimum

• day_time_maximum

• day_time_mean

• night_time_mean

• night_time_minimum

Parameter "time" for Variable "2m_relative_humidity"

Variable "2m_relative_humidity" requires to indicate one of the following options in time:

• 06_00

• 09_00

• 12_00

• 15_00

• 18_00

Variables that require statistic

For the following variables, only "24_hour_mean" statistic is available, but should be explicitly indicated.

• cloud_cover

• snow_thickness_lwe

• 2m_dewpoint_temperature

• snow_thickness

• vapour_pressure

• 10m_wind_speed

Examples

## Not run: 
ag5_download(variable = "2m_temperature",
            statistic = "night_time_minimum",
            day = "all",
            month = "all",
            year = 2015,
            path = "C:/custom_target_folder"
            )
            
## End(Not run)

---

Extract AgERA5 data stored in a local hard drive

Description

Extract data from AgERA5 data files previously downloaded from the Copernicus Climate Data Store. These functions use package 'terra' to read *.nc files and extract the requested data for a given location and dates. If dates is one value it extracts a single observation for the specified variable and location. If dates is a character vector of length == 2, it will extract a time series of the specified variable and location, where the first dates value is the start date and the second the end date.

Usage

ag5_extract(coords, ..., path)

## S3 method for class 'numeric'
ag5_extract(
  coords,
  dates,
  variable,
  statistic = NULL,
  time = NULL,
  celsius = FALSE,
  parallel = TRUE,
  ...,
  path
)

## S3 method for class 'data.frame'
ag5_extract(
  coords,
  lon = "lon",
  lat = "lat",
  start_date = "start_date",
  end_date = "end_date",
  variable,
  statistic = NULL,
  time = NULL,
  celsius = FALSE,
  ncores = NULL,
  ...,
  path
)

Arguments

coords	numeric vector of length = 2 of the form (lon, lat), or a data.frame with required columns
...	Other parameters
path	character The path for the folder containing the AgERA5 files
dates	character The dates for extracting the specified variable, a vector of length 1 extracts a single date, while a vector of length 2 indicates the start and end dates. or the column name in the case of data.frame
variable	character The AgERA5 variable to extract, see details for available options
statistic	character Only for some variables, see details for valid options
time	Only for variable Relative-Humidity-2m, see details for valid options
celsius	logical Only for variables "Temperature-Air-2m" and "2m_dewpoint_temperature".
parallel	logical Use parallel computation to speed-up data processing
lon	character Column name of longitude values in the case of data.frame
lat	character Column name of latitude values in the case of data.frame
start_date	character Column name of start_date values in the case that coords is a data.frame
end_date	character Column name of end_date values in the case that coords is a data.frame
ncores	Number of cores to use with parallel. If NULL and parallel is ON, half the available cores will be used. If TRUE the values are converted from Kelvin to Celsius. Default is FALSE

Value

numeric vector with length equal to the number of dates between first and second date. The returned vecter is a named vector, with requested dates as names. If only one date is provided the function returns a numeric vector with length = 1. If coords is a data.frame, the function returns a list of numeric vectors, each one corresponding to the rows in the input data.frame

Valid variable values

• "Cloud-Cover"

• "Precipitation-Rain-Duration-Fraction"

• "Snow-Thickness-LWE"

• "Solar-Radiation-Flux"

• "Temperature-Air-2m"

• "Dew-Point_Temperature-2m"

• "Precipitation-Flux"

• "Precipitation-Solid-Duration-Fraction"

• "Snow-Thickness"

• "Vapour-Pressure"

• "Wind-Speed-10m"

• "Relative-Humidity-2m"

Valid statistics for variable "Temperature-Air-2m"

• "Max-24h"

• "Mean-24h"

• "Min-24h"

• "Max-Day-Time"

• "Mean-Day-Time"

• "Mean-Night-Time"

• "Min-Night-Time"

Variables that require statistic

For the following variables, only 24 hour mean statistic is available, but should be explicitly indicated as "Mean".

• "Cloud-Cover"

• "Snow-Thickness-LWE"

• "Dew-Point_Temperature-2m"

• "Snow-Thickness"

• "Vapour-Pressure"

• "Wind-Speed-10m"

Valid time values for variable "Relative-Humidity-2m"

• "06h"

• "09h"

• "12h"

• "15h"

• "18h"

References

Temperature conversion is made accordingly to: Preston-Thomas, H. (1990). The International Temperature Scale of 1990 (ITS-90). Metrologia, 27(1), 3-10. doi:10.1088/0026-1394/27/1/002

Examples

## Not run: 
temp <- ag5_extract(coords = c(lon = 35.72636, lat = -2.197162),
                      dates = "1991-04-22",
                      variable = "Temperature-Air-2m",
                      statistic = "Max-Day-Time",
                      path = "C:/temperature_data/")

## End(Not run)

---

Example dataset for the agera5 package

Description

100 points in Arusha, Tanzania The geographic coordinates were generated with the function st_sample from package sf

Usage

arusha_df

Format

An object of class data.frame with 100 rows and 4 columns.

---