SpaDES (version 1.1.4)

adj.raw: Fast `adjacent` function, and Just In Time compiled version

Description

Faster function for determining the cells of the 4, 8 or bishop neighbours of the cells. This is a hybrid function that uses matrix for small numbers of loci (

Usage

adj.raw(x = NULL, cells, directions = 8, sort = FALSE, pairs = TRUE,
  include = FALSE, target = NULL, numCol = NULL, numCell = NULL,
  match.adjacent = FALSE, cutoff.for.data.table = 10000, torus = FALSE,
  id = NULL)

adj(x = NULL, cells, directions = 8, sort = FALSE, pairs = TRUE, include = FALSE, target = NULL, numCol = NULL, numCell = NULL, match.adjacent = FALSE, cutoff.for.data.table = 10000, torus = FALSE, id = NULL)

Arguments

x
Raster* object for which adjacency will be calculated.
cells
vector of cell numbers for which adjacent cells should be found. Cell numbers start with 1 in the upper-left corner and increase from left to right and from top to bottom
directions
the number of directions in which cells should be connected: 4 (rook's case), 8 (queen's case), or 'bishop' to connect cells with one-cell diagonal moves. Or a neigborhood matrix (see Details)
sort
logical. Whether the outputs should be sorted or not, using Cell IDs of the from cells (and to cells, if match.adjacent is TRUE.
pairs
logical. If TRUE, a matrix of pairs of adjacent cells is returned. If FALSE, a vector of cells adjacent to cells is returned
include
logical. Should the focal cells be included in the result?
target
a vector of cells that can be spread to. This is the inverse of a mask.
numCol
numeric indicating number of columns in the raster. Using this with numCell is a bit faster execution time.
numCell
numeric indicating number of cells in the raster. Using this with numCol is a bit faster execution time.
match.adjacent
logical. Should the returned object be the same as the adjacent function in the raster package.
cutoff.for.data.table
numeric. Above this value, the function uses data.table which is faster with large numbers of cells.
torus
Logical. Should the spread event wrap around to the other side of the raster. Default is FALSE.
id
numeric If not NULL, then function will return "id" column. Default NULL.

Value

  • a matrix of one or two columns, from and to.

Details

Between 4x (large number loci) to 200x (small number loci) speed gains over adjacent in raster package. There is some extra speed gain if NumCol and NumCells are passed rather than a raster. Efficiency gains come from: 1. use data.table internally - no need to remove NAs because wrapped or outside points are just removed directly with data.table - use data.table to sort and fast select (though not fastest possible) 2. don't make intermediate objects; just put calculation into return statement

The steps used in the algorithm are: 1. Calculate indices of neighbouring cells 2. Remove "to" cells that are - <1 or="">numCells (i.e., they are above or below raster), using a single modulo calculation - where the modulo of "to" cells is equal to 1 if "from" cells are 0 (wrapped right to left) - or where the modulo of the "to" cells is equal to 0 if "from" cells are 1 (wrapped left to right)

See Also

adjacent

Examples

Run this code
library(raster)
a <- raster(extent(0, 1000, 0, 1000), res = 1)
sam <- sample(1:length(a), 1e4)
numCol <- ncol(a)
numCell <- ncell(a)
adj.new <- adj(numCol = numCol, numCell = numCell, cells = sam, directions = 8)
adj.new <- adj(numCol = numCol, numCell = numCell, cells = sam, directions = 8,
  include = TRUE)
if (interactive()) print(head(adj.new))

Run the code above in your browser using DataCamp Workspace