Wrap coordinates or pixels in a torus-like fashion

Source: R/neighbourhood.R

Generally useful for model development purposes. Primarily used internally in e.g., crw if torus = TRUE.

wrapTorus(X, bounds, withHeading = FALSE)

wrap(X, bounds, withHeading = FALSE)

Arguments

X

SpatVector, sf, or matrix of coordinates.

bounds

Either a SpatRaster*, Extent, or bbox object defining bounds to wrap around.

withHeading

logical. If TRUE, the previous points must be wrapped also so that the subsequent heading calculation will work. Default FALSE. See details.

Value

Object of the same class as X, but with coordinates updated to reflect the wrapping.

Details

This function was named wrap() until version 2.1.3. It was renamed because terra::wrap() means something entirely different – it serialises a SpatRaster or SpatVector so it can be saved or sent to a parallel worker. Since this package imports terra, both were routinely on the search path and whichever was attached last silently masked the other, so a call to wrap() could do either thing depending on load order. wrap() remains as a deprecated alias.

If withHeading used, then X must be an sf or SpatVector object that contains two columns, x1 and y1, with the immediately previous agent locations.

wrap() is deprecated in favour of wrapTorus(); see the note above on why it was renamed.

Author

Eliot McIntire

Examples

origDTThreads <- data.table::setDTthreads(2L)
origNcpus <- options(Ncpus = 2L)

xrange <- yrange <- c(-50, 50)
hab <- terra::rast(terra::ext(c(xrange, yrange)))
hab[] <- 0

# initialize agents
N <- 10

# previous points
x1 <- y1 <- rep(0, N)
# initial points
starts <- cbind(x = stats::runif(N, xrange[1], xrange[2]),
                y = stats::runif(N, yrange[1], yrange[2]))

# create the agent object # the x1 and y1 are needed for "previous location"
agent <- terra::vect(data.frame(x1, y1, starts), geom = c("x", "y"))

ln <- rlnorm(N, 1, 0.02) # log normal step length
sd <- 30 # could be specified globally in params

if (interactive()) {
  # clearPlot()
  terra::plot(hab, col = "white")
}

for (i in 1:10) {
  agent <- crw(agent = agent, extent = terra::ext(hab), stepLength = ln,
               stddev = sd, lonlat = FALSE, torus = FALSE) # don't wrap
  if (interactive()) terra::plot(agent[, 1], add = TRUE, col = 1:10)
}
terra::crds(agent) # many are "off" the map, i.e., beyond the extent of hab
#>                x          y
#>  [1,]  -7.359131  47.350120
#>  [2,] -36.349039  -4.654296
#>  [3,] -39.489929 -15.540533
#>  [4,]  31.315504  52.929017
#>  [5,]  46.081860 -18.054884
#>  [6,] -19.956107  22.787570
#>  [7,] -66.934582 -30.752109
#>  [8,] -68.224197  18.961591
#>  [9,]  24.542212 -62.033998
#> [10,] -40.338536  42.934977
agent <- SpaDES.tools::wrapTorus(agent, bounds = terra::ext(hab))
terra::plot(agent, add = TRUE, col = 1:10) # now inside the extent of hab
#> Error in graphics::plot.xy(list(x = g[, 3], y = g[, 4]), type = "p", pch = pch,     col = col, cex = cex, ...): plot.new has not been called yet

# clean up
data.table::setDTthreads(origDTThreads)
options(Ncpus = origNcpus)