route_path: Re-route a movement path around land using the 'pathroutr'...

In ianjonsen/foieGras: Fit Continuous-Time State-Space and Latent Variable Models for Quality Control of Argos Satellite (and Other) Telemetry Data and for Estimating Changes in Animal Movement

Re-route a movement path around land using the pathroutr package

Description

A wrapper function that uses the pathroutr package https://jmlondon.github.io/pathroutr/ to re-route movement paths that cross a land barrier. The current implementation will take either the output from a fit_ssm model or the simulations generated by sim_fit.

Usage

route_path(
  x,
  what = c("fitted", "predicted"),
  map_scale = 50,
  dist = 50000,
  append = TRUE,
  ...
)

Arguments

x	either a ssm fit object or a sim_fit object containing simulated paths
what	if using a ssm object should the fitted (typically irregular in time) or predicted (typically regular in time) locations be re-routed.
map_scale	scale of rnaturalearth map to use for land mass: one of 110, 50 (default), or 10. Note that map_scale = 10 is only available if you have the rnaturalearthhires package installed see: https://github.com/ropensci/rnaturalearthhires
dist	buffer distance (m) to add around track locations. The convex hull of these buffered locations defines the size of land polygon used to aid re-routing of points on land. Larger buffers can result in longer computation times. See London (2020) for further details. The default buffer distance is a constant 50000 m.
append	should re-routed locations be appended to the ssm (ssm fit) object (default = TRUE), or returned as a tibble.
...	additional arguments passed to pathroutr::prt_visgraph

Details

route_path uses rnaturalearth::ne_countries at the medium (50) scale, by default, to generate a land barrier. For efficient computation, route_path clips the polygons to the buffered bounds (set by dist (in m) of the movement track(s).

When the input is a ssm object route_path can append the re-routed path locations to the ssm (ssm fit) object. This is useful when move persistence is to be estimated from the re-routed locations via fit_mpm, or tracks are to be visualised with map. route_path can also return a standalone tibble of the re-routed path with the same number of locations as either the original fitted or predicted locations.

When the re-routed path is appended to the ssm object, the path can be extracted using the grab function, e.g. grab(fit, what = "rerouted").

When the input is a sim_fit object then route_path returns the same object but with the locations within each simulation re-routed.

We recommend that users working on complex rerouting problems and/or requiring higher resolution land barrier data work with the pathroutr package directly by first exctracting aniMotum-estimated locations with grab. Higher resolution land barrier data (polygon shapefiles) must be obtained independently.

References

Josh M. London. (2020) pathroutr: An R Package for (Re-)Routing Paths Around Barriers (Version v0.2.1) https://zenodo.org/record/5522909#.YnPxEy_b1qs

Examples

# if 'pathroutr' is installed then ok to use route_path()
if(requireNamespace("pathroutr", quietly = TRUE)) {
  fit <- fit_ssm(ellie, vmax = 4, model = "crw", time.step = 24)
  fit <- route_path(fit, what = "predicted")
  grab(fit, what = "rerouted")
}

ianjonsen/foieGras documentation built on Jan. 17, 2025, 11:15 p.m.