edge_delay returns edge lists defined by the directional correlation
delay between individuals. The function expects a distance based edge list
generated by edge_dist or edge_nn, a data.table with
relocation data, individual identifiers and a window argument. The window
argument is used to specify the temporal window within which to measure the
directional correlation delay. Relocation data should be in two columns
representing the X and Y coordinates.
Arguments
- edges
edge list generated generated by
edge_distoredge_nn, with fusionID column generated byfusion_id- DT
input data.table with timegroup column generated with
group_timesmatching the input data.table used to generate the edge list withedge_nnoredge_dist- window
temporal window in unit of timegroup column generated with
group_times, eg.window = 4corresponds to the 4 timegroups before and after the focal observation- 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.
Value
edge_delay returns the input edges appended with a
'direction_delay' column indicating the temporal delay (in units of
timegroups) at which ID1's direction of movement is most similar to ID2's
direction of movement, within the temporal window defined, and a
'direction_diff' column indicating the absolute difference in direction.
For example, if focal individual 'A' moves in a 45 degree direction at time
2 and individual 'B' moves in a most similar direction within the window at
time 5, the directional correlation delay between A and B is 3. Positive
values of directional correlation delay indicate a directed leadership edge
from ID1 to ID2.
Details
The edges and DT must be data.tables. If your data is a
data.frame, you can convert it by reference using
data.table::setDT.
The edges argument expects a distance based edge list generated with
edge_nn or edge_dist. The DT argument expects relocation
data with a timegroup column generated with group_times.
The rows in edges and DT are internally matched in
edge_delay using the columns timegroup (from
group_times) and ID1 and ID2 (in edges, from
dyad_id) with id (in DT). This function expects a
fusionID present, generated with the fusion_id function, and a
dyadID present, generated with the dyad_id function. The
id, and direction arguments expect the names of a column in
DT which correspond to the id, and direction columns.
References
The directional correlation delay is defined in Nagy et al. 2010 (https://doi.org/10.1038/nature08891).
See examples of measuring the directional correlation delay:
See also
Other Edge-list generation:
edge_dist(),
edge_nn()
Other Direction functions:
direction_group(),
direction_polarization(),
direction_step(),
direction_to_centroid(),
direction_to_leader(),
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"))
# Select only individuals A, B, C for this example
DT <- DT[ID %in% c('A', 'B', 'C')]
# 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
#> ---
#> 4265: C 702093.6 5510180 2017-02-28 14:00:44 1
#> 4266: C 702086.0 5510183 2017-02-28 16:00:42 1
#> 4267: C 702961.8 5509447 2017-02-28 18:00:53 1
#> 4268: C 703130.4 5509528 2017-02-28 20:00:54 1
#> 4269: C 702872.3 5508531 2017-02-28 22:00:18 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
#> ---
#> 4265: C 702093.6 5510180 2017-02-28 14:00:44 1 0 1393
#> 4266: C 702086.0 5510183 2017-02-28 16:00:42 1 0 1394
#> 4267: C 702961.8 5509447 2017-02-28 18:00:53 1 0 1440
#> 4268: C 703130.4 5509528 2017-02-28 20:00:54 1 0 1395
#> 4269: C 702872.3 5508531 2017-02-28 22:00:18 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
#> ---
#> 4265: C 702093.6 5510180 2017-02-28 14:00:44 1 0 1393
#> 4266: C 702086.0 5510183 2017-02-28 16:00:42 1 0 1394
#> 4267: C 702961.8 5509447 2017-02-28 18:00:53 1 0 1440
#> 4268: C 703130.4 5509528 2017-02-28 20:00:54 1 0 1395
#> 4269: C 702872.3 5508531 2017-02-28 22:00:18 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]
#> ---
#> 4265: -1.16059019 [rad]
#> 4266: 2.24288689 [rad]
#> 4267: 1.09317866 [rad]
#> 4268: -2.91547765 [rad]
#> 4269: NA [rad]
# Distance based edge list generation
edges <- edge_dist(
DT,
threshold = 100,
id = 'ID',
coords = c('X', 'Y'),
timegroup = 'timegroup',
returnDist = TRUE,
fillNA = FALSE
)
# Generate dyad id
dyad_id(edges, id1 = 'ID1', id2 = 'ID2')
#> timegroup ID1 ID2 distance dyadID
#> <int> <char> <char> <num> <char>
#> 1: 116 C A 61.41036 A-C
#> 2: 116 A C 61.41036 A-C
#> 3: 117 C A 38.18977 A-C
#> 4: 117 A C 38.18977 A-C
#> 5: 119 C A 18.30832 A-C
#> ---
#> 1538: 1395 A C 12.31124 A-C
#> 1539: 1397 C B 24.45925 B-C
#> 1540: 1397 B C 24.45925 B-C
#> 1541: 1398 C B 23.01744 B-C
#> 1542: 1398 B C 23.01744 B-C
# Generate fusion id
fusion_id(edges, threshold = 100)
#> timegroup ID1 ID2 distance dyadID fusionID
#> <int> <char> <char> <num> <char> <int>
#> 1: 116 C A 61.41036 A-C 1
#> 2: 116 A C 61.41036 A-C 1
#> 3: 117 C A 38.18977 A-C 1
#> 4: 117 A C 38.18977 A-C 1
#> 5: 119 C A 18.30832 A-C 2
#> ---
#> 1538: 1395 A C 12.31124 A-C 206
#> 1539: 1397 C B 24.45925 B-C 207
#> 1540: 1397 B C 24.45925 B-C 207
#> 1541: 1398 C B 23.01744 B-C 208
#> 1542: 1398 B C 23.01744 B-C 208
# Directional correlation delay
delay <- edge_delay(
edges = edges,
DT = DT,
window = 3,
id = 'ID'
)
delay[, mean(direction_delay, na.rm = TRUE), by = .(ID1, ID2)][V1 > 0]
#> ID1 ID2 V1
#> <char> <char> <num>
#> 1: A C 0.06070826
#> 2: B C 0.20652174
#> 3: A B 0.08139535