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

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.

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")
}
#> fitting crw SSM to 1 tracks...
#> 
 pars:   1 1 0 -2.91153      
 pars:   0.38512 0.37191 -0.01692 -3.38813      
 pars:   -1.4595 -1.51236 -0.06769 -4.81792      
 pars:   -2.20058 -2.24383 -0.11527 -4.95732      
 pars:   -0.38346 -0.4056 -0.04615 -3.85456      
 pars:   -1.23664 -1.20844 -0.10327 -3.65984      
 pars:   -2.25711 -2.16871 -0.17159 -3.42693      
 pars:   -3.07868 -3.34599 -0.26131 -1.24778      
 pars:   -4.46619 -1.62751 -0.49092 0.12579      
 pars:   -3.18442 -2.86245 -0.30197 -0.80151      
 pars:   -3.40955 -3.30581 -0.49919 -0.40195      
 pars:   -3.06893 -3.16418 -1.05454 -0.36585      
 pars:   -3.5513 -2.81435 -1.34642 -0.44033      
 pars:   -3.30092 -3.01944 -1.10395 -0.39263      
 pars:   -3.27833 -3.03821 -1.38152 -0.39631      
 pars:   -3.23173 -2.97174 -2.21731 -0.40477      
 pars:   -3.28771 -3.08271 -5.28966 -0.34232      
 pars:   -3.30222 -3.07091 -5.31779 -0.38305      
 pars:   -3.30222 -3.07091 -5.31779 -0.38305      
#> # A tibble: 108 × 8
#>    id    date                  lon   lat      x      y       x.se       y.se
#>    <chr> <dttm>              <dbl> <dbl>  <dbl>  <dbl>      <dbl>      <dbl>
#>  1 54591 2012-03-05 05:00:00  111. -66.4 12309. -9956.  0.0000100  0.0000100
#>  2 54591 2012-03-06 05:00:00  110. -66.4 12299. -9947. 17.4        0.00763  
#>  3 54591 2012-03-07 05:00:00  110. -66.4 12296. -9956. 25.1       19.2      
#>  4 54591 2012-03-08 05:00:00  110. -66.5 12298. -9970. 21.1       18.5      
#>  5 54591 2012-03-09 05:00:00  110. -66.5 12300. -9972.  8.11       1.22     
#>  6 54591 2012-03-10 05:00:00  110. -66.4 12300. -9955.  5.10       3.03     
#>  7 54591 2012-03-11 05:00:00  110. -66.4 12292. -9958. 18.1       14.3      
#>  8 54591 2012-03-12 05:00:00  110. -66.5 12285. -9962. 18.2        4.41     
#>  9 54591 2012-03-13 05:00:00  110. -66.4 12287. -9952.  5.83       4.87     
#> 10 54591 2012-03-14 05:00:00  110. -66.4 12291. -9939.  4.31       4.36     
#> # ℹ 98 more rows