direction_to_leader calculates the direction to the leader of each
spatiotemporal group. The function accepts a data.table with
relocation data appended with a rank_position_group_direction column
indicating the ranked position along the group direction generated with
leader_direction_group(return_rank = TRUE). Relocation data should be
in planar coordinates provided in two columns representing the X and Y
coordinates.
Arguments
- DT
input data.table with 'rank_position_group_direction' column generated by
leader_direction_groupand group column generated bygroup_pts- 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'
Value
direction_to_leader returns the input DT appended with
a direction_leader column indicating the direction to the group leader.
A message is returned when the direction_leader column is already exist in the input DT
because it 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 rank_position_group_direction column
generated with leader_direction_group(return_rank = TRUE),
a group column generated with the
group_pts function. The coords and group arguments
expect the names of columns in DT which correspond to the X and Y
coordinates and group columns.
See also
distance_to_leader, leader_direction_group, group_pts
Other Direction functions:
direction_group(),
direction_polarization(),
direction_step()
Examples
# Load data.table
library(data.table)
# Read example data
DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc"))
# (Subset example data to reduce example run time)
DT <- DT[year(datetime) == 2016]
# 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
#> ---
#> 7288: J 700211.6 5509087 2016-12-31 14:00:49 1
#> 7289: J 700165.3 5508825 2016-12-31 16:00:23 1
#> 7290: J 700028.7 5508826 2016-12-31 18:00:53 1
#> 7291: J 700230.9 5508609 2016-12-31 20:00:53 1
#> 7292: J 700110.1 5508383 2016-12-31 22:00:54 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
#> ---
#> 7288: J 700211.6 5509087 2016-12-31 14:00:49 1 0 728
#> 7289: J 700165.3 5508825 2016-12-31 16:00:23 1 0 729
#> 7290: J 700028.7 5508826 2016-12-31 18:00:53 1 0 730
#> 7291: J 700230.9 5508609 2016-12-31 20:00:53 1 0 731
#> 7292: J 700110.1 5508383 2016-12-31 22:00:54 1 0 732
# Spatial grouping with timegroup
group_pts(DT, threshold = 50, 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
#> ---
#> 7288: J 700211.6 5509087 2016-12-31 14:00:49 1 0 728
#> 7289: J 700165.3 5508825 2016-12-31 16:00:23 1 0 729
#> 7290: J 700028.7 5508826 2016-12-31 18:00:53 1 0 730
#> 7291: J 700230.9 5508609 2016-12-31 20:00:53 1 0 731
#> 7292: J 700110.1 5508383 2016-12-31 22:00:54 1 0 732
#> group
#> <int>
#> 1: 1
#> 2: 2
#> 3: 3
#> 4: 4
#> 5: 5
#> ---
#> 7288: 728
#> 7289: 729
#> 7290: 5531
#> 7291: 731
#> 7292: 5532
# Calculate direction at each step
direction_step(
DT = DT,
id = 'ID',
coords = c('X', 'Y'),
projection = 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
#> ---
#> 7288: J 700211.6 5509087 2016-12-31 14:00:49 1 0 728
#> 7289: J 700165.3 5508825 2016-12-31 16:00:23 1 0 729
#> 7290: J 700028.7 5508826 2016-12-31 18:00:53 1 0 730
#> 7291: J 700230.9 5508609 2016-12-31 20:00:53 1 0 731
#> 7292: J 700110.1 5508383 2016-12-31 22:00:54 1 0 732
#> group direction
#> <int> <units>
#> 1: 1 -2.65649015 [rad]
#> 2: 2 2.17592086 [rad]
#> 3: 3 -1.98432277 [rad]
#> 4: 4 1.90650150 [rad]
#> 5: 5 -0.04059949 [rad]
#> ---
#> 7288: 728 -2.99285448 [rad]
#> 7289: 729 -1.59174536 [rad]
#> 7290: 5531 2.36456688 [rad]
#> 7291: 731 -2.67757174 [rad]
#> 7292: 5532 NA [rad]
# Calculate group centroid
centroid_group(DT, coords = c('X', 'Y'))
#> 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
#> ---
#> 7288: J 700211.6 5509087 2016-12-31 14:00:49 1 0 728
#> 7289: J 700165.3 5508825 2016-12-31 16:00:23 1 0 729
#> 7290: J 700028.7 5508826 2016-12-31 18:00:53 1 0 730
#> 7291: J 700230.9 5508609 2016-12-31 20:00:53 1 0 731
#> 7292: J 700110.1 5508383 2016-12-31 22:00:54 1 0 732
#> group direction centroid_X centroid_Y
#> <int> <units> <num> <num>
#> 1: 1 -2.65649015 [rad] 715851.4 5505340
#> 2: 2 2.17592086 [rad] 715822.8 5505289
#> 3: 3 -1.98432277 [rad] 715872.9 5505252
#> 4: 4 1.90650150 [rad] 715820.5 5505231
#> 5: 5 -0.04059949 [rad] 715830.6 5505227
#> ---
#> 7288: 728 -2.99285448 [rad] 700191.6 5509089
#> 7289: 729 -1.59174536 [rad] 700156.0 5508800
#> 7290: 5531 2.36456688 [rad] 700028.7 5508826
#> 7291: 731 -2.67757174 [rad] 700254.6 5508589
#> 7292: 5532 NA [rad] 700110.1 5508383
# Calculate group direction
direction_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
#> ---
#> 7288: J 700211.6 5509087 2016-12-31 14:00:49 1 0 728
#> 7289: J 700165.3 5508825 2016-12-31 16:00:23 1 0 729
#> 7290: J 700028.7 5508826 2016-12-31 18:00:53 1 0 730
#> 7291: J 700230.9 5508609 2016-12-31 20:00:53 1 0 731
#> 7292: J 700110.1 5508383 2016-12-31 22:00:54 1 0 732
#> group direction centroid_X centroid_Y group_direction
#> <int> <units> <num> <num> <units>
#> 1: 1 -2.65649015 [rad] 715851.4 5505340 -2.65649015 [rad]
#> 2: 2 2.17592086 [rad] 715822.8 5505289 2.17592086 [rad]
#> 3: 3 -1.98432277 [rad] 715872.9 5505252 -1.98432277 [rad]
#> 4: 4 1.90650150 [rad] 715820.5 5505231 1.90650150 [rad]
#> 5: 5 -0.04059949 [rad] 715830.6 5505227 -0.04059949 [rad]
#> ---
#> 7288: 728 -2.99285448 [rad] 700191.6 5509089 -3.05184005 [rad]
#> 7289: 729 -1.59174536 [rad] 700156.0 5508800 -2.41173804 [rad]
#> 7290: 5531 2.36456688 [rad] 700028.7 5508826 2.36456688 [rad]
#> 7291: 731 -2.67757174 [rad] 700254.6 5508589 -1.70798015 [rad]
#> 7292: 5532 NA [rad] 700110.1 5508383 NA [rad]
# Calculate leader in terms of position along group direction
leader_direction_group(
DT,
coords = c('X', 'Y'),
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
#> ---
#> 7288: J 700211.6 5509087 2016-12-31 14:00:49 1 0 728
#> 7289: J 700165.3 5508825 2016-12-31 16:00:23 1 0 729
#> 7290: J 700028.7 5508826 2016-12-31 18:00:53 1 0 730
#> 7291: J 700230.9 5508609 2016-12-31 20:00:53 1 0 731
#> 7292: J 700110.1 5508383 2016-12-31 22:00:54 1 0 732
#> group direction centroid_X centroid_Y group_direction
#> <int> <units> <num> <num> <units>
#> 1: 1 -2.65649015 [rad] 715851.4 5505340 -2.65649015 [rad]
#> 2: 2 2.17592086 [rad] 715822.8 5505289 2.17592086 [rad]
#> 3: 3 -1.98432277 [rad] 715872.9 5505252 -1.98432277 [rad]
#> 4: 4 1.90650150 [rad] 715820.5 5505231 1.90650150 [rad]
#> 5: 5 -0.04059949 [rad] 715830.6 5505227 -0.04059949 [rad]
#> ---
#> 7288: 728 -2.99285448 [rad] 700191.6 5509089 -3.05184005 [rad]
#> 7289: 729 -1.59174536 [rad] 700156.0 5508800 -2.41173804 [rad]
#> 7290: 5531 2.36456688 [rad] 700028.7 5508826 2.36456688 [rad]
#> 7291: 731 -2.67757174 [rad] 700254.6 5508589 -1.70798015 [rad]
#> 7292: 5532 NA [rad] 700110.1 5508383 NA [rad]
#> position_group_direction rank_position_group_direction
#> <num> <num>
#> 1: 0.00000 1
#> 2: 0.00000 1
#> 3: 0.00000 1
#> 4: 0.00000 1
#> 5: 0.00000 1
#> ---
#> 7288: -19.72453 2
#> 7289: -23.62960 5
#> 7290: 0.00000 1
#> 7291: -16.87561 5
#> 7292: NA 1
# Calculate direction to leader
direction_to_leader(DT, coords = c('X', 'Y'))
#> Warning: groups found missing leader (rank_position_group_direction == 1):
#> 732, 1464, 4649
#> Index: <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
#> ---
#> 7288: J 700211.6 5509087 2016-12-31 14:00:49 1 0 728
#> 7289: J 700165.3 5508825 2016-12-31 16:00:23 1 0 729
#> 7290: J 700028.7 5508826 2016-12-31 18:00:53 1 0 730
#> 7291: J 700230.9 5508609 2016-12-31 20:00:53 1 0 731
#> 7292: J 700110.1 5508383 2016-12-31 22:00:54 1 0 732
#> group direction centroid_X centroid_Y group_direction
#> <int> <units> <num> <num> <units>
#> 1: 1 -2.65649015 [rad] 715851.4 5505340 -2.65649015 [rad]
#> 2: 2 2.17592086 [rad] 715822.8 5505289 2.17592086 [rad]
#> 3: 3 -1.98432277 [rad] 715872.9 5505252 -1.98432277 [rad]
#> 4: 4 1.90650150 [rad] 715820.5 5505231 1.90650150 [rad]
#> 5: 5 -0.04059949 [rad] 715830.6 5505227 -0.04059949 [rad]
#> ---
#> 7288: 728 -2.99285448 [rad] 700191.6 5509089 -3.05184005 [rad]
#> 7289: 729 -1.59174536 [rad] 700156.0 5508800 -2.41173804 [rad]
#> 7290: 5531 2.36456688 [rad] 700028.7 5508826 2.36456688 [rad]
#> 7291: 731 -2.67757174 [rad] 700254.6 5508589 -1.70798015 [rad]
#> 7292: 5532 NA [rad] 700110.1 5508383 NA [rad]
#> position_group_direction rank_position_group_direction direction_leader
#> <num> <num> <num>
#> 1: 0.00000 1 NaN
#> 2: 0.00000 1 NaN
#> 3: 0.00000 1 NaN
#> 4: 0.00000 1 NaN
#> 5: 0.00000 1 NaN
#> ---
#> 7288: -19.72453 2 3.0354697
#> 7289: -23.62960 5 -1.7460659
#> 7290: 0.00000 1 NaN
#> 7291: -16.87561 5 -0.7660613
#> 7292: NA 1 NaN