Given the mean direction of a group of animals, leader_direction_group
shifts the coordinate system to a new origin at the group centroid and
rotates the coordinate system by the mean direction to return each
individual's position along the mean direction, representing leadership in
terms of the front-back position in each group's mean direction.
Usage
leader_direction_group(
DT = NULL,
group_direction = "group_direction",
coords = NULL,
group = "group",
return_rank = FALSE,
ties.method = "average"
)Arguments
- DT
input data.table with group direction columns generated by
direction_groupand centroid columns generated bycentroid_group- group_direction
group_direction column name generated using
direction_group, default 'group_direction'- 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
leader_direction_group returns the input DT appended
with a position_group_direction column indicating the position along
the group direction in the units of the projection and, optionally when
return_rank = TRUE, a rank_position_group_direction column
indicating the the ranked position along the group direction.
A message is returned when position_group_direction or
rank_position_group_direction columns already exist in the input
DT, because they will be overwritten.
Details
The function accepts a data.table with relocation data appended with a
group_direction column from direction_group and group centroid
columns from centroid_group. Relocation data should be in two columns
representing the X and Y coordinates.
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.
The group_direction argument expects the names of columns in DT
which correspond to the mean group direction generated by
direction_group. The mean group direction column is expected in units
of radians. The coords arguments expects the names of columns in
DT which correspond to the X and Y coordinate columns. The
return_rank argument controls if the rank of each individual's
distance to the group centroid is also returned. If return_rank is
TRUE, the group argument is required to specify the group column
generated by group_pts. The ties.method argument is passed to
data.table::frank, see details at
?data.table::frank.
References
See examples of measuring leadership along group direction (also called forefront index):
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'))
#> 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
#> <num>
#> 1: 0.00000
#> 2: 0.00000
#> 3: 0.00000
#> 4: 0.00000
#> 5: 0.00000
#> ---
#> 7288: -19.72453
#> 7289: -23.62960
#> 7290: 0.00000
#> 7291: -16.87561
#> 7292: NA