Package 'GeoPressureR'

Description

This function returns a list with the four morphological information necessary to construct the power curve: mass, wing span, wing aspect ratio, and body frontal area.

When any of these variables are missing, we query the AVONET database (doi:10.6084/m9.figshare.16586228.v5) using the scientific name from the Clements Checklist.

Usage

bird_create(
  scientific_name,
  mass = NULL,
  wing_span = NULL,
  wing_aspect = NULL,
  wing_area = NULL,
  body_frontal_area = NULL,
  species_name = lifecycle::deprecated()
)

Arguments

Value

List containing mass, wing span, wing aspect ratio, and body frontal area.

See Also

Other bird: print.bird()

Other movement: graph_set_movement(), plot_graph_movement(), speed2prob(), tag_download_wind()

Examples

# Using AVONET dataset
bird_create("Acrocephalus arundinaceus")

# Using AVONET dataset + custom values
bird_create("Acrocephalus arundinaceus", wing_aspect = 8)

# Import your own bird. You will need mass, and at least two of wing_span,
# wing_aspect or wing_area.
bird_create("Madynuss nutshell", mass = 8, wing_span = 0.2, wing_aspect = 4)

Description

Reads the NetCDF files and extracts the variable requested along each flight defined by the edges.

• Time: linear interpolation using the resolution requested with rounding_interval

• Space: nearest neighbour interpolation by default, or bi-linear with pracma::interp2 if interp_spatial_linear=TRUE. Note: spatial interpolation is limited to 0.1° for computational reasons.

• Pressure/altitude: linear interpolation using the exact pressure values

Usage

edge_add_wind(
  graph,
  edge_s,
  edge_t,
  pressure = NULL,
  variable = c("u_component_of_wind", "v_component_of_wind"),
  rounding_interval = 60,
  interp_spatial_linear = FALSE,
  return_averaged_variable = lifecycle::deprecated(),
  file = function(stap_id, tag_id) {
    
    glue::glue("./data/wind/{tag_id}/{tag_id}_{stap_id}.nc")
 },
  quiet = FALSE
)

Arguments

Value

A data.frame with one row per time step, edge, and variable:

• edge_id edge index

• val value of the variable at each time step

• pressure pressure at each time step

• date datetime of each time step

• w weight for averaging

• var variable name, as passed to variable

• lat latitude at each time step

• lon longitude at each time step

See Also

GeoPressureManual

Examples

## Not run: 
withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    tag_set_map(extent = c(-16, 23, 0, 50), scale = 1) |>
    geopressure_map(quiet = TRUE)
})
graph <- graph_create(tag, quiet = TRUE)
wind <- edge_add_wind(graph, edge_s = graph$s, edge_t = graph$t, quiet = TRUE)

## End(Not run)

Description

For each stationary period (stap_id) with usable twilight events, estimate a single longitude, latitude, and effective zenith angle by minimizing the squared spherical distance to the corresponding iso-zenith small circles.

Each twilight defines a small circle on the Earth: the set of locations at a fixed angular distance (zenith angle) from the subsolar point at that time. The fitted location is the point that is, in a least-squares sense, closest to all those circles simultaneously.

For a stationary period with twilight-specific subsolar points s_i, the fitted longitude lon, latitude lat, and zenith angle z minimize

mean_i ( d((lon, lat), s_i) - z )^2 + P_prior(z)

where ⁠d((lon, lat), s_i)⁠ is the great-circle angular distance from the candidate location to the subsolar point at twilight i. The first term is the mean squared residual to the iso-zenith small circles, normalized by the number of twilight events so its influence does not depend on sample size.

P_prior(z) is an optional Gaussian penalty on the fitted zenith angle:

1/2 * ((z - mu) / sigma)^2

where mu = zenith_prior_mean and sigma = zenith_prior_sd. This acts as a prior on the effective zenith angle while leaving longitude and latitude driven by the twilight geometry.

Usage

geolight_fit_location(
  tag,
  fitted_location_duration = Inf,
  extent = NULL,
  zenith_bounds = c(70, 110),
  zenith_prior_mean = 93,
  zenith_prior_sd = 1.3,
  zenith_prior_penalty_weight = 1e-05,
  compute_known = FALSE,
  quiet = FALSE
)

Arguments

Value

A path data.frame derived from tag$stap with added columns: lon, lat, zenith. Rows where fitting was not possible remain NA.

See Also

Other geolight: geolight_map(), geolight_solar(), plot_twl_calib(), twilight_create(), twilight_label_read(), twilight_label_write()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    twilight_create() |>
    twilight_label_read()
})
tag <- tag_stap_daily(tag, quiet = TRUE)
path <- geolight_fit_location(tag, fitted_location_duration = 5, quiet = TRUE)

Description

This function estimates a likelihood map for each stationary period based on twilight data. The function performs the following steps:

1. Calibrate twilight errors from true known locations and/or automatically fitted calibration locations. See below for details.

2. Compute a likelihood map for each twilight using the calibration.

3. Combine the likelihood maps of all twilights belonging to the same stationary periods with a log-linear pooling. See GeoPressureManual | Probability aggregation for more information on probability aggregation using log-linear pooling.

Usage

geolight_map(
  tag,
  twl_calib_adjust = 1.4,
  fitted_location_duration = Inf,
  zenith_prior_mean = 93,
  zenith_prior_sd = 1.3,
  zenith_prior_penalty_weight = 1e-05,
  refine_fitted_location_scale = 20,
  refine_fitted_location_max_iter = 2,
  twl_llp = function(n) log(n)/n,
  compute_known = FALSE,
  keep_twl = FALSE,
  quiet = FALSE
)

geolight_map_aggregate(
  tag,
  compute_known = FALSE,
  twl_llp = function(n) log(n)/n,
  keep_twl = FALSE,
  quiet = FALSE
)

geolight_map_calibrate(
  tag,
  twl_calib_adjust = 1.4,
  fitted_location_duration = Inf,
  zenith_prior_mean = 93,
  zenith_prior_sd = 1.3,
  zenith_prior_penalty_weight = 1e-05,
  refine_fitted_location_scale = 20,
  refine_fitted_location_max_iter = 2,
  quiet = FALSE
)

geolight_map_likelihood(tag, compute_known = FALSE, quiet = FALSE)

Arguments

Value

a tag with the likelihood of light as tag$map_light

Calibration

Calibration can be based on:

• a known location for at least one stationary period (set via tag_set_map(known = ...)), and/or

• an automatically fitted calibration location (enabled via fitted_location_duration).

When fitted_location_duration is finite, stationary periods at least as long as this threshold and without known coordinates can be fitted from twilight geometry and used as calibration locations. If known locations are also present, the calibration combines the known and fitted locations. The fitted-location step uses a weak Gaussian prior on the effective zenith angle, controlled by zenith_prior_mean, zenith_prior_sd, and zenith_prior_penalty_weight.

After the initial fitted-location estimate, refine_fitted_location_max_iter > 0 optionally refines automatically fitted calibration anchors by iteratively recalibrating the twilight-error distribution for the same stationary period and moving the anchor to the local light-likelihood mode. This is a calibration-anchor refinement, not a separate movement estimator. It is only applied to fitted calibration locations; true known locations are kept fixed. Refined fitted anchors have zenith set to NA because the initial fitted zenith no longer corresponds to the refined coordinates. The default is 2 iterations.

Instead of calibrating the twilight errors in terms of duration, we directly model the zenith angle error. We use a kernel distribution to fit the zenith angle during the known stationary period(s). The twl_calib_adjust parameter allows to manually adjust how smooth you want the fit of the zenith angle to be. Because the zenith angle error model is fitted with data from the calibration site only, and we are using it for all locations of the bird’s journey, it is safer to assume a broader/smoother distribution.

See Also

Other geolight: geolight_fit_location(), geolight_solar(), plot_twl_calib(), twilight_create(), twilight_label_read(), twilight_label_write()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  # Read geolocator data and set map parameters
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    tag_set_map(
      extent = c(-16, 23, 0, 50),
      scale = 10,
      known = data.frame(
        stap_id = 1,
        known_lon = 17.05,
        known_lat = 48.9
      )
    ) |>
    twilight_create() |>
    twilight_label_read()
})

# Visualize twilights
plot(tag, type = "twilight")

# Calibrate twilight to zenith angle and visualize
tag <- geolight_map_calibrate(tag)
plot_twl_calib(tag)

# Compute likelihood for each twilight and visualize
tag <- geolight_map_likelihood(tag)
plot(tag, type = "map_light_twl")

# Aggregate twilights to stationary periods and visualize
tag <- geolight_map_aggregate(tag, quiet = TRUE)
plot(tag, type = "map_light")

Description

Compute solar zenith angles from time and location using the formulation implemented in the NOAA Solar Calculator, itself based on the astronomical algorithms of Meeus.

Usage

geolight_solar(date, lat, lon)

Arguments

Details

The computation is split internally into three steps:

1. geolight_solar_constants(): Time-only solar quantities (solar time and declination)

2. geolight_solar_zenith(): Geometric solar zenith angle

3. geolight_solar_refracted(): Approximate atmospheric refraction correction

Conventions

• lon is expressed in degrees east (positive eastward).

• lat is expressed in degrees north.

• All angles are in degrees unless stated otherwise.

• date is provided as POSIXct and internally converted to Julian day.

When lat and lon are vectors, the result is a 3-D array with dimensions:

c(length(lat), length(lon), length(date))

When lat and lon are scalars, the result reduces to a vector of length length(date).

Solar time and hour angle

Internally, the solar time is computed as NOAA's true solar time expressed as an angle (degrees) at Greenwich, without longitude adjustment. Longitude enters later through the hour angle:

hour_angle = solar_time + lon - 180

Values are intentionally not wrapped to ⁠[0, 360)⁠ because all downstream trigonometric functions are periodic.

Atmospheric refraction

Atmospheric refraction is applied using NOAA's standard piecewise approximation as a function of solar elevation. This correction is approximate and does not account for local pressure or temperature.

Value

Solar zenith angle(s) in degrees, corrected for atmospheric refraction.

References

NOAA Global Monitoring Laboratory. Solar Calculation Details. https://gml.noaa.gov/grad/solcalc/calcdetails.html

Meeus, J. (1998). Astronomical Algorithms. Willmann-Bell.

See Also

Other geolight: geolight_fit_location(), geolight_map(), plot_twl_calib(), twilight_create(), twilight_label_read(), twilight_label_write()

Examples

date <- as.POSIXct(
  c("2020-06-21 12:00:00", "2020-12-21 12:00:00"),
  tz = "UTC"
)
z <- geolight_solar(date, lat = 46, lon = 6)
z

Description

GeoLightViz is an interactive tool for reviewing twilight observations and preparing light-based geolocation analyses. It displays the light record and detected twilight events so that observations affected by shading or other light obstructions can be marked as discarded. It can also be used to define or edit stationary periods from twilight patterns, which is useful when pressure or acceleration data are unavailable. When a map has been defined with tag_set_map() and stationary periods are available, the app links the light plot to a map of twilight likelihoods. You can explore candidate locations and tune twilight calibration and likelihood aggregation settings with visual feedback. Twilight labels and stationary periods can be saved or exported from the app.

Usage

geolightviz(
  x,
  stapath = NULL,
  launch_browser = TRUE,
  run_bg = TRUE,
  quiet = FALSE,
  ...
)

Arguments

Details

See the GeoLightViz chapter of the GeoPressureManual for an overview of the app's controls and workflow.

Value

When run_bg = TRUE, an invisible callr r_process running the app. When run_bg = FALSE, the return value of shiny::runApp().

Basemap API keys

Interactive maps always offer Esri basemaps (gray canvas, imagery and topographic). CARTO, Mapbox and MapTiler basemaps are added to the layer control only when their API key is stored in your system keyring. Get a key from each provider:

• CARTO: "Get your API key" on CARTO Basemaps.

• Mapbox: Access tokens page of your account (see Mapbox documentation).

• MapTiler: API keys page of your MapTiler Cloud account (see MapTiler documentation).

Then store each key once:

keyring::key_set_with_value("CARTO_API_KEY", password = "<your CARTO API key>")
keyring::key_set_with_value("MAPBOX_ACCESS_TOKEN", password = "<your Mapbox token>")
keyring::key_set_with_value("MAPTILER_API_KEY", password = "<your MapTiler API key>")

Mapbox access tokens are visible in the browser when a map is rendered. Use a public, read-only token rather than a secret token.

See Also

GeoPressureManual | GeoLightViz

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    twilight_create() |>
    twilight_label_read()
})
geolightviz(tag, run_bg = FALSE, launch_browser = FALSE)

Description

The geopressure_map() function computes a likelihood map for each stationary period based on pressure measurements. It is a wrapper of the following two child functions:

1. geopressure_map_mismatch() computes the mismatch maps between the pressure sensor measurements and the ERA5 reanalysis database.

2. geopressure_map_likelihood() converts the mismatch maps into a likelihood map.

See below for details. For more background on the method behind these functions, please refer to Nussbaumer et al. (2023a; doi:10.1111/2041-210X.14043).

Usage

geopressure_map(
  tag,
  max_sample = 250,
  margin = 30,
  sd = 1,
  thr_mask = 0.9,
  log_linear_pooling_weight = function(n) log(n)/n,
  timeout = 300,
  workers = "auto",
  era5_dataset = "land",
  keep_mask = FALSE,
  keep_mse = FALSE,
  compute_known = FALSE,
  debug = FALSE,
  quiet = FALSE
)

geopressure_map_likelihood(
  tag,
  sd = 1,
  log_linear_pooling_weight = function(n) log(n)/n,
  keep_mse = TRUE
)

geopressure_map_mismatch(
  tag,
  max_sample = 250,
  margin = 30,
  thr_mask = 0.9,
  timeout = 300,
  workers = "auto",
  era5_dataset = "land",
  compute_known = FALSE,
  keep_mask = TRUE,
  debug = FALSE,
  quiet = FALSE
)

Arguments

Details

A map will only be computed for the stationary periods included in tag$stap$include and without a known position ⁠tag$stap$known_l**⁠ as defined by tag_set_map(). At known stationary periods, the likelihood map is a map of 0s with a single 1 at the pixel closest to the known position.

Value

Returns the same GeoPressureR tag object including the GeoPressureR map object tag$map_pressure containing the likelihood map of each stationary period. See map_create() for details. If keep_mask and keep_mse are each true, tag also includes the tag$map_pressure_mse and tag$map_pressure_mask maps, as well as tag$stap$nb_sample, indicating the number of datapoints used to compute the MSE.

Mismatch map with GeoPressureAPI

geopressure_map_mismatch() computes the mismatch maps on Google Earth Engine via the map entry point of the GeoPressure API. This consists of the following steps:

1. Pre-process pressure: the pressure measurements are first smoothed and downscaled to a 1-hour resolution in order to match ERA-5 resolution (see geopressure_map_preprocess()).

2. Generate requests: Send a single request to the GeoPressureAPI to generate the Google Earth Engine (GEE) URLs, one for each elevation/stationary period which can be used to compute the maps on the GEE server.

3. Send the requests: Call the URLs, which will start the computation on the GEE server. At this step, it does not wait for an answer, but sends the requests in parallel to be faster.

4. Compute and download the maps: When all requests are sent, we wait for the GEE server to return a geotiff file (map) for each elevation/ stationary period.

5. Post-process maps: Read these geotiff maps as matrix, create the corresponding GeoPressureR map object with create_map().

The following two maps are returned for each stationary period:

1. map_pressure_mse: The Mean Square Error (MSE) between the data logger pressure time series and the reanalysis. The mean error is removed because we assume no specific altitude of the geolocator, thus allowing an altitudinal shift of the pressure time series.

2. map_pressure_mask (optionally): The mask of the proportion of pressure measurements corresponding to altitude values found within the min and max ground elevation at each location. The altitude value of the geolocator pressure time series is computed with the barometric formula accounting for the temporal variation of pressure (surface-pressure) and temperature (2m-temperature) based on ERA5 data. The min and max ground elevation of each pixel is computed from SRTM-90. This map is only returned if keep_mask is TRUE.

For more details, read the GeoPressure API documentation .

Elevation levels

It is possible to indicate different elevation levels when the bird was spending time at locations with different elevations within a general area (~10km), and thus within the same stationary period. This can be done by using tag$label="elev_x" for all measurements of the same elevation level x. See more information on the labelling of elevation levels in the corresponding section in the GeoPressureManual.

Behind the scene, each of these elevation levels produces a new request on the GeoPressureAPI. The mismatch maps of all elevation levels belonging to the same stationary periods are combined (as a weighted average) to result in a single mismatch map per stationary period.

Convert mismatch map into likelihood map

We convert the map of the mean square error $\mathrm{MSE}$ and altitude mask $z_\mathrm{mask}$ computed by geopressure_map_mismatch() into a likelihood map with,

$L = \left( \frac{1}{2 \pi \sigma^2}\right)^{n w/2} \exp \left(-w n \frac{\mathrm{MSE}}{2\sigma^2} \right) \left[z_\mathrm{mask}>T \right],$

where $\sigma$ is the standard deviation (sd) of pressure and $T$ is the mask threshold (thr_mask).

Because the auto-correlation of the time series is not accounted for in this equation, we use a log-linear pooling weight of $w=\log(n)/n$ by default, where $n$ is the number of samples in the time series (i.e., data points used to compute the MSE). See GeoPressureManual | Probability aggregation for details.

Important Note: Since GeoPressure v3.1.0, the threshold of the mask is happening directly on the GEE server (i.e., during geopressure_map_mismatch()). This allows to compute the MSE only for pixels which are within the threshold, thus reducing the computational cost significantly.

References

Nussbaumer, Raphaël, Mathieu Gravey, Martins Briedis, and Felix Liechti. 2023. Global Positioning with Animal‐borne Pressure Sensors. Methods in Ecology and Evolution, 14, 1118–1129 doi:10.1111/2041-210X.14043.

See Also

GeoPressureManual

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    tag_set_map(
      extent = c(-16, 23, 0, 50),
      scale = 4
    )
})

tag <- geopressure_map_mismatch(tag,
  max_sample = 50,
  margin = 20,
  thr_mask = 0.95,
  keep_mask = TRUE,
  quiet = TRUE
)

plot(tag, type = "map_pressure_mse", plot_leaflet = FALSE)

plot(tag, type = "map_pressure_mask", plot_leaflet = FALSE)

tag <- geopressure_map_likelihood(tag,
  sd = 1,
  log_linear_pooling_weight = function(n) log(n) / n
)

plot(tag, type = "map_pressure")

Description

Performs the following pre-processing for the pressure data.frame:

1. Remove discarded and flight pressure measurements.

2. Group pressure measurements by stationary period and elevation level.

3. Smooth and downscale pressure to a 1 hour resolution to match ERA5 data.

This function is used within geopressure_map_mismatch() but can be useful to check the pressure data sent to the GeoPressureAPI.

Usage

geopressure_map_preprocess(tag, compute_known = FALSE)

Arguments

Value

Pressure data.frame without flight and discarded values, on a 1 hour resolution.

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |> tag_label(quiet = TRUE)
})

pressure_processed <- geopressure_map_preprocess(tag)
str(pressure_processed)

# Plotting pressure displays the raw data (in grey) with the processed data from
# `geopressure_map_preprocess` (as coloured line)
plot_tag_pressure(tag)

Description

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

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-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().

See Also

Other pressurepath: plot_pressurepath(), pressurepath_create(), pressurepath_variable_available()

Examples

geopressure_timeseries(
  lat = 46,
  lon = 6,
  start_time = "2020-01-01",
  end_time = "2020-01-02"
)

Description

GeoPressureR is a R package which help researchers determine the position of a bird based on the data retrieved from multi-sensor geolocators.

Details

The main novelty of this package is to match atmospheric pressure measurements to weather reanalysis database (ERA-5) and produce a probability maps of position.

In addition, we use a graphical model to combine pressure, light, acceleration and windspeed data into a trajectory model of the bird.

Author(s)

Maintainer: Raphaël Nussbaumer [email protected] (ORCID) [copyright holder]

Authors:

• Raphaël Nussbaumer [email protected] (ORCID) [copyright holder]

• Mathieu Gravey [email protected] (ORCID)

See Also

Useful links:

• https://github.com/GeoPressure/GeoPressureR

• https://geopressure.org/GeoPressureR/

• Report bugs at https://github.com/GeoPressure/GeoPressureR/issues

Description

The geopressuretemplate() function manages the complete workflow for modelling bird trajectories using geolocator data. It includes the creation tag object, the construction of the likelihood maps (pressure and/or light), the creation of the graph model construction, and, finally, the estimation of the trajectory products and the pressure path computation. Read the Workflow chapter in the GeoPressureManual for more information.

Usage

geopressuretemplate(
  id,
  config = config::get(config = id),
  quiet = FALSE,
  file = glue::glue("./data/interim/{id}.RData"),
  ...
)

geopressuretemplate_config(
  id,
  config = config::get(config = id),
  assert_tag = TRUE,
  assert_graph = FALSE,
  ...
)

geopressuretemplate_graph(
  id,
  config = config::get(config = id),
  quiet = FALSE,
  file = glue::glue("./data/interim/{id}.RData"),
  ...
)

geopressuretemplate_pressurepath(
  id,
  config = config::get(config = id),
  quiet = FALSE,
  file = glue::glue("./data/interim/{id}.RData"),
  ...
)

geopressuretemplate_tag(
  id,
  config = config::get(config = id),
  quiet = FALSE,
  file = glue::glue("./data/interim/{id}.RData"),
  ...
)

Arguments

Details

The geopressuretemplate function is a high-level entry point that coordinates multiple steps for processing the geolocator data and produce trajectories. It relies on underlying child functions for each step:

• Tag Creation geopressuretemplate_tag(): Initializes and labels the tag object. It also generates light and pressure likelihood maps:

1. tag_create(): Initializes the tag object.

2. tag_label(): Adds labels.

3. tag_set_map(): Sets the spatial and temporal parameters.

4. If "map_pressure" is in the config$geopressuretemplate$likelihood:

   • geopressure_map(): Computes the pressure likelihood.

5. If "map_light" is in the config$geopressuretemplate$likelihood:

   • twilight_create() |> twilight_read() |> geolight_map(): Computes the light likelihood.

• Graph Creation geopressuretemplate_graph(): Builds a movement model graph based tag data, and can include wind effects if specified. Outputs such as marginal distributions, most likely paths, and simulation paths can be computed.

1. graph_create(): Creates the graph based on tag.

2. If config$graph_set_movement$type == "gs" (i.e., no wind):

   • graph_set_movement(): Sets the movement model without wind.

3. If config$graph_set_movement$type == "as" (i.e., with wind):

   • graph_add_wind(): Adds wind data to the graph.

   • graph_set_movement(): Sets the movement model with wind.

4. If "marginal" is in config$geopressuretemplate$outputs:

   • graph_marginal(): Computes the marginal distribution map.

5. If "most_likely" is in config$geopressuretemplate$outputs:

   • graph_most_likely(): Computes the most likely path based on the movement model.

6. If "simulation" is in config$geopressuretemplate$outputs:

   • graph_simulation(): Runs simulations to model multiple possible paths.

7. save(): Saves the computed graph and associated objects in ⁠data/interim/{id}.Rdata⁠

• Pressure Path Processing geopressuretemplate_pressurepath(): Computes pressurepaths (pressurepath_create) using the content of the Rdata file and appending the pressurepath data.frame to the same file.

1. If "most_likely" is in config$geopressuretemplate$pressurepath, computes the pressure path for path_most_likely.

2. If "geopressureviz" is in config$geopressuretemplate$pressurepath computes the pressure path for path_geopressureviz

Each of these child functions can be called individually or automatically as part of the geopressuretemplate workflow.

Value

The function returns nothing. Instead, it saves the processed outputs (tag, graph, pressure paths, etc.) to the specified file.

See Also

GeoPressureManual

Examples

# Run the complete geopressuretemplate workflow
geopressuretemplate("18LX")

# Overwrite parameters passed through ...
geopressuretemplate("18LX",
  tag_set_map = list(scale = 2),
  geopressure_map = list(max_sample = 100, margin = 20)
)

# Or run step-by-step
# you can check that all the parameters are correctly set in the config file
geopressuretemplate_config(id)
# 1. creation of the tag
tag <- geopressuretemplate_tag("18LX")
# 2. creation of the graph
geopressuretemplate_graph("18LX")
# 3. Computation of the pressurepath
geopressuretemplate_pressurepath("18LX")

Description

GeoPressureViz is an interactive app to inspect and manually edit migration paths together with the underlying map likelihoods and pressure time series by stationary period. It is useful to compare pressure-, light- and distance-based information before finalizing a path.

The app can start from a tag object already in memory, or from an interim .RData/.rda file that contains at least tag (and optionally marginal, path_most_likely, pressurepath, pressurepath_most_likely).

When run_bg = FALSE, the app stores the current edited path in the Shiny option path_geopressureviz and returns it invisibly when the app closes. You can capture it from the return value of this function or retrieve it afterwards in the same R session with shiny::getShinyOption("path_geopressureviz").

When run_bg = TRUE, the function returns the background process object instead of the edited path.

The app Save button writes the current path to ./data/interim/{id}-path-geopressureviz.csv.

Learn more about GeoPressureViz in the GeoPressureManual .

Usage

geopressureviz(
  x,
  path = NULL,
  marginal = NULL,
  launch_browser = TRUE,
  run_bg = TRUE
)

Arguments

Value

When run_bg = FALSE: The edited path, returned invisibly when the app closes. During the app session, the current path is also stored in the Shiny option shiny::getShinyOption("path_geopressureviz"), which can be read afterwards in the same R session. When run_bg = TRUE: The background process object. In this case the edited path is not returned to the calling console session.

Basemap API keys

Interactive maps always offer Esri basemaps (gray canvas, imagery and topographic). CARTO, Mapbox and MapTiler basemaps are added to the layer control only when their API key is stored in your system keyring. Get a key from each provider:

• CARTO: "Get your API key" on CARTO Basemaps.

• Mapbox: Access tokens page of your account (see Mapbox documentation).

• MapTiler: API keys page of your MapTiler Cloud account (see MapTiler documentation).

Then store each key once:

keyring::key_set_with_value("CARTO_API_KEY", password = "<your CARTO API key>")
keyring::key_set_with_value("MAPBOX_ACCESS_TOKEN", password = "<your Mapbox token>")
keyring::key_set_with_value("MAPTILER_API_KEY", password = "<your MapTiler API key>")

Mapbox access tokens are visible in the browser when a map is rendered. Use a public, read-only token rather than a secret token.

See Also

GeoPressureManual

Examples

geopressureviz("18LX")

Description

Reads the NetCDF files downloaded and interpolate the average windspeed experienced by the bird on each possible edge, as well as the corresponding airspeed.

In addition, the graph can be further pruned based on a threshold of airspeed thr_as.

See section 2.2.4 in Nussbaumer (2023b) for more technical details and the GeoPressureManual for an illustration on how to use it.

Usage

graph_add_wind(graph, thr_as = Inf, variable = lifecycle::deprecated(), ...)

Arguments

Value

A graph object with windspeed and airspeed as ws and as respectively.

References

Nussbaumer, Raphaël, Mathieu Gravey, Martins Briedis, Felix Liechti, and Daniel Sheldon. 2023. Reconstructing bird trajectories from pressure and wind data using a highly optimized hidden Markov model. Methods in Ecology and Evolution, 14, 1118–1129 doi:10.1111/2041-210X.14082.

See Also

GeoPressureManual

Other graph: graph_create(), graph_marginal(), graph_most_likely(), graph_set_movement(), graph_simulation(), print.graph()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    tag_set_map(extent = c(-16, 23, 0, 50), scale = 1) |>
    geopressure_map(quiet = TRUE)
})
graph <- graph_create(tag, quiet = TRUE)
graph <- graph_add_wind(graph, pressure = tag$pressure, quiet = TRUE)

Description

This function check the condition of a graph object.

Usage

graph_assert(graph, condition = "graph")

Arguments

Value

logical indicating whether the graph object fulfil the condition.

Examples

graph_assert(graph, "movement")

Description

This function returns a trellis graph representing the trajectory of a bird based on filtering and pruning the likelihood maps provided.

In the final graph, we only keep the likely nodes (i.e., position of the bird at each stationary periods) defined as (1) those whose likelihood value are within the threshold of percentile thr_likelihood of the total likelihood map and (2) those which are connected to at least one edge of the previous and next stationary periods requiring an average ground speed lower than thr_gs (in km/h).

For more details and illustration, see section 2.2 of Nussbaumer et al. (2023b) and the GeoPressureManual

Usage

graph_create(
  tag,
  thr_likelihood = 0.99,
  thr_gs = 150,
  likelihood = NULL,
  quiet = FALSE,
  geosphere_dist = lifecycle::deprecated(),
  geosphere_bearing = lifecycle::deprecated(),
  workers = lifecycle::deprecated()
)

Arguments

Value

Graph as a list

• s: source node (index in the 3d grid lat-lon-stap)

• t: target node (index in the 3d grid lat-lon-stap)

• gs: average ground speed required to make that transition (km/h) as complex number representing the E-W as real and S-N as imaginary

• obs: observation model, corresponding to the normalized likelihood in a 3D matrix of size sz

• sz: size of the 3d grid lat-lon-stap

• stap: data.frame of all stationary periods (same as tag$stap)

• equipment: node(s) of the first stap (index in the 3d grid lat-lon-stap)

• retrieval: node(s) of the last stap (index in the 3d grid lat-lon-stap)

• mask_water: logical matrix of water-land

• param: list of parameters including thr_likelihood and thr_gs (same as tag$param)

References

Nussbaumer, Raphaël, Mathieu Gravey, Martins Briedis, Felix Liechti, and Daniel Sheldon. 2023. Reconstructing bird trajectories from pressure and wind data using a highly optimized hidden Markov model. Methods in Ecology and Evolution, 14, 1118–1129 doi:10.1111/2041-210X.14082.

See Also

GeoPressureManual

Other graph: graph_add_wind(), graph_marginal(), graph_most_likely(), graph_set_movement(), graph_simulation(), print.graph()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    twilight_create() |>
    twilight_label_read() |>
    tag_set_map(
      extent = c(-16, 23, 0, 50),
      known = data.frame(stap_id = 1, known_lon = 17.05, known_lat = 48.9)
    ) |>
    geopressure_map(quiet = TRUE) |>
    geolight_map(quiet = TRUE)
})

# Create graph
graph <- graph_create(tag, thr_likelihood = 0.95, thr_gs = 100, quiet = TRUE)

print(graph)

Description

Compute the marginal probability map from a graph. The computation uses the forward backward algorithm. For more details, see section 2.3.2 of Nussbaumer et al. (2023b) and the GeoPressureManual.

Usage

graph_marginal(graph, quiet = FALSE)

Arguments

Value

A list of the marginal maps for each stationary period (even those not modelled). Best to include within tag.

References

Nussbaumer, Raphaël, Mathieu Gravey, Martins Briedis, Felix Liechti, and Daniel Sheldon. 2023. Reconstructing bird trajectories from pressure and wind data using a highly optimized hidden Markov model. Methods in Ecology and Evolution, 14, 1118–1129 doi:10.1111/2041-210X.14082.

See Also

GeoPressureManual

Other graph: graph_add_wind(), graph_create(), graph_most_likely(), graph_set_movement(), graph_simulation(), print.graph()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    twilight_create() |>
    twilight_label_read() |>
    tag_set_map(
      extent = c(-16, 23, 0, 50),
      known = data.frame(stap_id = 1, known_lon = 17.05, known_lat = 48.9)
    ) |>
    geopressure_map(quiet = TRUE) |>
    geolight_map(quiet = TRUE)
})

# Create graph
graph <- graph_create(tag, quiet = TRUE)

# Define movement model
graph <- graph_set_movement(graph)

# Compute marginal
marginal <- graph_marginal(graph)

plot(marginal)

Description

Compute the trajectory which maximizes the joint probability using the Viterbi algorithm on the graph structure. For more details, see section 2.3.1 of Nussbaumer et al. (2023b) and the GeoPressureManual.

Usage

graph_most_likely(graph, quiet = FALSE)

Arguments

Value

Path data.frame containing the columns -stap_id stationary period

• j unique ID for each path, here always 1 as there is a single path.

• ind indices of the coordinate in the 2D grid. Useful to retrieve map or graph information

• lat latitude,

• lon longitude

• start datetime of the start of the stationary period (same as in stap)

• end datetime of the end of the stationary period (same as in stap)

• include logical if stationary period was modelled (same as in stap)

References

Nussbaumer, Raphaël, Mathieu Gravey, Martins Briedis, Felix Liechti, and Daniel Sheldon. 2023. Reconstructing bird trajectories from pressure and wind data using a highly optimized hidden Markov model. Methods in Ecology and Evolution, 14, 1118–1129 doi:10.1111/2041-210X.14082.

See Also

GeoPressureManual

Other graph: graph_add_wind(), graph_create(), graph_marginal(), graph_set_movement(), graph_simulation(), print.graph()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    twilight_create() |>
    twilight_label_read() |>
    tag_set_map(
      extent = c(-16, 23, 0, 50),
      known = data.frame(stap_id = 1, known_lon = 17.05, known_lat = 48.9)
    ) |>
    geopressure_map(quiet = TRUE) |>
    geolight_map(quiet = TRUE)
})

# Create graph
graph <- graph_create(tag, quiet = TRUE)

# Define movement model
graph <- graph_set_movement(graph)

# Compute most likely path
path_most_likely <- graph_most_likely(graph, quiet = TRUE)

plot_path(path_most_likely)

Description

Configure the movement model of a graph by defining the value of the parameters needed to build the transition graph_transition() through speed2prob().

Three methods are currently implemented with two parametric function "gamma" and "logis" suitable when wind data is not available and are thus defining the probability of a groundspeed.

If wind data is available, it is recommended to use the "power" method which rely on the power curve equation (energy vs airspeed) to estimate the probability of an airspeed. Read more about this approach in section 2.2.5. of Nussbaumer et al. (2023b)

Usage

graph_set_movement(
  graph,
  type = ifelse("ws" %in% names(graph), "as", "gs"),
  method = ifelse("ws" %in% names(graph), "power", "gamma"),
  shape = 7,
  scale = 7,
  location = 40,
  bird = NULL,
  power2prob = function(power) (1/power)^3,
  low_speed_fix = 15,
  zero_speed_ratio = 1
)

Arguments

Value

Graph list with a new list graph$movement storing all the parameters needed to compute the transition probability

References

Nussbaumer, Raphaël, Mathieu Gravey, Martins Briedis, Felix Liechti, and Daniel Sheldon. 2023. Reconstructing bird trajectories from pressure and wind data using a highly optimized hidden Markov model. Methods in Ecology and Evolution, 14, 1118–1129 doi:10.1111/2041-210X.14082.

See Also

Other graph: graph_add_wind(), graph_create(), graph_marginal(), graph_most_likely(), graph_simulation(), print.graph()

Other movement: bird_create(), plot_graph_movement(), speed2prob(), tag_download_wind()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    twilight_create() |>
    twilight_label_read() |>
    tag_set_map(
      extent = c(-16, 23, 0, 50),
      known = data.frame(stap_id = 1, known_lon = 17.05, known_lat = 48.9)
    ) |>
    geopressure_map(quiet = TRUE) |>
    geolight_map(quiet = TRUE)
})

graph <- graph_create(tag, quiet = TRUE)

graph <- graph_set_movement(graph,
  method = "gamma",
  shape = 4,
  scale = 6,
  low_speed_fix = 10
)
plot_graph_movement(graph)

graph <- graph_set_movement(graph,
  method = "logis",
  shape = 4,
  location = 60,
  low_speed_fix = 10
)
plot_graph_movement(graph)

Description

This function randomly simulates multiple trajectories from a graph using the forward filtering backward sampling algorithm. For more details, see section 2.3.3 of Nussbaumer et al. (2023b) and the GeoPressureManual.

Usage

graph_simulation(graph, nj = 10, quiet = FALSE)

Arguments

Value

Path data.frame containing the columns -stap_id stationary period

• j unique ID for each simulation.

• ind indices of the coordinate in the 2D grid. Useful to retrieve map or graph information

• lat latitude,

• lon longitude

• start datetime of the start of the stationary period (same as in stap)

• end datetime of the end of the stationary period (same as in stap)

• include logical if stationary period was modelled (same as in stap)

References

Nussbaumer, Raphaël, Mathieu Gravey, Martins Briedis, Felix Liechti, and Daniel Sheldon. 2023. Reconstructing bird trajectories from pressure and wind data using a highly optimized hidden Markov model. Methods in Ecology and Evolution, 14, 1118–1129 doi:10.1111/2041-210X.14082.

See Also

GeoPressureManual

Other graph: graph_add_wind(), graph_create(), graph_marginal(), graph_most_likely(), graph_set_movement(), print.graph()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    twilight_create() |>
    twilight_label_read() |>
    tag_set_map(
      extent = c(-16, 23, 0, 50),
      known = data.frame(stap_id = 1, known_lon = 17.05, known_lat = 48.9)
    ) |>
    geopressure_map(quiet = TRUE) |>
    geolight_map(quiet = TRUE)
})

# Create graph
graph <- graph_create(tag, quiet = TRUE)

# Define movement model
graph <- graph_set_movement(graph)

# Compute simulations
path_simulation <- graph_simulation(graph, quiet = TRUE)

plot_path(path_simulation, plot_leaflet = FALSE)

Description

Loads one or more objects from an interim .RData file created during the GeoPressure analysis. This is a convenience function to quickly restore saved objects (e.g., tag, graph, path_most_likely) for a given tag id or directly from a file path.

Usage

load_interim(
  x,
  var = NULL,
  var_optional = NULL,
  envir = parent.frame(),
  verbose = FALSE
)

Arguments

Value

If no selection is requested (var and var_optional both NULL), invisibly returns the character vector of object names loaded (as in base::load()). Otherwise, if a single object name is requested, invisibly returns that object; if multiple names are requested, invisibly returns a named list of those objects.

Examples

load_interim("18LX", var = c("tag", "graph"))

Description

This function creates a water mask for maps with geolight_map already run. The mask is based on coastline data from Natural Earth and is stored as map$mask_water as a boolean matrix where TRUE indicates water and FALSE indicates land.

A pixel is marked as land if any land exists within it (using the conservative touches=TRUE approach in rasterization), which is important for detecting small islands; the mask then flags the remaining pixels as water.

Usage

map_add_mask_water(map, ne_scale = "medium", land_threshold = 0)

Arguments

Details

The coastline data is rasterized to match the map's grid (defined by extent and scale from the map). land_threshold controls how much land can be present in a pixel before it is treated as land in map$mask_water. For "large"/10 resolution, rnaturalearthhires is used by rnaturalearth when available.

Value

A map object with mask_water added as a logical matrix.

See Also

Other map: map_create(), print.map(), rast.map()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    tag_set_map(
      extent = c(-16, 23, 0, 50),
      scale = 4,
      known = data.frame(
        stap_id = 1,
        known_lon = 17.05,
        known_lat = 48.9
      )
    ) |>
    twilight_create() |>
    twilight_label_read() |>
    geolight_map(quiet = TRUE)

  # Create water mask
  tag$map_light <- map_add_mask_water(tag$map_light)

  # View the mask
  image(tag$map_light$mask_water)
})

Description

This function creates a GeoPressureR map object from a spatio-temporal dataset. The data needs to be discretized according to scale, extent (space) and stap (time).

This function is used by geopressure_map and graph_marginal.

Usage

map_create(data, extent, scale, stap, id = NA, type = "unknown")

Arguments

Value

A GeoPressure map object

See Also

Other map: map_add_mask_water(), print.map(), rast.map()

Examples

data <- lapply(1:10, \(x) matrix(runif(5000), nrow = 50, ncol = 100))
scale <- 10
extent <- c(0, 10, 0, 5)
seq(as.Date("2023-01-01"), as.Date("2023-01-10"), by = "day")
stap <- data.frame(
  stap_id = 1:10,
  start = seq(as.POSIXct("2023-01-01", tz = "UTC"),
    as.POSIXct("2023-01-10 UTC", tz = "UTC"),
    by = "day"
  ),
  include = TRUE
)
stap$end <- stap$start + sample(1:10) * 10000

# Create the map
map <- map_create(
  data = data,
  extent = extent,
  scale = scale,
  stap = stap,
  id = "18LX",
  type = "pressure"
)

print(map)

plot(map)

Description

Take the two parameters defining the spatial grid of a map in GeoPressureR (extent and scale) and constructs various possible spatial variable of interest for the spatial grid (e.g., grid dimension, latitude and longitude...)

This function is used in multiple functions of GeoPressureR to allow to only store extent and scale in tag and graph while having access to all spatial variables anywhere anytime.

Usage

map_expand(extent, scale)

Arguments

Value

A list containing:

• extent same as input

• scale same as input

• lat vector of latitude

• lon vector of longitude

• dim vector of length 2 of the dimension of the map (number of pixel in lat and lon)

Examples

str(map_expand(extent = c(0, 10, 0, 5), scale = 1))

str(map_expand(extent = c(-16, 23, 0, 50), scale = 10))

Description

Create the list of parameter for GeoPressureR tag and graph objects.

param list are mostly used to archived the actual value of parameters used to create a tag and/or a graph, thus allowing for examination of parameters post-creation. This function should therefore not be used to set/define parameters ahead of computation. In reality, there are very few external case of use for this function.

Usage

param_create(id, default = FALSE, ...)

Arguments

Value

A GeoPressureR param list

See Also

Other param: print.param()

Examples

param <- param_create("18LX", default = TRUE)
print(param)

Description

Retrieve the edges in a graph corresponding to the flight transition defined by a path. These edges can be useful to extract flight information specific to a path.

Usage

path2edge(path, tag_graph)

Arguments

Value

Data.frame of the edge containing:

• s: index in 3D (lat-lon-stap) of the origin (source).

• t: index in 3D (lat-lon-stap) of the destination (target).

• lat_s: latitude of the origin (source).

• lat_t: latitude of the destination (target).

• lon_s: longitude of the origin (source).

• lon_t: longitude of the destination (target).

• stap_s: stationary period of the origin (source).

• stap_t: stationary period of the destination (target).

• distance: Distance (in km) of the flight.

• start: end of the flight.

• end: start of the flight.

• duration: duration of the flight.

• n: number of flight.

• bearing: Angle of the flight in degree (0° = North, 90° = East).

• gs: groundspeed vector expressed as a complex number. You can compute the groundspeed value (km/h) with abs(gs), the W-E and S-N component of the flight with Re(gs) and Im(gs), and the angle/direction with Arg(gs). If graph provided.

• ws: if computed with graph_add_wind(), same value as gs. Airspeed is computed with as = gs - ws in complex number to keep the vectorial additive properties. If graph provided.

See Also

GeoPressureManual

Other path: path2elevation(), path2twilight(), plot_path(), tag2path()

Examples

edge <- path2edge(path, tag)

Description

This function is a wrapper of the GeoPressureAPI elevationPath entry point. It queries the ground elevation from SRTM (SRTM90_V4) along a polyline specify by path.

Because the position are often defined on a relative coarse scale (e.g., 0.25° ~ 29km), you can request the elevation at a specify resolution defined by scale and return pre-defined percentile of the elevation at this resolution.

The returned data.frame provide the ground elevation along the path with a resolution defined by sampling_scale.

Usage

path2elevation(
  path,
  scale = 4,
  sampling_scale = scale,
  percentile = c(10, 50, 90),
  debug = FALSE
)

Arguments

Value

A data.frame containing

• stap_id numeric value corresponding to the ratio of distance between position of known stap

• lon

• lat

• distance distance in km along the path starting at the first stap_id

See Also

Other path: path2edge(), path2twilight(), plot_path(), tag2path()

Examples

# Create a path
path <- data.frame(
  lon = c(8.47, 9.41, 9.01, -0.91, 14.24, 27.30, 34.39, 30.00),
  lat = c(48.89, 44.78, 40.07, 37.68, 17.33, 7.32, 8.09, -23.13),
  start = as.POSIXct(
    c(
      "2017-05-01 00:42", "2017-05-03 01:22", "2017-05-03 22:47", "2017-05-06 03:32",
      "2017-05-07 01:12", "2017-05-07 22:32", "2017-05-09 21:52", "2017-05-10 21:12"
    ),
    tz = "UTC"
  ),
  end = as.POSIXct(
    c(
      "2017-05-02 22:12", "2017-05-03 20:12", "2017-05-06 02:47", "2017-05-06 23:22",
      "2017-05-07 17:42", "2017-05-09 20:27", "2017-05-10 19:57", "2017-05-11 21:17"
    ),
    tz = "UTC"
  ),
  stap_id = seq(1, 8)
)


plot_path(path)

elevation <- path2elevation(path)

plot(elevation$distance, elevation$X50,
  type = "l",
  ylab = "Elevation (m)", xlab = "Distance from start (km)"
)
lines(elevation$distance, elevation$X10, lty = 5)
lines(elevation$distance, elevation$X90, lty = 5)
id <- elevation$stap_id %% 1 == 0
points(elevation$distance[id], elevation$X90[id], col = "red")

Description

This function computes the theoretical twilight (i.e., datetime of sunrise and sunset) at given locations and for specific date.

We use the suntools package for this.

By default (solar_dep=0), the computation returns sunrise and sunset. But, it is also possible to compute different twilights by setting depression angle value greater than 0 (6° for civil, 12° for nautical and 18° for astronomical). The corresponding solar elevation threshold is -solar_dep, and the equivalent solar zenith angle is 90 + solar_dep.

Usage

path2twilight(path, date = NULL, solar_dep = 0, return_long = TRUE)

Arguments

Value

if return_long == TRUE, a twilight data.frame (same as twilight_create()) with columns:

• date same as input date

• twilight date-time of twilight

• rise logical indicating sunrise (TRUE) or sunset (FALSE).

• stap_id same as path$stap_id

• lat same as path$lat

• lon same as path$lon

if return_long == FALSE, a data.frame with the same size of date with columns:

• date same as input date

• sunrise date-time of sunrise

• sunset date-time of sunset

• stap_id same as path$stap_id

• lat same as path$lat

• lon same as path$lon

See Also

GeoPressureManual , suntools

Other path: path2edge(), path2elevation(), plot_path(), tag2path()

Examples

path <- data.frame(
  stap_id = c(1, 2, 3, 4, 5),
  j = c(1, 1, 1, 1, 1),
  ind = c(1652L, 1603L, 1505L, 1609L, 1463L),
  lat = c(48.9, 47.5, 45.5, 41.5, 37.5),
  lon = c(17.05, 16.5, 14.5, 16.5, 13.5),
  start = as.POSIXct(
    c(1501113450, 1501888650, 1501987950, 1502075550, 1502151150),
    tzone = "UTC"
  ),
  end = as.POSIXct(c(1501876050, 1501961250, 1502046750, 1502133150, 1502323050), tzone = "UTC"),
  include = c(TRUE, TRUE, TRUE, TRUE, TRUE),
  known = c(TRUE, FALSE, FALSE, FALSE, FALSE),
  interp = c(FALSE, FALSE, FALSE, FALSE, FALSE)
)

twl <- path2twilight(path)

Description

This function display a plot of pressure time series recorded by a tag

Usage

plot_graph_movement(graph, speed = seq(0, 120), plot_plotly = FALSE)

Arguments

Value

a plot or ggplotly object.

See Also

Other movement: bird_create(), graph_set_movement(), speed2prob(), tag_download_wind()

Examples

movement_gamma <- list(
  type = "gs",
  method = "gamma",
  shape = 7,
  scale = 7,
  low_speed_fix = 15,
  zero_speed_ratio = 1
)
plot_graph_movement(movement_gamma)

movement_logis <- list(
  type = "gs",
  method = "logis",
  scale = 7,
  location = 40,
  low_speed_fix = 15,
  zero_speed_ratio = 1
)
plot_graph_movement(movement_logis)

bird <- bird_create("Example bird", mass = 0.1, wing_span = 0.4, wing_aspect = 7)
movement_power <- list(
  type = "as",
  method = "power",
  bird = bird,
  power2prob = \(power) (1 / power)^3,
  low_speed_fix = 15,
  zero_speed_ratio = 1
)
plot_graph_movement(movement_power)

Description

This function plots a path data.frame. This function is used in plot.map().

Usage

plot_path(
  path,
  plot_leaflet = TRUE,
  map = NULL,
  provider = NULL,
  provider_options = leaflet::providerTileOptions(),
  pad = 3,
  polyline = NULL,
  circle = NULL,
  group = NULL
)

Arguments

Value

A leaflet map when plot_leaflet = TRUE, otherwise a ggplot2 object.

Basemap API keys

Interactive maps always offer Esri basemaps (gray canvas, imagery and topographic). CARTO, Mapbox and MapTiler basemaps are added to the layer control only when their API key is stored in your system keyring. Get a key from each provider:

• CARTO: "Get your API key" on CARTO Basemaps.

• Mapbox: Access tokens page of your account (see Mapbox documentation).

• MapTiler: API keys page of your MapTiler Cloud account (see MapTiler documentation).

Then store each key once:

keyring::key_set_with_value("CARTO_API_KEY", password = "<your CARTO API key>")
keyring::key_set_with_value("MAPBOX_ACCESS_TOKEN", password = "<your Mapbox token>")
keyring::key_set_with_value("MAPTILER_API_KEY", password = "<your MapTiler API key>")

Mapbox access tokens are visible in the browser when a map is rendered. Use a public, read-only token rather than a secret token.

See Also

plot.map()

Other path: path2edge(), path2elevation(), path2twilight(), tag2path()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE)
})

path <- data.frame(
  stap_id = 1:4,
  lon = c(17.05, 16.2, NA, 15.4),
  lat = c(48.9, 47.8, NA, 46.5),
  known_lon = c(17.05, NA, NA, NA),
  known_lat = c(48.9, NA, NA, NA),
  start = as.POSIXct(
    c("2018-01-01", "2018-01-03", "2018-01-05", "2018-01-07"),
    tz = "UTC"
  ),
  end = as.POSIXct(
    c("2018-01-02", "2018-01-04", "2018-01-06", "2018-01-08"),
    tz = "UTC"
  )
)

plot_path(path)

plot_path(path, plot_leaflet = FALSE)

Description

Display a pressurepath data.frame as a time series or histogram

Usage

plot_pressurepath(
  pressurepath,
  type = "timeseries",
  sd = attr(pressurepath, "sd"),
  warning_std_thr = 3,
  plot_plotly = TRUE
)

Arguments

Value

a plot or ggplotly object.

See Also

Other pressurepath: geopressure_timeseries(), pressurepath_create(), pressurepath_variable_available()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |> tag_label(quiet = TRUE)
})

path <- data.frame(
  stap_id = tag$stap$stap_id,
  lat = c(48.5, 32.5, 30.5, 49.5, 41.6),
  lon = c(17.5, 13.5, 16.5, 21.5, 12.7)
)

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

plot_pressurepath(pressurepath)

plot_pressurepath(pressurepath, type = "histogram")

plot_pressurepath(pressurepath, type = "altitude")

Description

This function display a plot of acceleration time series recorded by a tag

Usage

plot_tag_acceleration(
  tag,
  variable = "activity",
  plot_plotly = TRUE,
  label_auto = TRUE,
  min_duration = 30
)

Arguments

Value

a plot or ggplotly object.

See Also

Other plot_tag: plot_tag_actogram(), plot_tag_light(), plot_tag_pressure(), plot_tag_temperature(), plot_tag_twilight()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE)
})

plot_tag_acceleration(tag)

Description

This function display a plot of the acceleration time series recorded by a tag

Usage

plot_tag_actogram(
  tag,
  twl_offset = NULL,
  plot_plotly = TRUE,
  flip_axes = FALSE,
  double_plot = FALSE
)

Arguments

Value

a ggplot or ggplotly object.

See Also

Other plot_tag: plot_tag_acceleration(), plot_tag_light(), plot_tag_pressure(), plot_tag_temperature(), plot_tag_twilight()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE)

  plot_tag_actogram(tag, plot_plotly = TRUE)
})

Description

This function display a plot of light time series recorded by a tag

Usage

plot_tag_light(tag, transform_light = TRUE, plot_plotly = TRUE)

Arguments

Value

a plot or ggplotly object.

See Also

Other plot_tag: plot_tag_acceleration(), plot_tag_actogram(), plot_tag_pressure(), plot_tag_temperature(), plot_tag_twilight()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE)
})

plot_tag_light(tag)

Description

This function display a plot of pressure time series recorded by a tag

Usage

plot_tag_pressure(tag, plot_plotly = TRUE, warning_pressure_diff = 3)

Arguments

Value

a plot or ggplotly object.

See Also

Other plot_tag: plot_tag_acceleration(), plot_tag_actogram(), plot_tag_light(), plot_tag_temperature(), plot_tag_twilight()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE)
})

plot_tag_pressure(tag, plot_plotly = FALSE)

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_label(tag, quiet = TRUE)
})

plot_tag_pressure(tag)

Description

This function display a plot of temperature time series recorded by a tag

Usage

plot_tag_temperature(tag, variable = "external", plot_plotly = TRUE)

Arguments

Value

a plot or ggplotly object.

See Also

Other plot_tag: plot_tag_acceleration(), plot_tag_actogram(), plot_tag_light(), plot_tag_pressure(), plot_tag_twilight()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE)
})

plot_tag_temperature(tag)

Description

This function display a plot of twilight time series recorded by a tag

Usage

plot_tag_twilight(
  tag,
  twilight_line = NULL,
  transform_light = TRUE,
  twl_offset = NULL,
  plot_plotly = TRUE,
  flip_axes = FALSE,
  double_plot = FALSE
)

Arguments

Value

a ggplot or ggplotly object.

See Also

Other plot_tag: plot_tag_acceleration(), plot_tag_actogram(), plot_tag_light(), plot_tag_pressure(), plot_tag_temperature()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE)

  plot_tag_twilight(tag, plot_plotly = TRUE)

  tag <- tag_label(tag, quiet = TRUE)

  plot_tag_twilight(tag)
})

Description

This function plots the stacked calibration histogram and fitted density, with calibration stationary periods labeled as known or fitted anchors. Refined fitted anchors remain labeled as fitted. If a path is provided, it instead plots the solar zenith angle histogram derived from tag$twilight and the path, with the calibration density overlaid.

Usage

plot_twl_calib(x, path = NULL, warning_ci = 0.95, plot_plotly = TRUE, ...)

plot_twl_calib_path(tag, path, warning_ci = 0.9973, plot_plotly = TRUE)

Arguments

Value

a ggplot or ggplotly object

See Also

Other geolight: geolight_fit_location(), geolight_map(), geolight_solar(), twilight_create(), twilight_label_read(), twilight_label_write()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    tag_set_map(
      extent = c(-16, 23, 0, 50),
      scale = 5,
      known = data.frame(
        stap_id = 1,
        known_lon = 17.05,
        known_lat = 48.9
      )
    ) |>
    twilight_create() |>
    twilight_label_read() |>
    geolight_map_calibrate()
})

# Histogram + kernel density
plot_twl_calib(tag)

# With fitted location duration of 5 days minimum
tag <- geolight_map_calibrate(tag, fitted_location_duration = 5)

# Path-based diagnostic (uses tag$twilight)
path <- tag$stap[, c("stap_id", "start", "end")]
path$lon <- ifelse(is.na(tag$stap$known_lon), 0, tag$stap$known_lon)
path$lat <- ifelse(is.na(tag$stap$known_lat), 0, tag$stap$known_lat)
plot_twl_calib(tag, path = path, plot_plotly = FALSE)

Description

This function plots a GeoPressureR map object.

You can plot on top of the map a path, this uses the plot_path() function.

Our maps are defined in lat-lon (i.e., EPSG:4326), but the display of maps on web map are nearly always in web mercator (i.e., EPSG:3857). We therefore need to reproject our map for display. However, we don't really want to interpolate the map as each pixel might be important to visualize. We therefore re-project with a near-neighbour interpolation (method = "near" in terra::project()). Yet to avoid having pixel misplaced, we generally need to use a projection with a finer resolution. The argument fac_res_proj controls the relative change of resolution between the original map to the projected map.

Usage

## S3 method for class 'map'
plot(
  x,
  path = NULL,
  thr_likelihood = 1,
  plot_leaflet = TRUE,
  provider = NULL,
  provider_options = leaflet::providerTileOptions(),
  palette = NULL,
  opacity = 0.8,
  legend = FALSE,
  fac_res_proj = 4,
  ...
)

Arguments

Value

a plot or leaflet object.

Basemap API keys

Interactive maps always offer Esri basemaps (gray canvas, imagery and topographic). CARTO, Mapbox and MapTiler basemaps are added to the layer control only when their API key is stored in your system keyring. Get a key from each provider:

• CARTO: "Get your API key" on CARTO Basemaps.

• Mapbox: Access tokens page of your account (see Mapbox documentation).

• MapTiler: API keys page of your MapTiler Cloud account (see MapTiler documentation).

Then store each key once:

keyring::key_set_with_value("CARTO_API_KEY", password = "<your CARTO API key>")
keyring::key_set_with_value("MAPBOX_ACCESS_TOKEN", password = "<your Mapbox token>")
keyring::key_set_with_value("MAPTILER_API_KEY", password = "<your MapTiler API key>")

Mapbox access tokens are visible in the browser when a map is rendered. Use a public, read-only token rather than a secret token.

See Also

plot_path() plot.tag()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    tag_set_map(
      extent = c(-16, 23, 0, 50),
      scale = 4
    ) |>
    geopressure_map(quiet = TRUE)
})

plot(tag$map_pressure)

plot(tag$map_pressure, plot_leaflet = FALSE)

# `thr_likelihood` can be used to visualize its effect in `graph_create`
plot(tag$map_pressure,
  thr_likelihood = 0.9,
  palette = "viridis",
  opacity = 1,
  provider = "Esri.WorldGrayCanvas"
)

Description

This function plots a GeoPressureR tag object as a time series or a map.

By default, type is determined in the following order of preference according to availability: c("map_pressure", "map_light"), "map_pressure", "map_light", "pressure".

plot.tag() calls different plotting functions depending on type.

• "pressure": plot_tag_pressure()

• "light": plot_tag_light()

• "acceleration": plot_tag_acceleration()

• "temperature": plot_tag_temperature()

• "twilight": plot_tag_twilight()

• "actogram": plot_tag_actogram()

• "map_*" : plot.map() with ⁠tag$map_*⁠ as first argument.

Refers to these functions for additional parameters and more flexibility in the plotting.

Usage

## S3 method for class 'tag'
plot(x, type = NULL, ...)

Arguments

Value

a plot, ggplotly or leaflet object.

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    twilight_create() |>
    twilight_label_read()
})

# By default, plot will display the time series of pressure
plot(tag)
# Change the `type` to display other sensor
plot(tag, type = "acceleration")
plot(tag, type = "light")
plot(tag, type = "temperature")
plot(tag, type = "twilight")
plot(tag, type = "actogram")

# After you compute any likelihood map, the default will
# become this map (i.e., `type = "map"`)
tag <- tag_set_map(tag,
  extent = c(-16, 23, 0, 50),
  scale = 4,
  known = data.frame(
    stap_id = 1,
    known_lon = 17.05,
    known_lat = 48.9
  )
) |>
  geopressure_map(quiet = TRUE)
plot(tag)
# The likelihood map of light can be display with
tag <- geolight_map(tag, quiet = TRUE)
plot(tag, type = "map_light")
# When both pressure and light likelihood are present,
# the default is to display their products, equivalent
# to choose `type = c("map_pressure", "map_light")`
plot(tag)

Description

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 = "both",
  preprocess = FALSE,
  workers = "auto",
  quiet = FALSE,
  debug = FALSE,
  source = c("auto", "arco", "api")
)

pressurepath_create_api(
  tag,
  path = tag2path(tag),
  variable = c("altitude", "surface_pressure"),
  solar_dep = 0,
  era5_dataset = "both",
  preprocess = FALSE,
  workers = "auto",
  quiet = FALSE,
  debug = FALSE
)

pressurepath_create_arco(
  tag,
  path = tag2path(tag),
  variable = c("altitude", "surface_pressure"),
  solar_dep = 0,
  era5_dataset = "both",
  preprocess = FALSE,
  quiet = FALSE,
  debug = FALSE
)

Arguments

Value

A pressurepath data.frame containing tag pressure, coordinates, requested ERA5 variables, normalised surface pressure, and optional sunrise and sunset times.

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. 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-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.

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().

See Also

Other pressurepath: geopressure_timeseries(), plot_pressurepath(), pressurepath_variable_available()

Examples

pressurepath <- pressurepath_create(tag, path)

Description

The variables available to pressurepath_create() depend on both the backend and the ERA5 product, and the sets genuinely differ. GeoPressureAPI serves whatever bands the underlying Earth Engine collection carries: 292 for ERA5 single levels against 70 for ERA5-Land, with only 44 in common. era5_dataset = "both" mosaics ERA5-Land on top of ERA5 but returns ERA5's band namespace, so its set equals "single-levels" and ERA5-Land-only bands are dropped. The ARCO backend reads ECMWF's zarr stores directly and currently maps only surface pressure and 2 m temperature, so it can return "surface_pressure" and the derived "altitude".

Usage

pressurepath_variable_available(
  source = c("api", "arco"),
  era5_dataset = c("single-levels", "land", "both")
)

Arguments

Details

Requesting a variable the chosen product does not have used to fail silently: GeoPressureAPI returned ⁠200 success⁠ with every array empty — not just the missing one — which arrived as a pressurepath whose ERA5 columns were all NA. pressurepath_create() now validates the request up front with this list.

Value

A character vector of variable names accepted by variable, including "altitude".

See Also

Other pressurepath: geopressure_timeseries(), plot_pressurepath(), pressurepath_create()

Examples

length(pressurepath_variable_available("api", "single-levels"))
length(pressurepath_variable_available("api", "land"))
pressurepath_variable_available("arco", "land")

Description

This function displays the information of a bird object.

Usage

## S3 method for class 'bird'
print(x, ...)

Arguments

Value

bird is returned invisibly and unchanged

See Also

Other bird: bird_create()

Examples

# Using AVONET dataset
bird_create("Acrocephalus arundinaceus")

Description

This function displays the information of a graph object.

Usage

## S3 method for class 'graph'
print(x, ...)

Arguments

Value

graph is returned invisibly and unchanged

See Also

Other graph: graph_add_wind(), graph_create(), graph_marginal(), graph_most_likely(), graph_set_movement(), graph_simulation()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    twilight_create() |>
    twilight_label_read() |>
    tag_set_map(
      extent = c(-16, 23, 0, 50),
      known = data.frame(stap_id = 1, known_lon = 17.05, known_lat = 48.9)
    ) |>
    geopressure_map(quiet = TRUE) |>
    geolight_map(quiet = TRUE)
})

graph <- graph_create(tag, quiet = TRUE)

print(graph)

Description

This function displays the information of a map object.

Usage

## S3 method for class 'map'
print(x, ...)

Arguments

Value

map is returned invisibly and unchanged

See Also

Other map: map_add_mask_water(), map_create(), rast.map()

Examples

withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- tag_create("18LX", quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    tag_label(quiet = TRUE) |>
    tag_set_map(
      extent = c(-16, 23, 0, 50),
      scale = 4
    ) |>
    geopressure_map(quiet = TRUE)
})

print(tag$map_pressure)