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
`SpatRaster`

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 neighbourhood 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

`raster::adjacent`

. Default`FALSE`

, which is faster.- 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

`FALSE`

.- id
numeric If not

`NULL`

(default), then function will return`"id"`

column.- numNeighs
A numeric scalar, indicating how many neighbours to return. Must be less than or equal to

`directions`

; which neighbours are random with equal probabilities.- returnDT
A logical. If TRUE, then the function will return the result as a

`data.table`

, if the internals used`data.table`

, i.e., if number of cells is greater than`cutoff.for.data.table`

. User should be warned that this will therefore cause the output format to change depending`cutoff.for.data.table`

. This will be faster for situations where`cutoff.for.data.table = TRUE`

.

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:

use

`data.table`

internallyno 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)

don't make intermediate objects; just put calculation into return statement

The steps used in the algorithm are:

Calculate indices of neighbouring cells

Remove "to" cells that are

`< 1`

or`> numCells`

(i.e., they are above or below raster), using a single modulo calculationwhere 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)

```
library(terra)
#> terra 1.7.78
#>
#> Attaching package: ‘terra’
#> The following object is masked from ‘package:SpaDES.tools’:
#>
#> wrap
origDTThreads <- data.table::setDTthreads(2L)
origNcpus <- options(Ncpus = 2L)
a <- rast(ext(0, 1000, 0, 1000), res = 1)
sam <- sample(1:ncell(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)
# clean up
data.table::setDTthreads(origDTThreads)
options(Ncpus = origNcpus)
```