direction_group calculates the mean direction of all individuals in
each spatiotemporal group identified by group_pts. The function
expects a data.table with relocation data appended with a
direction column from direction_step and a group column
from group_pts.
Arguments
- DT
input data.table with direction column generated by
direction_stepand group column generated withgroup_pts- direction
character string of direction column name, default "direction", expects that the unit of the direction column is radians.
- group
character string of group column name, default "group"
Value
direction_group returns the input DT appended with a
group_direction column representing the mean direction of
all individuals in each spatiotemporal group.
The mean direction is calculated using CircStats::circ.mean()
which expects units of radians.
A message is returned when the group_direction columns already
exists in the input DT, because it 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().
The direction and group arguments expect the names of columns
in DT which correspond to the direction and group columns. The
direction column is expected in units of radians and the mean calculated with
CircStats::circ.mean().
See also
direction_step, group_pts,
CircStats::circ.mean()
Other Direction functions:
direction_polarization(),
direction_step(),
direction_to_centroid(),
direction_to_leader(),
edge_alignment(),
edge_delay(),
edge_direction(),
edge_dist(),
edge_zones(),
leader_direction_group(),
leader_edge_delay()
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 = 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
#> ---
#> 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: 9899
#> 14294: 9900
#> 14295: 9901
#> 14296: 9902
#> 14297: 9903
# Calculate direction at each step
direction_step(
DT = DT,
id = 'ID',
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 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]
#> ---
#> 14293: 9899 2.10901157 [rad]
#> 14294: 9900 0.13663566 [rad]
#> 14295: 9901 -1.78096501 [rad]
#> 14296: 9902 2.84652173 [rad]
#> 14297: 9903 NA [rad]
# 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
#> ---
#> 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 direction group_direction
#> <int> <units> <units>
#> 1: 1 -2.65649015 [rad] -2.65649015 [rad]
#> 2: 2 2.17592086 [rad] 2.17592086 [rad]
#> 3: 3 -1.98432277 [rad] -1.98432277 [rad]
#> 4: 4 1.90650150 [rad] 1.90650150 [rad]
#> 5: 5 -0.04059949 [rad] -0.04059949 [rad]
#> ---
#> 14293: 9899 2.10901157 [rad] 2.10901157 [rad]
#> 14294: 9900 0.13663566 [rad] 0.13663566 [rad]
#> 14295: 9901 -1.78096501 [rad] -1.78096501 [rad]
#> 14296: 9902 2.84652173 [rad] 2.84652173 [rad]
#> 14297: 9903 NA [rad] NA [rad]