Skip to contents

Download ERA5 hourly data on pressure levels (doi:10.24381/cds.bd0915c6 ) for each flight of tag and save one NetCDF file per flight, covering the flight hours and the pressure levels flown. These files are then read by edge_add_wind() and graph_add_wind().

More information in the GeoPressureManual.

Usage

tag_download_wind(
  tag,
  extent = tag$param$tag_set_map$extent,
  include_stap_id = NULL,
  variable = c("u_component_of_wind", "v_component_of_wind"),
  file = wind_file_default,
  overwrite = FALSE,
  workers = if (source == "cds") 2 else 6,
  source = c("cds", "gcs"),
  cds_token = lifecycle::deprecated(),
  ...
)

Arguments

tag

a GeoPressureR tag object.

extent

geographical extent of the area for which wind data is downloaded. Vector of length 4 c(xmin, xmax, ymin, ymax) or c(W, E, S, N).

include_stap_id

stationary period identifiers of the start of the flight to download. Default is to download all flights.

variable

ERA5 pressure-level variables to download, using the same names as edge_add_wind(). Available from both sources: "u_component_of_wind", "v_component_of_wind", "temperature", "geopotential", "specific_humidity", "vertical_velocity", "fraction_of_cloud_cover", "specific_cloud_liquid_water_content", "specific_cloud_ice_water_content", "ozone_mass_mixing_ratio" and "potential_vorticity". Only with source = "cds": "relative_humidity", "divergence", "vorticity", "specific_rain_water_content" and "specific_snow_water_content".

file

function returning the path of the wind file of a flight from (1) the stationary period identifier and (2) the tag_id. The default, wind_file_default, gives ./data/wind/{tag_id}/{tag_id}_{stap_id}.nc.

overwrite

logical. If TRUE, file is overwritten.

workers

number of downloads run in parallel. Defaults to 2 for "cds", which rejects more queued requests per account (use 1 if other sessions also request data), and 6 for "gcs", where each download needs about 300 MB of memory.

source

"cds" (default) or "gcs". See Choosing a source.

cds_token

[Deprecated] Enter the API token with ecmwfr::wf_set_key()

...

Arguments passed on to ecmwfr::wf_request_batch

request

nested list with query parameters following the layout as specified on the ECMWF APIs page

user

user (default = "ecmwf") provided by the ECMWF data service, used to retrieve the token set by wf_set_key

transfer

logical, download data TRUE or FALSE (default = TRUE)

path

path were to store the downloaded data

time_out

how long to wait on a download to start (default = 3600 seconds).

retry

polling frequency of submitted request for downloading (default = 30 seconds).

job_name

optional name to use as an RStudio job and as output variable name. It has to be a syntactically valid name.

verbose

show feedback on processing

request_list

a list of requests that will be processed in parallel.

total_timeout

overall timeout limit for all the requests in seconds.

Value

For "cds", the output of ecmwfr::wf_request_batch(); for "gcs", the paths of the files written (invisibly).

Choosing a source

Both sources provide the same ERA5 data and write the same files.

  • "cds" (default) requests one file per flight from the Climate Data Store (CDS) with ecmwfr. It needs an ECMWF key (see below). The CDS queues requests and runs only about 2 at a time per account, so when it is busy a tag can take hours to days.

  • "gcs" reads the public Google ARCO-ERA5 copy of ERA5 on Google Cloud Storage. It needs no key and has no queue, so a tag usually takes minutes. Each hour of each variable is downloaded as one global field (~120 MB), so the time depends on the flight durations and your bandwidth, not on extent. It needs the package Rarr and lacks a few variables (see variable).

Use "gcs" when the CDS is slow, unless you need one of these variables or have a slow connection.

File format

The downloaded data are processed to take less space. Each file keeps only the flight hours. Values are stored as 16-bit integers with scale_factor and add_offset (wind to 0.01 m/s), which NetCDF readers unpack automatically. Variables use the CDS short names, units and attributes, following the CF conventions. Writing the files needs the package ncdf4.

ECMWF API key

ARCO access and CDS downloads use the same ECMWF Personal Access Token. Create an ECMWF account, copy the token from your Climate Data Store profile, accept the dataset licence terms, and store the token once in your system keyring:

ecmwfr::wf_set_key("your-personal-access-token")

Do not put the token in a script or commit it to version control. GeoPressureR retrieves the stored token with ecmwfr::wf_get_key() for all ECMWF-backed functions, including geopressure_timeseries(), pressurepath_create(), and tag_download_wind().

Examples

if (FALSE) {
  tag_download_wind(tag)
  tag_download_wind(tag, source = "gcs")
}