distance_to_centroid calculates the distance of each relocation to the
centroid of the spatiotemporal group identified by group_pts. The
function accepts a data.table with relocation data appended with a
group column from group_pts and centroid columns from
centroid_group. Relocation data should be in planar coordinates
provided in two columns representing the X and Y coordinates.
Usage
distance_to_centroid(
DT = NULL,
coords = NULL,
group = "group",
return_rank = FALSE,
ties.method = NULL
)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'- return_rank
boolean if rank distance should also be returned, default FALSE
- ties.method
Value
distance_to_centroid returns the input DT appended with
a distance_centroid column indicating the distance to group centroid
and, optionally, a rank_distance_centroid column indicating the
within group rank distance to 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.
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 columns generated with the
centroid_group function. The coords and group arguments
expect the names of columns in DT which correspond to the X and Y
coordinates and group columns. 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 also
Other Distance functions:
direction_to_centroid(),
distance_to_leader()
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', na.rm = TRUE)
#> 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',
return_rank = TRUE
)
#> 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