edge_nn returns edge-lists defined by the nearest neighbour. The function
expects 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, or in a geometry column
prepared by the helper function get_geometry().
Usage
edge_nn(
DT = NULL,
id = NULL,
coords = NULL,
timegroup,
crs = NULL,
splitBy = NULL,
threshold = NULL,
geometry = "geometry",
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. Note: the order is assumed X followed by Y column names
- timegroup
timegroup field in the DT within which the output will be calculated
- crs
numeric or character defining the coordinate reference system to be passed to sf::st_crs. For example, either
crs = "EPSG:32736"orcrs = 32736. Used only if coords are provided, see details under Interface- splitBy
(optional) character string or vector of grouping column name(s) upon which the output will be calculated
- threshold
(optional) spatial distance threshold to set maximum distance between an individual and their neighbour.
- geometry
simple feature geometry list column name, generated by
get_geometry(). Default 'geometry', see details under Interface- returnDist
logical indicating if the distance between individuals should be returned. If FALSE (default), only individual columns (and timegroup, splitBy columns if provided) are returned. If TRUE, a column "distance" is also returned indicating the distance between individuals in the units of the
crs, or ifcrs = NULLno units are set.
Value
edge_nn returns a data.table with three columns: timegroup, ID
and NN. If 'returnDist' is TRUE, a 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.
Note: unlike many other functions (eg. group_pts) in spatsoc, edge_nn
needs to be reassigned. See details in
FAQ.
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, timegroup (and optional splitBy) arguments expect the names of
columns in DT which correspond to the individual identifier, and timegroup
(generated by group_times) and additional grouping columns.
If a threshold is provided, it should match the units of the coordinates.
The threshold can be provided with units specified using the units package
(eg. threshold = units::set_units(10, m)) which will be checked against the
units of the coordinates using the crs. If units are not specified, the
threshold is assumed to be in the units of the coordinates.
The timegroup argument is required to define the temporal groups within
which edge nearest neighbours are calculated. The intended framework is to
group rows temporally with group_times then spatially with edge_nn. If
you have already calculated temporal groups without group_times, you can
pass this column to the timegroup argument. Note that the expectation is
that each individual will be observed only once per timegroup. Caution that
accidentally including huge numbers of rows within timegroups can overload
your machine since all pairwise distances are calculated within each
timegroup.
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 below under "Interface" for details on providing coordinates and under "Distance function" for details on underlying distance function used.
Interface
Two interfaces are available for providing coordinates:
Provide
coordsandcrs. Thecoordsargument expects the names of the X and Y coordinate columns. Thecrsargument expects a character string or numeric defining the coordinate reference system to be passed to sf::st_crs. For example, for UTM zone 36S (EPSG 32736), the crs argument iscrs = "EPSG:32736"orcrs = 32736. See https://spatialreference.org for a list of EPSG codes.(New!) Provide
geometry. Thegeometryargument allows the user to supply ageometrycolumn that represents the coordinates as a simple feature geometry list column. This interface expects the user to prepare their input DT withget_geometry(). To use this interface, leave thecoordsandcrsargumentsNULL, and the default argument forgeometry('geometry') will be used directly.
Distance function
The underlying distance function used depends on the crs of the coordinates or geometry provided.
If the crs is longlat degrees (as determined by
sf::st_is_longlat()), the distance function issf::st_distance()which passes tos2::s2_distance()ifsf::sf_use_s2()is TRUE andlwgeom::st_geod_distance()ifsf::sf_use_s2()is FALSE. The distance returned has units set according to the crs.If the crs is not longlat degrees (eg. NULL, NA_crs_, or projected), the distance function used is
stats::dist(), maintaining expected behaviour from previous versions. The distance returned does not have units set.
Note: in both cases, if the coordinates are NA then the result will be NA.
See also
Other Edge-list generation:
edge_alignment(),
edge_delay(),
edge_direction(),
edge_dist()
Other Distance functions:
distance_to_centroid(),
distance_to_leader(),
edge_dist(),
edge_zones()
Examples
# Load data.table
library(data.table)
# Read example data
DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc"))
# Select only individuals A, B, C for this example
DT <- DT[ID %in% c('A', 'B', 'C')]
# Cast the character column to POSIXct
DT[, datetime := as.POSIXct(datetime, tz = 'UTC')]
#> ID X Y datetime population
#> <char> <num> <num> <POSc> <int>
#> 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
#> ---
#> 4265: C 702093.6 5510180 2017-02-28 14:00:44 1
#> 4266: C 702086.0 5510183 2017-02-28 16:00:42 1
#> 4267: C 702961.8 5509447 2017-02-28 18:00:53 1
#> 4268: C 703130.4 5509528 2017-02-28 20:00:54 1
#> 4269: C 702872.3 5508531 2017-02-28 22:00:18 1
# Temporal grouping
group_times(DT, datetime = 'datetime', threshold = '20 minutes')
#> ID X Y datetime population minutes timegroup
#> <char> <num> <num> <POSc> <int> <int> <int>
#> 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
#> ---
#> 4265: C 702093.6 5510180 2017-02-28 14:00:44 1 0 1393
#> 4266: C 702086.0 5510183 2017-02-28 16:00:42 1 0 1394
#> 4267: C 702961.8 5509447 2017-02-28 18:00:53 1 0 1440
#> 4268: C 703130.4 5509528 2017-02-28 20:00:54 1 0 1395
#> 4269: C 702872.3 5508531 2017-02-28 22:00:18 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
#> <int> <char> <char> <num>
#> 1: 1 A <NA> NA
#> 2: 1 B <NA> NA
#> 3: 1 C <NA> NA
#> 4: 2 A <NA> NA
#> 5: 2 B <NA> NA
#> ---
#> 4265: 1438 C <NA> NA
#> 4266: 1439 B <NA> NA
#> 4267: 1439 C <NA> NA
#> 4268: 1440 B <NA> NA
#> 4269: 1440 C <NA> NA
# Or, using the new geometry interface
get_geometry(DT, coords = c('X', 'Y'), crs = 32736)
#> ID X Y datetime population minutes timegroup
#> <char> <num> <num> <POSc> <int> <int> <int>
#> 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
#> ---
#> 4265: C 702093.6 5510180 2017-02-28 14:00:44 1 0 1393
#> 4266: C 702086.0 5510183 2017-02-28 16:00:42 1 0 1394
#> 4267: C 702961.8 5509447 2017-02-28 18:00:53 1 0 1440
#> 4268: C 703130.4 5509528 2017-02-28 20:00:54 1 0 1395
#> 4269: C 702872.3 5508531 2017-02-28 22:00:18 1 0 1396
#> geometry
#> <sfc_POINT>
#> 1: POINT (715851.4 5505340)
#> 2: POINT (715822.8 5505289)
#> 3: POINT (715872.9 5505252)
#> 4: POINT (715820.5 5505231)
#> 5: POINT (715830.6 5505227)
#> ---
#> 4265: POINT (702093.6 5510180)
#> 4266: POINT (702086 5510183)
#> 4267: POINT (702961.8 5509447)
#> 4268: POINT (703130.4 5509528)
#> 4269: POINT (702872.3 5508531)
edge_nn(DT, threshold = 100, id = 'ID', timegroup = 'timegroup', returnDist = TRUE)
#> timegroup ID NN distance
#> <int> <char> <char> <num>
#> 1: 1 A <NA> NA
#> 2: 1 B <NA> NA
#> 3: 1 C <NA> NA
#> 4: 2 A <NA> NA
#> 5: 2 B <NA> NA
#> ---
#> 4265: 1438 C <NA> NA
#> 4266: 1439 B <NA> NA
#> 4267: 1439 C <NA> NA
#> 4268: 1440 B <NA> NA
#> 4269: 1440 C <NA> NA