Create a pressurepath — pressurepath

A pressurepath is a data.frame merging path and tag$pressure. It can be thought as the equivalent of the measurement of variables by sensors equipped on the bird moving along a specific path.

Any ERA variables can be retrieve but the functions is most notably used to retrieve ERA5 surface pressure to then be able to compare it to the pressure measured by the tag, and potentially adjust labelling tag data.

By default, We use both the ERA5 LAND and ERA5 surface level if position over water. Available variables can be listed with GeoPressureR:::pressurepath_variable and details description can be found on the parameter listings in ERA5 doc. Note that their exact name might be be different as we query them through Google Earth Engine.

Positions during the flight are estimated by linear interpolation of the position of the stap before and after. pressurepath_create() does not return measurement for stationary periods which are not provided in path as well as the flight before and after.

also return the altitude of the bird along its trajectory. The altitude $z_{tag}$ (a.s.l.) is computed from the tag pressure $P_{tag}$, using the barometric equation $$ z_{{tag}}(x)=z_{ERA5}(x) + \frac{T_{ERA5}(x)}{L_b} \left( \frac{P_{tag}}{P_{ERA5}(x)} \right)^{\frac{RL_b}{g M}-1},$$ where $z_{ERA}$, $T_{ERA}$, and $P_{ERA}$ respectively correspond to the ground level elevation, temperature at 2m, and ground level pressure of ERA5, $L_b$ is the standard temperature lapse rate, $R$ is the universal gas constant, $g$ is the gravity constant and $M$ is the molar mass of air. See more information at the GeoPressureAPI documentation.

To be able to compare the temporal variation of the retrieved pressure of ERA5 $P_{ERA}$ to the tag pressure $P_{tag}$, the function also returns the ERA pressure normalized with the tag mean pressure measurement as surface_pressure_norm. $$ P_{ERA5,0}(\boldsymbol{x})[t] = \left( P_{ERA5}(\boldsymbol{x})[t]-P_{tag}[t]\right) - \left( \frac{1}{n}\sum_{i=1}^{n} P_{ERA5}(\boldsymbol{x})[i]-P_{tag}[i] \right).$$

pressurepath_create() also computes the local sunrise and sunset times for each timestep according to the position of the path using path2twilight(). Sunrise and sunset are defined by the solar depression angle solar_dep.

Usage

pressurepath_create(
  tag,
  path = tag2path(tag),
  variable = c("altitude", "surface_pressure"),
  solar_dep = 0,
  era5_dataset = "both",
  preprocess = FALSE,
  timeout = 60 * 5,
  workers = "auto",
  quiet = FALSE,
  debug = FALSE
)

Arguments

tag: a GeoPressureR tag object.
path: a GeoPressureR path data.frame.
variable: ERA5 variable/parameters available to download. The most commonly used variables:"altitude", "surface_pressure", "temperature_2m", "u_component_of_wind_10m", "v_component_of_wind_10m", "u_component_of_wind_100m", "v_component_of_wind_100m", "total_cloud_cover", "total_precipitation", "land_sea_mask". All variables can be listed with GeoPressureR:::pressurepath_variable.
solar_dep: a numerical value representing the solar depression angle used to compute sunrise and sunset. If NULL, does not compute sunrise sunset.
era5_dataset: select the dataset to use: "single-levels" for ERA5 hourly data on single levels, "land" for ERA5-Land hourly data or "both" to use land where available and sing-levels otherwise (i.e. over water). LAND has greater precision but is not available on water. Using a single one makes the query faster.
preprocess: logical to pre-process pressure data with geopressure_map_preprocess().
timeout: duration before the code is interrupted both for the request on GeoPressureAPI and on GEE (in seconds, see httr2::req_timeout()).
workers: number of parallel requests on GEE. Integer between 1 and 99.
quiet: logical to hide messages about the progress
debug: logical to display additional information to debug a request

Value

A GeoPressureR pressurepath data.frame with columns:

date same as pressure$date
stap_id same as pressure$stap_id
pressure_tag same as pressure$value
label same as pressure$label
j same as path$j
lat same as path$lat
lon same as path$lon
include same as path$include
known same as path$known
altitude altitude of the bird along the path (see detail)
surface_pressure pressure retrieved from ERA5.
surface_pressure_norm pressure retrieved from ERA5 normalized to the average of pressure_tag over the stationary period.
sunrise datetime of the sunrise according to solar_dep.
sunset datetime of the sunset according to solar_dep.
... any other ERA5 variable requested by variable

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)

str(pressurepath)
#> 'data.frame':	672 obs. of  11 variables:
#>  $ date                 : POSIXct, format: "2017-07-27 00:00:00" "2017-07-27 00:30:00" ...
#>  $ stap_id              : num  1 1 1 1 1 1 1 1 1 1 ...
#>  $ pressure_tag         : int  989 989 990 990 989 989 990 990 991 990 ...
#>  $ label                : chr  "" "" "" "" ...
#>  $ lat                  : num  48.5 48.5 48.5 48.5 48.5 48.5 48.5 48.5 48.5 48.5 ...
#>  $ lon                  : num  17.5 17.5 17.5 17.5 17.5 17.5 17.5 17.5 17.5 17.5 ...
#>  $ altitude             : num  157 157 148 148 158 ...
#>  $ surface_pressure     : num  978 978 978 978 978 ...
#>  $ surface_pressure_norm: num  989 989 989 989 989 ...
#>  $ sunset               : POSIXct, format: "2017-07-27 18:34:08" "2017-07-27 18:34:08" ...
#>  $ sunrise              : POSIXct, format: "2017-07-27 03:18:06" "2017-07-27 03:18:06" ...
#>  - attr(*, "id")= chr "18LX"
#>  - attr(*, "preprocess")= logi FALSE

plot_pressurepath(pressurepath)


pressurepath <- pressurepath_create(
  tag,
  path[c(2, 3, 4), ],
  quiet = TRUE
)

plot_pressurepath(pressurepath)

Create a `pressurepath`

Usage

Arguments

Value

See also

Examples