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
)

Arguments

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.

Value

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.

Details

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.

See also

Other Edge-list generation: edge_dist()

Examples

# 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
# Temporal grouping group_times(DT, datetime = 'datetime', threshold = '20 minutes')
#> 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