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 = 2000,
  append = TRUE,
  barrier = NULL,
  onland = NULL,
  ...
)

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. Ignored if an alternate simple feature barrier is provided (see barrier). 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.
barrier: a user-supplied barrier simple feature POLYGON or MULTIPOLYGON object. Default is NULL, in which case rnaturalearth data are used.
onland: a data frame of intervals when individuals are known to be on land, with columns id, start and end (POSIXct). Locations within these intervals are not re-routed. Default is NULL.
...: additional arguments passed to pathroutr::prt_visgraph. If the ssm fit was produced with haulout information (via the haulout argument of fit_ssm or by calling smru_haulout before fitting), locations within haulout periods (ho = 1) are automatically exempt from rerouting. These locations are known to be on land by design and should not be moved into water.

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.07869 -3.34599 -0.26131 -1.24778      
 pars:   -4.46622 -1.62752 -0.49092 0.12577      
 pars:   -3.18442 -2.86246 -0.30197 -0.80152      
 pars:   -3.40949 -3.30584 -0.49915 -0.40195      
 pars:   -3.06904 -3.1641 -1.05456 -0.36592      
 pars:   -3.55185 -2.81433 -1.34577 -0.44032      
 pars:   -3.30075 -3.01959 -1.10393 -0.39264      
 pars:   -3.27829 -3.03843 -1.38115 -0.39634      
 pars:   -3.2318 -2.97181 -2.21587 -0.40477      
 pars:   -3.28781 -3.0824 -5.29383 -0.34231      
 pars:   -3.30223 -3.07095 -5.32168 -0.38301      
 pars:   -3.30223 -3.07095 -5.32168 -0.38301      
#> # A tibble: 113 × 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.00001000  0.00001000
#>  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      
#> # ℹ 103 more rows