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"
Value
edge_delay returns the input edges appended with
a 'dir_corr_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. 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_leader()
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(dir_corr_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