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_step()and 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().
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]
# 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 direction group_direction geometry
#> <int> <units> <units> <sfc_POINT>
#> 1: 1 -2.65649015 [rad] -2.65649015 [rad] POINT (715851.4 5505340)
#> 2: 2 2.17592086 [rad] 2.17592086 [rad] POINT (715822.8 5505289)
#> 3: 3 -1.98432277 [rad] -1.98432277 [rad] POINT (715872.9 5505252)
#> 4: 4 1.90650150 [rad] 1.90650150 [rad] POINT (715820.5 5505231)
#> 5: 5 -0.04059949 [rad] -0.04059949 [rad] POINT (715830.6 5505227)
#> ---
#> 14293: 9899 2.10901157 [rad] 2.10901157 [rad] POINT (700616.5 5509069)
#> 14294: 9900 0.13663566 [rad] 0.13663566 [rad] POINT (700622.6 5509065)
#> 14295: 9901 -1.78096501 [rad] -1.78096501 [rad] POINT (700657.5 5509277)
#> 14296: 9902 2.84652173 [rad] 2.84652173 [rad] POINT (700610.3 5509269)
#> 14297: 9903 NA [rad] NA [rad] 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
#> direction group_direction geometry group
#> <units> <units> <sfc_POINT> <int>
#> 1: -2.65649015 [rad] -2.65649015 [rad] POINT (715851.4 5505340) 1
#> 2: 2.17592086 [rad] 2.17592086 [rad] POINT (715822.8 5505289) 2
#> 3: -1.98432277 [rad] -1.98432277 [rad] POINT (715872.9 5505252) 3
#> 4: 1.90650150 [rad] 1.90650150 [rad] POINT (715820.5 5505231) 4
#> 5: -0.04059949 [rad] -0.04059949 [rad] POINT (715830.6 5505227) 5
#> ---
#> 14293: 2.10901157 [rad] 2.10901157 [rad] POINT (700616.5 5509069) 13882
#> 14294: 0.13663566 [rad] 0.13663566 [rad] POINT (700622.6 5509065) 13883
#> 14295: -1.78096501 [rad] -1.78096501 [rad] POINT (700657.5 5509277) 13884
#> 14296: 2.84652173 [rad] 2.84652173 [rad] POINT (700610.3 5509269) 13885
#> 14297: NA [rad] NA [rad] POINT (700744 5508782) 13886
direction_step(DT, id = 'ID')
#> direction 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
#> group_direction geometry group direction
#> <units> <sfc_POINT> <int> <units>
#> 1: -2.65649015 [rad] POINT (715851.4 5505340) 1 -2.65649015 [rad]
#> 2: 2.17592086 [rad] POINT (715822.8 5505289) 2 2.17592086 [rad]
#> 3: -1.98432277 [rad] POINT (715872.9 5505252) 3 -1.98432277 [rad]
#> 4: 1.90650150 [rad] POINT (715820.5 5505231) 4 1.90650150 [rad]
#> 5: -0.04059949 [rad] POINT (715830.6 5505227) 5 -0.04059949 [rad]
#> ---
#> 14293: 2.10901157 [rad] POINT (700616.5 5509069) 13882 2.10901157 [rad]
#> 14294: 0.13663566 [rad] POINT (700622.6 5509065) 13883 0.13663566 [rad]
#> 14295: -1.78096501 [rad] POINT (700657.5 5509277) 13884 -1.78096501 [rad]
#> 14296: 2.84652173 [rad] POINT (700610.3 5509269) 13885 2.84652173 [rad]
#> 14297: NA [rad] POINT (700744 5508782) 13886 NA [rad]
direction_group(DT)
#> group_direction 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
#> geometry group direction group_direction
#> <sfc_POINT> <int> <units> <units>
#> 1: POINT (715851.4 5505340) 1 -2.65649015 [rad] -2.65649015 [rad]
#> 2: POINT (715822.8 5505289) 2 2.17592086 [rad] 2.17592086 [rad]
#> 3: POINT (715872.9 5505252) 3 -1.98432277 [rad] -1.98432277 [rad]
#> 4: POINT (715820.5 5505231) 4 1.90650150 [rad] 1.90650150 [rad]
#> 5: POINT (715830.6 5505227) 5 -0.04059949 [rad] -0.04059949 [rad]
#> ---
#> 14293: POINT (700616.5 5509069) 13882 2.10901157 [rad] 2.10901157 [rad]
#> 14294: POINT (700622.6 5509065) 13883 0.13663566 [rad] 0.13663566 [rad]
#> 14295: POINT (700657.5 5509277) 13884 -1.78096501 [rad] -1.78096501 [rad]
#> 14296: POINT (700610.3 5509269) 13885 2.84652173 [rad] 2.84652173 [rad]
#> 14297: POINT (700744 5508782) 13886 NA [rad] NA [rad]