Skip to contents

pressurepath_create() combines a tag pressure series with a path and retrieves matching ERA5 variables. Positions during flights are linearly interpolated between stationary periods. pressurepath_create_arco() and pressurepath_create_api() are shortcuts that force the corresponding source.

Usage

pressurepath_create(
  tag,
  path = tag2path(tag),
  variable = c("altitude", "surface_pressure"),
  solar_dep = 0,
  era5_dataset = "single-levels",
  preprocess = FALSE,
  workers = "auto",
  quiet = FALSE,
  debug = FALSE,
  source = c("auto", "arco", "api"),
  altitude_formula = c("virtual", "standard")
)

pressurepath_create_api(
  tag,
  path = tag2path(tag),
  variable = c("altitude", "surface_pressure"),
  solar_dep = 0,
  era5_dataset = "single-levels",
  preprocess = FALSE,
  workers = "auto",
  quiet = FALSE,
  debug = FALSE,
  altitude_formula = "virtual"
)

pressurepath_create_arco(
  tag,
  path = tag2path(tag),
  variable = c("altitude", "surface_pressure"),
  solar_dep = 0,
  era5_dataset = "single-levels",
  preprocess = FALSE,
  quiet = FALSE,
  debug = FALSE,
  altitude_formula = "virtual"
)

Arguments

tag

A GeoPressureR tag object.

path

A GeoPressureR path data.frame. A path with several trajectories (column j, e.g. from graph_simulation()) is computed one trajectory at a time.

variable

ERA5 variables to retrieve, named as in the ERA5 catalogue, plus the derived "altitude". The same names work for every source, but the available set depends on both source and era5_dataset — see pressurepath_variable_available().

solar_dep

Solar depression angle used to compute sunrise and sunset, or NULL to skip this computation.

era5_dataset

ERA5 product: "single-levels" (default), "land", or "both" to use ERA5-Land over land and global ERA5 elsewhere. Keep the default whenever variable includes "altitude"; see the Choosing era5_dataset section.

preprocess

Whether to preprocess pressure with geopressure_map_preprocess().

workers

Number of parallel GeoPressureAPI requests, or "auto".

quiet

Logical to suppress progress messages.

debug

Logical to display request details.

source

Data source: "auto", "arco", or "api".

altitude_formula

Altitude formula: "virtual" (default) uses 2 m virtual temperature and the GPT3 lapse rate (Landskron & Böhm 2018), based on the altitude validation. "standard" uses 2 m temperature and a lapse rate of -6.5 K/km to reproduce previous results.

Value

A pressurepath data.frame containing tag pressure, coordinates, requested ERA5 variables, normalised surface pressure, and optional sunrise and sunset times. The attribute provenance records the source ("arco" or "api"), the ERA5 dataset, the altitude formula, the GeoPressureR version and, for the API, the unique versions of GeoPressureAPI used.

Data sources

source = "arco" reads ECMWF's Analysis-Ready Cloud-Optimised (ARCO) archive directly. It requires an ECMWF API key and the optional Rarr and ecmwfr packages. variable uses the same names as the hosted API, but the archive carries fewer of them: 20 for era5_dataset = "single-levels", 16 for "land", and the 8 they share for "both", plus the derived "altitude". Use pressurepath_variable_available() to list them.

source = "api" uses the hosted GeoPressureAPI. It needs no ECMWF key or Rarr installation and reaches the full Earth Engine band set: 292 variables for era5_dataset = "single-levels" and "both", 70 for "land".

The default, source = "auto", uses ARCO when a key stored by ecmwfr::wf_set_key() is available and GeoPressureAPI otherwise. Use pressurepath_create_arco() or pressurepath_create_api() to select a backend explicitly.

Path and ERA5 processing

Measurements are retained only when path contains the surrounding stationary periods. Coordinates during flights are interpolated linearly, while ERA5 values are sampled at the nearest grid cell and hour. era5_dataset = "single-levels" uses 0.25 degree global ERA5, "land" uses 0.1 degree ERA5-Land, and "both" selects ERA5-Land over land and global ERA5 over water.

Surface pressure is returned in hPa and normalised to the mean tag pressure within each stationary-period and elevation-label group. Observations labelled "discard" are excluded from those means. If solar_dep is not NULL, local sunrise and sunset are added.

Pressure-derived altitude

When altitude is produced, GeoPressureR uses the same barometric relation as GeoPressureAPI: $$z_\mathrm{tag}=z_\mathrm{ERA5}+\frac{T_\mathrm{ERA5}}{L_b}\left[\left( \frac{P_\mathrm{tag}}{P_\mathrm{ERA5}}\right)^{-R L_b/(g M)}-1\right].$$ Here, \(P_\mathrm{tag}\) is tag pressure, while \(P_\mathrm{ERA5}\), \(T_\mathrm{ERA5}\), and \(z_\mathrm{ERA5}\) are ERA5 surface pressure, 2 m temperature, and model-surface elevation. Model-surface elevation is obtained from ERA5 surface geopotential divided by standard gravity. altitude_formula = "virtual" (default) uses the virtual temperature computed from ERA5 2 m dewpoint, and the temperature lapse rate of the GPT3 empirical troposphere model (Landskron & Böhm 2018), a mean, annual and semi-annual cycle on a 1° grid, downloaded once from TU Wien and cached. altitude_formula = "standard" uses 2 m temperature and \(L_b=-0.0065\) K/m. The constants are the universal gas constant \(R=8.31432\) J/(mol K), standard gravity \(g=9.80665\) m/s², and molar mass of dry air \(M=0.0289644\) kg/mol. Pressure is converted to Pa internally and altitude is returned in metres above mean sea level.

Choosing era5_dataset

Use era5_dataset = "single-levels" whenever altitude is computed. It is the default.

ERA5-Land's surface_pressure is not the exact hydrostatic image of the orography ERA5-Land publishes as geopotential — the two disagree by up to ~10 hPa in steep terrain. The \(z_\mathrm{ERA5}\) term therefore fails to cancel from the relation above and the whole discrepancy lands in the retrieved altitude. Measured against 41,653 hourly station-pressure observations from 271 NOAA ISD stations (2–3576 m, Alps, July 2020), compared with surveyed station elevation:

era5_datasetbiasMAERMSE
"single-levels"−0.6 m9.0 m27.4 m
"land" / "both"+2.5 m55.3 m76.9 m

ERA5-Land replays the land component of ERA5 and assimilates no atmospheric observations of its own, so it carries no independent information about absolute altitude. Substituting the orography implied by its own surface pressure removes the error exactly and reproduces "single-levels" to 0.1 m.

"land" and "both" remain supported. They are appropriate for retrieving other variables at 0.1 degree resolution. For altitude, prefer "single-levels" based on the altitude validation.

Accuracy

The altitude validation evaluates the conversion against weather stations, GNSS and Swiss stations with documented barometer heights, and radiosondes, for a perfect pressure reading with era5_dataset = "single-levels" and the default altitude_formula = "virtual":

  • Absolute altitude on the ground is a fixed offset per site: median 2.6 m (p90 11 m), with a temporal scatter (SD) of 3.7 m around it, growing to tens of metres in steep terrain where the 0.25° orography departs from the real one.

  • Altitude changes at one site are therefore more reliable than absolute altitudes.

  • Height above the ground in flight is nearly unbiased (−4 m at 1–1.5 km), but its scatter grows with height (RMSE 20 m at 1–1.5 km and 43 m at 2–3 km). Over the heights birds fly, the mean absolute error is 13.1 m, against 16.4 m with "standard", which places birds too low by 1–1.5% of their height.

The tag's own sensor adds to these: altitude is computed from the raw tag pressure, so an absolute sensor offset of 1 hPa shifts it by about 8 m near the ground.

A note on accumulated variables

total_precipitation, surface_solar_radiation_downwards and surface_thermal_radiation_downwards do not mean the same thing across backends when era5_dataset = "land". GeoPressureAPI serves Earth Engine's ERA5-Land collection, where these bands are overwritten by their *_hourly counterparts and are therefore hourly increments. ARCO serves ECMWF's own ERA5-Land fields, which accumulate from 00 UTC. For era5_dataset = "single-levels" both are hourly and agree. Take the difference between consecutive hours if you need increments from ARCO over land.

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

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- load_interim("18LX", var = "tag")
  path <- load_interim("18LX", var = "path_most_likely")
})

pressurepath <- pressurepath_create(tag, path, quiet = TRUE)

plot_pressurepath(pressurepath)