Retrieve an ERA5 pressure time series

geopressure_timeseries() retrieves an hourly ERA5 surface-pressure time series at one location. Supply a tag pressure series to also normalise ERA5 pressure and estimate altitude. geopressure_timeseries_arco() and geopressure_timeseries_api() are shortcuts that force the corresponding source.

Usage

geopressure_timeseries(
  lat,
  lon,
  pressure = NULL,
  start_time = NULL,
  end_time = NULL,
  quiet = FALSE,
  debug = FALSE,
  source = c("auto", "arco", "api"),
  era5_dataset = c("land", "single-levels")
)

geopressure_timeseries_api(
  lat,
  lon,
  pressure = NULL,
  start_time = NULL,
  end_time = NULL,
  quiet = FALSE,
  debug = FALSE
)

geopressure_timeseries_arco(
  lat,
  lon,
  pressure = NULL,
  start_time = NULL,
  end_time = NULL,
  quiet = FALSE,
  debug = FALSE,
  era5_dataset = c("land", "single-levels")
)

Arguments

lat: Numeric scalar latitude, between -90 and 90 degrees.
lon: Numeric scalar longitude, between -180 and 180 degrees.
pressure: Optional data.frame with a date-time date column and numeric pressure value column in hPa. Additional columns are retained.
start_time, end_time: Start and end of the requested interval when pressure is NULL.
quiet: Logical to suppress progress messages.
debug: Logical to display request details.
source: Data source: "auto", "arco", or "api".
era5_dataset: ERA5 product used by ARCO: "land" (default) at 0.1 degree resolution or "single-levels" at 0.25 degree resolution. Prefer "single-levels" when pressure is supplied, because altitude is then computed; see the Choosing era5_dataset section. GeoPressureAPI uses its own configuration.

Value

A data.frame containing date, surface_pressure, lat, and lon. With pressure, it also retains the input columns, renames value to pressure_tag, and adds surface_pressure_norm and altitude.

Data sources

source = "arco" reads ECMWF's Analysis-Ready Cloud-Optimised (ARCO) archive directly. It is generally faster for a long time series at one location, supports ERA5-Land and global ERA5, and requires an ECMWF API key plus the optional Rarr and ecmwfr packages.

source = "api" asks the hosted GeoPressureAPI to prepare the data. It needs no ECMWF key or Rarr installation, but depends on that service and supports its fixed ERA5 configuration.

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

ERA5 datasets and matching

With ARCO, era5_dataset = "single-levels" uses global ERA5 on a 0.25 degree grid and retains locations over water. era5_dataset = "land" (the default) uses ERA5-Land on a 0.1 degree grid; it has finer spatial resolution but is masked over oceans, so ocean locations are moved to the closest land cell, and it must not be used when pressure is supplied because altitude is then computed from it (see the Choosing era5_dataset section). GeoPressureAPI chooses its ERA5 data internally and moves ocean locations onshore.

Without pressure, the requested interval is returned hourly. With ARCO and pressure, each tag time is matched to its closest ERA5 hour and restored after matching; no temporal interpolation is used. GeoPressureAPI receives the original tag timestamps and performs the matching remotely.

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. The constants are the standard temperature lapse rate $L_b=-0.0065$ K/m, 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.

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_dataset`	bias	MAE	RMSE
`"single-levels"`	−0.6 m	9.0 m	27.4 m
`"land"` / `"both"`	+2.5 m	55.3 m	76.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 the defaults for backward compatibility. They are appropriate for retrieving other variables at 0.1 degree resolution, and for geopressure_map(), whose pressure mismatch is differential and unaffected.

Accuracy

With era5_dataset = "single-levels" the altitude error separates into two parts that behave very differently. A static per-site offset (median 3.7 m, p90 15 m) reflects station metadata and sub-grid terrain and does not vary in time, while the temporal scatter (median SD 3.1 m, p90 7.7 m) is the actual reanalysis error. Expect roughly 3 m for relative altitude changes at a fixed location and 10 m mean absolute error for absolute altitude, degrading to tens of metres in steep terrain — where it is a fixed offset rather than noise. Precision is nearly independent of flight altitude: de-biased RMSE stays 2–7 m up to 1000 m above the model surface and about 12 m at 1000–3000 m above it.

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.

Pressure normalisation

ERA5 surface pressure is also shifted to the mean tag-pressure level within each elevation-label group. Flight observations (stap_id == 0) and observations labelled "discard" are excluded from the group means. The adjusted series is returned as surface_pressure_norm.

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) {
geopressure_timeseries(
  lat = 46,
  lon = 6,
  start_time = "2020-01-01",
  end_time = "2020-01-02"
)
}