fusion_id identifies fusion events in distance based edge lists.
The function accepts a distance based edge list generated by
edge_dist, a threshold argument and arguments controlling how fusion
events are defined.
Usage
fusion_id(
edges = NULL,
threshold = 50,
n_min_length = 0,
n_max_missing = 0,
allow_split = FALSE
)Arguments
- edges
distance based edge list generated by
edge_distfunction, with dyad ID generated bydyad_ID- threshold
spatial distance threshold in the units of the projection
- n_min_length
minimum length of fusion events
- n_max_missing
maximum number of missing observations within a fusion event
- allow_split
boolean defining if a single observation can be greater than the threshold distance without initiating fission event
Value
fusion_id returns the input edges appended with a
fusionID column.
This column represents the fusion event id. As with spatsoc's
grouping functions, the actual value of fusionID is arbitrary and
represents the identity of a given fusion event. If the data was reordered,
the fusionID may change, but the membership of each fusion event
would not.
A message is returned when a column named fusionID already exists in
the input edges, because it will be overwritten.
Details
The edges must be a data.table returned by the edge_dist
function. In addition, fusion_id requires a dyad ID set on the edge
list generated by dyad_id. If your data is a data.frame, you
can convert it by reference using
data.table::setDT.
The threshold must be provided in the units of the coordinates. The
threshold must be larger than 0. The coordinates must be planar
coordinates (e.g.: UTM). In the case of UTM, a threshold = 50 would
indicate a 50 m distance threshold.
The n_min_length argument defines the minimum number of successive
fixes that are required to establish a fusion event. The n_max_missing
argument defines the the maximum number of allowable missing observations for
the dyad within a fusion event. The allow_split argument defines if a
single observation can be greater than the threshold distance without
initiating fission event.
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
# Edge list generation
edges <- edge_dist(
DT,
threshold = 100,
id = 'ID',
coords = c('X', 'Y'),
timegroup = 'timegroup',
returnDist = TRUE,
fillNA = TRUE
)
dyad_id(edges, 'ID1', 'ID2')
#> Key: <timegroup, ID1>
#> timegroup ID1 ID2 distance dyadID
#> <int> <char> <char> <num> <char>
#> 1: 1 A <NA> NA <NA>
#> 2: 1 B G 5.782904 B-G
#> 3: 1 C <NA> NA <NA>
#> 4: 1 D <NA> NA <NA>
#> 5: 1 E H 65.061671 E-H
#> ---
#> 22985: 1440 G <NA> NA <NA>
#> 22986: 1440 H <NA> NA <NA>
#> 22987: 1440 I C 2.831071 C-I
#> 22988: 1440 I F 7.512922 F-I
#> 22989: 1440 J <NA> NA <NA>
fusion_id(
edges = edges,
threshold = 100,
n_min_length = 1,
n_max_missing = 0,
allow_split = FALSE
)
#> Key: <timegroup, ID1>
#> timegroup ID1 ID2 distance dyadID fusionID
#> <int> <char> <char> <num> <char> <int>
#> 1: 1 A <NA> NA <NA> NA
#> 2: 1 B G 5.782904 B-G 1
#> 3: 1 C <NA> NA <NA> NA
#> 4: 1 D <NA> NA <NA> NA
#> 5: 1 E H 65.061671 E-H 2
#> ---
#> 22985: 1440 G <NA> NA <NA> NA
#> 22986: 1440 H <NA> NA <NA> NA
#> 22987: 1440 I C 2.831071 C-I 2846
#> 22988: 1440 I F 7.512922 F-I 2847
#> 22989: 1440 J <NA> NA <NA> NA