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 (<1e4) and data.table for larger numbers of loci
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 = 2000, torus = FALSE, id = NULL, numNeighs = NULL, returnDT = FALSE )
x 


cells  vector of cell numbers for which adjacent cells should be found. Cell numbers start with 1 in the upperleft 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 
sort  logical. Whether the outputs should be sorted or not, using cell ids
of the 
pairs  logical. If 
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  numeric indicating number of cells in the raster.
Using this with 
match.adjacent  logical. Should the returned object be the same as

cutoff.for.data.table  numeric. If the number of cells is above this value, the function uses data.table which is faster with large numbers of cells. Default is 5000, which appears to be the turning point where data.table becomes faster. 
torus  Logical. Should the spread event wrap around to the other side of the raster?
Default is 
id  numeric If not 
numNeighs  A numeric scalar, indicating how many neighbours to return. Must be
less than or equal to 
returnDT  A logical. If TRUE, then the function will return the result
as a 
Either a matrix (if more than 1 column, i.e., pairs = TRUE
,
and/or id
is provided), a vector (if only one column), or a data.table
(if cutoff.for.data.table
is less than length(cells)
and
returnDT
is TRUE
.
To get a consistent output, say a matrix, it would be wise to test the output
for its class.
The variable output is done to minimize coercion to maintain speed.
The columns will be one or more of id
, from
, to
.
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)
Eliot McIntire
#>