distance_to_centroid calculates the distance of each relocation to the
centroid of the spatiotemporal group identified by group_pts. The function
expects a data.table with relocation data appended with a group column
from group_pts and centroid columns from centroid_group. Relocation data
should be provided in two columns representing the X and Y coordinates, or in
a geometry column prepared by the helper function get_geometry().
Usage
distance_to_centroid(
DT = NULL,
coords = NULL,
group = "group",
crs = NULL,
return_rank = TRUE,
ties.method = NULL,
geometry = "geometry"
)Arguments
- DT
input data.table with centroid columns generated by eg.
centroid_group- coords
character vector of X coordinate and Y coordinate column names. Note: the order is assumed X followed by Y column names
- group
group column name, generated by
group_pts, default 'group'- 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- return_rank
logical if rank distance should also be returned, default TRUE
- ties.method
- geometry
simple feature geometry list column name, generated by
get_geometry(). Default 'geometry', see details under Interface
Value
distance_to_centroid returns the input DT appended with a
distance_centroid column indicating the distance to the group centroid
and, optionally, a rank_distance_centroid column indicating the within
group rank distance to the group centroid (if return_rank = TRUE).
A message is returned when distance_centroid and optional
rank_distance_centroid columns already exist in the input DT, because
they will be overwritten.
See details for appending outputs using modify-by-reference in the 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() or by reassigning using
data.table::data.table().
This function expects a group column present generated with the group_pts
function and centroid coordinate column(s) generated with the
centroid_group function. The group arguments expect the names of columns
in DT which correspond to the group column. The return_rank argument
controls if the rank of each individual's distance to the group centroid is
also returned. The ties.method argument is passed to data.table::frank,
see details at ?data.table::frank().
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
centroid_group, group_pts, sf::st_distance()
Other Distance functions:
distance_to_leader(),
edge_dist(),
edge_nn(),
edge_zones()
Other Centroid functions:
centroid_dyad(),
centroid_fusion(),
centroid_group(),
direction_to_centroid()
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
#> <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
#> ---
#> 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
#> <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
#> ---
#> 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
# Spatial grouping with timegroup
group_pts(DT, threshold = 5, id = 'ID',
coords = c('X', 'Y'), timegroup = 'timegroup')
#> 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
#> ---
#> 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
#> group
#> <int>
#> 1: 1
#> 2: 2
#> 3: 3
#> 4: 4
#> 5: 5
#> ---
#> 14293: 13882
#> 14294: 13883
#> 14295: 13884
#> 14296: 13885
#> 14297: 13886
# Calculate group centroid
centroid_group(DT, coords = c('X', 'Y'), group = 'group')
#> 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
#> ---
#> 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
#> group centroid_X centroid_Y
#> <int> <num> <num>
#> 1: 1 715851.4 5505340
#> 2: 2 715822.8 5505289
#> 3: 3 715872.9 5505252
#> 4: 4 715820.5 5505231
#> 5: 5 715830.6 5505227
#> ---
#> 14293: 13882 700616.5 5509069
#> 14294: 13883 700622.6 5509065
#> 14295: 13884 700657.5 5509277
#> 14296: 13885 700610.3 5509269
#> 14297: 13886 700744.0 5508782
# Calculate distance to group centroid
distance_to_centroid(
DT,
coords = c('X', 'Y'),
group = 'group',
)
#> 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
#> ---
#> 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
#> group centroid_X centroid_Y distance_centroid rank_distance_centroid
#> <int> <num> <num> <num> <num>
#> 1: 1 715851.4 5505340 0 1
#> 2: 2 715822.8 5505289 0 1
#> 3: 3 715872.9 5505252 0 1
#> 4: 4 715820.5 5505231 0 1
#> 5: 5 715830.6 5505227 0 1
#> ---
#> 14293: 13882 700616.5 5509069 0 1
#> 14294: 13883 700622.6 5509065 0 1
#> 14295: 13884 700657.5 5509277 0 1
#> 14296: 13885 700610.3 5509269 0 1
#> 14297: 13886 700744.0 5508782 0 1
# 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
#> ---
#> 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
#> group centroid_X centroid_Y distance_centroid rank_distance_centroid
#> <int> <num> <num> <num> <num>
#> 1: 1 715851.4 5505340 0 1
#> 2: 2 715822.8 5505289 0 1
#> 3: 3 715872.9 5505252 0 1
#> 4: 4 715820.5 5505231 0 1
#> 5: 5 715830.6 5505227 0 1
#> ---
#> 14293: 13882 700616.5 5509069 0 1
#> 14294: 13883 700622.6 5509065 0 1
#> 14295: 13884 700657.5 5509277 0 1
#> 14296: 13885 700610.3 5509269 0 1
#> 14297: 13886 700744.0 5508782 0 1
#> 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)
#> ---
#> 14293: POINT (700616.5 5509069)
#> 14294: POINT (700622.6 5509065)
#> 14295: POINT (700657.5 5509277)
#> 14296: POINT (700610.3 5509269)
#> 14297: POINT (700744 5508782)
group_pts(DT, threshold = 5, id = 'ID', timegroup = 'timegroup')
#> group column will be overwritten by this function
#> 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
#> ---
#> 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
#> centroid_X centroid_Y distance_centroid rank_distance_centroid
#> <num> <num> <num> <num>
#> 1: 715851.4 5505340 0 1
#> 2: 715822.8 5505289 0 1
#> 3: 715872.9 5505252 0 1
#> 4: 715820.5 5505231 0 1
#> 5: 715830.6 5505227 0 1
#> ---
#> 14293: 700616.5 5509069 0 1
#> 14294: 700622.6 5509065 0 1
#> 14295: 700657.5 5509277 0 1
#> 14296: 700610.3 5509269 0 1
#> 14297: 700744.0 5508782 0 1
#> geometry group
#> <sfc_POINT> <int>
#> 1: POINT (715851.4 5505340) 1
#> 2: POINT (715822.8 5505289) 2
#> 3: POINT (715872.9 5505252) 3
#> 4: POINT (715820.5 5505231) 4
#> 5: POINT (715830.6 5505227) 5
#> ---
#> 14293: POINT (700616.5 5509069) 13882
#> 14294: POINT (700622.6 5509065) 13883
#> 14295: POINT (700657.5 5509277) 13884
#> 14296: POINT (700610.3 5509269) 13885
#> 14297: POINT (700744 5508782) 13886
centroid_group(DT)
#> 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
#> ---
#> 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
#> centroid_X centroid_Y distance_centroid rank_distance_centroid
#> <num> <num> <num> <num>
#> 1: 715851.4 5505340 0 1
#> 2: 715822.8 5505289 0 1
#> 3: 715872.9 5505252 0 1
#> 4: 715820.5 5505231 0 1
#> 5: 715830.6 5505227 0 1
#> ---
#> 14293: 700616.5 5509069 0 1
#> 14294: 700622.6 5509065 0 1
#> 14295: 700657.5 5509277 0 1
#> 14296: 700610.3 5509269 0 1
#> 14297: 700744.0 5508782 0 1
#> geometry group centroid
#> <sfc_POINT> <int> <sfc_POINT>
#> 1: POINT (715851.4 5505340) 1 POINT (715851.4 5505340)
#> 2: POINT (715822.8 5505289) 2 POINT (715822.8 5505289)
#> 3: POINT (715872.9 5505252) 3 POINT (715872.9 5505252)
#> 4: POINT (715820.5 5505231) 4 POINT (715820.5 5505231)
#> 5: POINT (715830.6 5505227) 5 POINT (715830.6 5505227)
#> ---
#> 14293: POINT (700616.5 5509069) 13882 POINT (700616.5 5509069)
#> 14294: POINT (700622.6 5509065) 13883 POINT (700622.6 5509065)
#> 14295: POINT (700657.5 5509277) 13884 POINT (700657.5 5509277)
#> 14296: POINT (700610.3 5509269) 13885 POINT (700610.3 5509269)
#> 14297: POINT (700744 5508782) 13886 POINT (700744 5508782)
direction_to_centroid(DT)
#> 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
#> ---
#> 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
#> centroid_X centroid_Y distance_centroid rank_distance_centroid
#> <num> <num> <num> <num>
#> 1: 715851.4 5505340 0 1
#> 2: 715822.8 5505289 0 1
#> 3: 715872.9 5505252 0 1
#> 4: 715820.5 5505231 0 1
#> 5: 715830.6 5505227 0 1
#> ---
#> 14293: 700616.5 5509069 0 1
#> 14294: 700622.6 5509065 0 1
#> 14295: 700657.5 5509277 0 1
#> 14296: 700610.3 5509269 0 1
#> 14297: 700744.0 5508782 0 1
#> geometry group centroid
#> <sfc_POINT> <int> <sfc_POINT>
#> 1: POINT (715851.4 5505340) 1 POINT (715851.4 5505340)
#> 2: POINT (715822.8 5505289) 2 POINT (715822.8 5505289)
#> 3: POINT (715872.9 5505252) 3 POINT (715872.9 5505252)
#> 4: POINT (715820.5 5505231) 4 POINT (715820.5 5505231)
#> 5: POINT (715830.6 5505227) 5 POINT (715830.6 5505227)
#> ---
#> 14293: POINT (700616.5 5509069) 13882 POINT (700616.5 5509069)
#> 14294: POINT (700622.6 5509065) 13883 POINT (700622.6 5509065)
#> 14295: POINT (700657.5 5509277) 13884 POINT (700657.5 5509277)
#> 14296: POINT (700610.3 5509269) 13885 POINT (700610.3 5509269)
#> 14297: POINT (700744 5508782) 13886 POINT (700744 5508782)
#> direction_centroid
#> <units>
#> 1: NaN [rad]
#> 2: NaN [rad]
#> 3: NaN [rad]
#> 4: NaN [rad]
#> 5: NaN [rad]
#> ---
#> 14293: NaN [rad]
#> 14294: NaN [rad]
#> 14295: NaN [rad]
#> 14296: NaN [rad]
#> 14297: NaN [rad]