edge_nn
returns edge lists defined by the nearest neighbour. The
function accepts a data.table
with relocation data, individual
identifiers and a threshold argument. The threshold argument is used to
specify the criteria for distance between points which defines a group.
Relocation data should be in two columns representing the X and Y
coordinates.
edge_nn( DT = NULL, id = NULL, coords = NULL, timegroup, splitBy = NULL, threshold = NULL, returnDist = FALSE )
DT | input data.table |
---|---|
id | Character string of ID column name |
coords | Character vector of X coordinate and Y coordinate column names |
timegroup | timegroup field in the DT upon which the grouping will be calculated |
splitBy | (optional) character string or vector of grouping column name(s) upon which the grouping will be calculated |
threshold | (optional) spatial distance threshold to set maximum distance between an individual and their neighbour. |
returnDist | boolean indicating if the distance between individuals should be returned. If FALSE (default), only ID, NN columns (and timegroup, splitBy columns if provided) are returned. If TRUE, another column "distance" is returned indicating the distance between ID and NN. |
edge_nn
returns a data.table
with three columns:
timegroup, ID and NN. If 'returnDist' is TRUE, column 'distance' is
returned indicating the distance between ID and NN.
The ID and NN columns represent the edges defined by the nearest neighbours
(and temporal thresholds with group_times
).
If an individual was alone in a timegroup or splitBy, or did not have any neighbours within the threshold distance, they are assigned NA for nearest neighbour.
The DT
must be a data.table
. If your data is a
data.frame
, you can convert it by reference using
data.table::setDT
.
The id
, coords
(and optional timegroup
and
splitBy
) arguments expect the names of a column in DT
which
correspond to the individual identifier, X and Y coordinates, timegroup
(generated by group_times
) and additional grouping columns.
The threshold
must be provided in the units of the coordinates. The
threshold
must be larger than 0. The coordinates must be planar
coordinates (e.g.: UTM). In the case of UTM, a threshold
= 50 would
indicate a 50m distance threshold.
The timegroup
argument is optional, but recommended to pair with
group_times
. The intended framework is to group rows temporally
with group_times
then spatially with edge_nn
(or
grouping functions).
The splitBy
argument offers further control over grouping. If within
your DT
, you have multiple populations, subgroups or other distinct
parts, you can provide the name of the column which identifies them to
splitBy
. edge_nn
will only consider rows within each
splitBy
subgroup.
Other Edge-list generation:
edge_dist()
# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc")) # Cast the character column to POSIXct DT[, datetime := as.POSIXct(datetime, tz = 'UTC')]#> ID X Y datetime population #> 1: A 715851.4 5505340 2016-11-01 00:00:54 1 #> 2: A 715822.8 5505289 2016-11-01 02:01:22 1 #> 3: A 715872.9 5505252 2016-11-01 04:01:24 1 #> 4: A 715820.5 5505231 2016-11-01 06:01:05 1 #> 5: A 715830.6 5505227 2016-11-01 08:01:11 1 #> --- #> 14293: J 700616.5 5509069 2017-02-28 14:00:54 1 #> 14294: J 700622.6 5509065 2017-02-28 16:00:11 1 #> 14295: J 700657.5 5509277 2017-02-28 18:00:55 1 #> 14296: J 700610.3 5509269 2017-02-28 20:00:48 1 #> 14297: J 700744.0 5508782 2017-02-28 22:00:39 1#> ID X Y datetime population minutes timegroup #> 1: A 715851.4 5505340 2016-11-01 00:00:54 1 0 1 #> 2: A 715822.8 5505289 2016-11-01 02:01:22 1 0 2 #> 3: A 715872.9 5505252 2016-11-01 04:01:24 1 0 3 #> 4: A 715820.5 5505231 2016-11-01 06:01:05 1 0 4 #> 5: A 715830.6 5505227 2016-11-01 08:01:11 1 0 5 #> --- #> 14293: J 700616.5 5509069 2017-02-28 14:00:54 1 0 1393 #> 14294: J 700622.6 5509065 2017-02-28 16:00:11 1 0 1394 #> 14295: J 700657.5 5509277 2017-02-28 18:00:55 1 0 1440 #> 14296: J 700610.3 5509269 2017-02-28 20:00:48 1 0 1395 #> 14297: J 700744.0 5508782 2017-02-28 22:00:39 1 0 1396# Edge list generation edges <- edge_nn(DT, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Edge list generation using maximum distance threshold edges <- edge_nn(DT, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', threshold = 100) # Edge list generation, returning distance between nearest neighbours edge_nn(DT, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', threshold = 100, returnDist = TRUE)#> timegroup ID NN distance #> 1: 1 A <NA> NA #> 2: 1 B G 5.782904 #> 3: 1 C <NA> NA #> 4: 1 D <NA> NA #> 5: 1 E H 65.061671 #> --- #> 14293: 1440 F I 7.512922 #> 14294: 1440 G <NA> NA #> 14295: 1440 H <NA> NA #> 14296: 1440 I C 2.831071 #> 14297: 1440 J <NA> NA