Skip to contents

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 period) defined as (1) those whose likelihood values 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

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). By default, uses the product of map_pressure and map_light if available, otherwise the first available likelihood map in the tag.

quiet

logical to hide messages about the progress.

geosphere_dist

[Deprecated] This argument is no longer used. Distance calculations now use a custom memory-efficient Haversine implementation.

geosphere_bearing

[Deprecated] This argument is no longer used. Bearing calculations now use a custom memory-efficient implementation.

workers

[Deprecated] This argument is no longer used. Parallel processing has been removed to avoid memory issues.

Value

A GeoPressureR graph object, a list with:

  • 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: tag$param with an additional graph_create list including thr_likelihood and thr_gs

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 .

Examples

# Load a tag with pressure and light likelihood maps computed with `geopressuretemplate()`
withr::with_dir(system.file("extdata", package = "GeoPressureR"), {
  tag <- load_interim("18LX", var = "tag")
})

# 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 all parameters
#> 
#> ── 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): 100 x 78 (res. 0.5°)
#> 
#> ── Graph size 
#> • 1 equipment node
#> • 1 retrieval node
#> • 151 nodes
#> • 5,265 edges
#> 
#> ── Movement model 
#> ! Windspeed not computed. Use `graph_add_wind()`
#> ✖ No movement model defined. Use `graph_set_movement()`