Skip to contents

Create a graph object

Source: R/graph_create.R
graph_create.Rd

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 most 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,
  geosphere_dist = geosphere::distHaversine,
  geosphere_bearing = geosphere::bearing,
  workers = 1,
  quiet = FALSE
)

Arguments

tag

a GeoPressureR tag object.

thr_likelihood

threshold of percentile (see details).

thr_gs

threshold of groundspeed (km/h) (see details).

likelihood

Field of the tag list containing the likelihood map (character). Possible value are map_pressure, map_light, map_pressure_mse, map_pressure_mse, map_pressure_mse, mask_water. Default NA is to take the product of map_pressure and map_light, or if not available, taking the first of the possible values.

geosphere_dist

function to compute the distance. Usually, either geosphere::distHaversine (fast) or geosphere::distGeo (precise but slow). See https://rspatial.org/raster/sphere/2-distance.html for more options and details.

geosphere_bearing

function to compute the bearing. Either geosphere::bearing (default) or geosphere::bearingRhumb. See https://rspatial.org/raster/sphere/3-direction.html#bearing for details.

workers

number of workers used in the computation of edges ground speed. More workers (up to the limit future::availableCores()) usually makes the computation faster, but because the the number of edges is large, memory will often limit the computation.

quiet

logical to hide messages about the progress.

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 https://doi.org/10.1111/2041-210X.14082.

See also

GeoPressureManual

Other graph: 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)
#> 
#> ── GeoPressureR `graph` object for 18LX ────────────────────────────────────────
#> Note: All green texts are fields of `graph` (i.e., `graph$field`).
#> 
#> ── Parameters param 
#> Run `graph$param` to display full table
#> 
#> ── Stationary periods stap 
#> 5 stationary periods
#>   stap_id               start                 end known_lon known_lat include
#> 1       1 2017-07-26 23:57:30 2017-08-04 19:47:30     17.05      48.9    TRUE
#> 2       2 2017-08-04 23:17:30 2017-08-05 19:27:30        NA        NA    TRUE
#> 3       3 2017-08-06 02:52:30 2017-08-06 19:12:30        NA        NA    TRUE
#> ...
#> Run `graph$stap` to see full stap table
#> 
#> ── Map 
#> • Extent (W, E, S, N): -16°, 23°, 0°, 50°
#> • Dimensions (lat x lon): 500 x 390 (res. 0.1°)
#> 
#> ── Graph size 
#> • 1 equipement node
#> • 51 retrieval nodes
#> • 1,913 nodes
#> • 854,174 edges
#> 
#> ── Movement model 
#> ! Windspeed not computed. Use `graph_add_wind()`
#> ✖ No movement model defined. Use `graph_set_movement()`