
Configure the spatial and temporal parameters of the map of a tag object
Source: R/tag_set_map.R
tag_set_map.RdThis function adds to tag the parameters defining the 3D grid of the map. The spatial
parameters (extent and scale) define the geographical dimensions of the map, and the
temporal dimension is defined based on the stationary periods built using the labels.
include_stap_id and include_min_duration can be used to limit which stationary periods are
computed and modelled in the analysis. By default, all stationary periods are included.
In addition, tag offers the possibility to define known locations (e.g., equipment or
retrieval site). These can only be defined at the level of a stationary period (i.e., assuming
constant position during the whole stationary period) but you can define as many known stationary
periods as you wish. Because the index of the last stationary period is generally unknown, you
can use negative indexing in known, i.e., known$stap_id = -1 will be converted to
nrow(tag$stap).
By default, no likelihood map will be computed for these stationary periods and the trajectory
model will be more constrained, saving significant computational time. You can change this
using the compute_known parameter in geopressure_map().
Running tag_set_map() again with different parameters overwrites the previous ones with a
warning. If likelihood maps (map_pressure or map_light) have already been computed, it
aborts instead: start again from tag_create() to use new parameters.
Usage
tag_set_map(
tag,
extent,
scale = 4,
known = data.frame(stap_id = integer(), known_lat = double(), known_lon = double()),
include_stap_id = NULL,
include_min_duration = 0
)Arguments
- tag
a GeoPressureR
tagobject.- extent
geographical extent of the map on which the likelihood and graph model will be computed. Vector of length 4
c(xmin, xmax, ymin, ymax)orc(W, E, S, N).- scale
number of pixels per 1° latitude-longitude. For instance,
scale = 10for a resolution of 0.1° (~10km) andscale=4for a resolution of 0.25° (~30km). To avoid interpolating the ERA5 single-levels data, the scale should be equal to or smaller than 4 (the default intag_set_map()).tag_set_map()warns for higher values. Read more about scale on the Google Earth Engine documentation .- known
data.frame containing the known positions of the bird (e.g., equipment or retrieval site) with columns
stap_id,known_latandknown_lon. You can set position of the last stationary period usingstap_id = -1. A list is also accepted and converted to a data.frame.- include_stap_id
vector of
stap_iddefining which stationary periods to model, that is, to compute in the likelihood map and use in the graph.- include_min_duration
minimum duration threshold of stationary periods to include (in hours).
Value
A GeoPressureR tag object with:
stap: Data.frame of all stationary periods with three new columns:known_latandknown_londefine the known position during these stationary periods, andincludedefines whether the likelihood map of this stationary period should be computed and later used in the graph.param$tag_set_map: list of the input parameters (extent,scale,known,include_stap_idandinclude_min_duration).
See also
Other tag:
print.tag(),
read_stap(),
tag_create(),
tag_stap_daily()
Examples
withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
tag <- tag_create("18LX", quiet = TRUE) |> tag_label(quiet = TRUE)
})
# Default tag
tag_default <- tag_set_map(tag, c(-16, 23, 0, 50))
print(tag_default)
#>
#> ── GeoPressureR `tag` object for 18LX ──────────────────────────────────────────
#> Note: All green texts are fields of `tag` (i.e., `tag$field`).
#>
#> ── Parameter param
#> Run `tag$param` to display all parameters
#>
#> ── Sensors data
#> Manufacturer: soi
#> Date range: 2017-06-20 to 2017-08-09 23:55:00
#> • pressure: 672 datapoints (30min)
#> • light: 4,032 datapoints (5min)
#> • acceleration: 4,032 datapoints (5min)
#> • temperature_external: 2,448 datapoints (30min)
#>
#> ── Stationary periods stap
#> stap_id | start | end | known_lat | known_lon | include
#> 1 | 2017-07-27 00:00:00 | 2017-08-04 19:47:30 | NA | NA | TRUE
#> 2 | 2017-08-04 23:17:30 | 2017-08-05 19:27:30 | NA | NA | TRUE
#> ...
#> 5 | 2017-08-08 00:12:30 | 2017-08-09 23:55:00 | NA | NA | TRUE
#> Run `tag$stap` to see full stap table
#>
#> ── Map
#> • Extent (W, E, S, N): -16°, 23°, 0°, 50°
#> • Dimensions (lat x lon): 200 x 156 (res. 0.25°)
#> ✖ No pressure likelihood computed yet. Use `geopressure_map()`.
# Customized tag, with coarse grid scale, known position for the first stationary
# period and considering only the stationary periods lasting more than 20 hours.
tag_custom <- tag_set_map(tag,
extent = c(-16, 23, 0, 50),
scale = 1,
include_min_duration = 20,
known = data.frame(
stap_id = 1,
known_lon = 17.05,
known_lat = 48.9
)
)
print(tag_custom)
#>
#> ── GeoPressureR `tag` object for 18LX ──────────────────────────────────────────
#> Note: All green texts are fields of `tag` (i.e., `tag$field`).
#>
#> ── Parameter param
#> Run `tag$param` to display all parameters
#>
#> ── Sensors data
#> Manufacturer: soi
#> Date range: 2017-06-20 to 2017-08-09 23:55:00
#> • pressure: 672 datapoints (30min)
#> • light: 4,032 datapoints (5min)
#> • acceleration: 4,032 datapoints (5min)
#> • temperature_external: 2,448 datapoints (30min)
#>
#> ── Stationary periods stap
#> stap_id | start | end | known_lat | known_lon | include
#> 1 | 2017-07-27 00:00:00 | 2017-08-04 19:47:30 | 48.9 | 17.05 | TRUE
#> 2 | 2017-08-04 23:17:30 | 2017-08-05 19:27:30 | NA | NA | TRUE
#> ...
#> 5 | 2017-08-08 00:12:30 | 2017-08-09 23:55:00 | NA | NA | TRUE
#> Run `tag$stap` to see full stap table
#>
#> ── Map
#> • Extent (W, E, S, N): -16°, 23°, 0°, 50°
#> • Dimensions (lat x lon): 50 x 39 (res. 1°)
#> ✖ No pressure likelihood computed yet. Use `geopressure_map()`.