edge_alignment returns edge-lists defined by directional alignment
(difference in movement direction) between individuals. The function expects
a data.table with relocation data and individual identifiers, a
direction column (generated by direction_step) and timegroup column
(generated by group_times).
Usage
edge_alignment(
DT = NULL,
id = NULL,
direction = "direction",
timegroup = "timegroup",
group = NULL,
splitBy = NULL,
signed = FALSE
)Arguments
- DT
input data.table
- id
character string of ID column name
- direction
character string of direction column name, default "direction", expects that the unit of the direction column is radians.
- timegroup
character string of timegroup column name, default "timegroup"
- group
(optional) character string of group column name, used to restrict the calculation of directional alignment to within spatiotemporal groups
- splitBy
(optional) vector of column names indicating subgroups within which the direction alignment will be calculated
- signed
boolean if signed difference should be returned, default FALSE
Value
edge_alignment returns a data.table with columns ID1, ID2,
timegroup, and a 'direction_diff' column indicating the difference in direction
between ID1 and ID2, along with any columns provided in splitBy.
Note: unlike many other functions (eg. group_pts) in spatsoc,
edge_alignment needs to be reassigned. See details in
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.
The id, direction, timegroup, and optional group
and splitBy arguments expect the names of a column in DT which
correspond to the individual identifier, direction (generated by
direction_step), timegroup (generated by group_times), group
(generated by group_pts) and additional grouping columns.
There are two approaches to spatially restricting the calculation of
directional alignment. The group argument can be used to pass the
output group column from group_pts to calculate direction alignment
within spatiotemporal groups. Alternatively, the output of
edge_alignment can be merged with the output of edge_dist to
compare the difference in direction to the distance between individuals.
The splitBy argument offers further control over the calculation of
directional alignment. If within your DT, you have multiple
populations, subgroups or other distinct parts, you can provide the name of
the column which identifies them to splitBy. edge_alignment
will only consider rows within each splitBy subgroup.
See also
Other Edge-list generation:
edge_delay(),
edge_dist(),
edge_nn()
Other Direction functions:
direction_group(),
direction_polarization(),
direction_step(),
direction_to_centroid(),
direction_to_leader(),
edge_delay(),
edge_dist(),
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
# Calculate direction
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
#> ---
#> 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
#> <units>
#> 1: -2.65649015 [rad]
#> 2: 2.17592086 [rad]
#> 3: -1.98432277 [rad]
#> 4: 1.90650150 [rad]
#> 5: -0.04059949 [rad]
#> ---
#> 14293: 2.10901157 [rad]
#> 14294: 0.13663566 [rad]
#> 14295: -1.78096501 [rad]
#> 14296: 2.84652173 [rad]
#> 14297: NA [rad]
# Calculate directional alignment edge-list
align <- edge_alignment(
DT,
id = 'ID',
timegroup = 'timegroup',
signed = FALSE
)
# Or, calculate directional alignment within spatiotemporal groups
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
#> direction group
#> <units> <int>
#> 1: -2.65649015 [rad] 1
#> 2: 2.17592086 [rad] 2
#> 3: -1.98432277 [rad] 3
#> 4: 1.90650150 [rad] 4
#> 5: -0.04059949 [rad] 5
#> ---
#> 14293: 2.10901157 [rad] 13882
#> 14294: 0.13663566 [rad] 13883
#> 14295: -1.78096501 [rad] 13884
#> 14296: 2.84652173 [rad] 13885
#> 14297: NA [rad] 13886
align_group <- edge_alignment(
DT,
id = 'ID',
timegroup = 'timegroup',
group = 'group',
signed = FALSE
)