edge_direction returns edge lists defined by the direction between
individuals. The function expects a distance based edge-list generated by
edge_nn or edge_dist and a data.table with relocation
data appended with a timegroup column from group_times.
It is required to use the argument fillNA = FALSE for
edge_dist to ensure there are no NAs in the coordinate columns.
Relocation data should be in two columns representing the X and Y coordinates.
Usage
edge_direction(
edges = NULL,
DT = NULL,
id = NULL,
coords = NULL,
crs = NULL,
timegroup = "timegroup",
projection = NULL
)Arguments
- edges
edge-list generated generated by
edge_distoredge_nn, with dyad ID column generated bydyad_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- id
character string of ID column name
- coords
character vector of X coordinate and Y coordinate column names. Note: the order is assumed X followed by Y column names.
- crs
numeric or character defining the coordinate reference system to be passed to sf::st_crs. For example, either
crs = "EPSG:32736"orcrs = 32736.- timegroup
character string of timegroup column name, default "timegroup"
- projection
(deprecated) use crs argument instead
Value
edge_direction returns the input edges appended with
a "direction_dyad" column representing the direction between ID1 and ID2.
The direction between individuals is calculated with
lwgeom::st_geod_azimuth().
If the "direction" column is found in input DT, it will be retained for
ID1 in the output for use in downstream functions (eg. edge_zones).
Note: due to the merge required within this function, the output needs to be
reassigned unlike some other spatsoc functions like dyad_id
and group_pts. See details in
FAQ.
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() or by reassigning using
data.table::data.table().
The crs argument expects a character string or numeric defining
the coordinate reference system to be passed to sf::st_crs. For example,
for UTM zone 36S (EPSG 32736), the crs argument is
crs = "EPSG:32736" or crs = 32736. See
https://spatialreference.org for a list of EPSG codes.
The edges and DT are internally merged in this function using
the columns id, dyadID and timegroup. This function
expects a dyadID present, generated with the dyad_id function.
The id, coords and timegroup arguments expect the names
of columns which correspond to the ID, X and Y coordinates and timegroup
columns.
See also
dyad_id edge_dist edge_nn group_times
Other Edge-list generation:
edge_alignment(),
edge_delay(),
edge_dist(),
edge_nn()
Other Direction functions:
direction_group(),
direction_polarization(),
direction_step(),
direction_to_centroid(),
direction_to_leader(),
edge_alignment(),
edge_delay(),
edge_dist(),
edge_zones(),
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
# 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: 1 G B 5.782904 B-G
#> 2: 1 H E 65.061671 E-H
#> 3: 1 B G 5.782904 B-G
#> 4: 1 E H 65.061671 E-H
#> 5: 2 H E 79.659918 E-H
#> ---
#> 17174: 1440 I C 2.831071 C-I
#> 17175: 1440 C F 9.372972 C-F
#> 17176: 1440 I F 7.512922 F-I
#> 17177: 1440 C I 2.831071 C-I
#> 17178: 1440 F I 7.512922 F-I
# Direction based edge-lists
dyad_directions <- edge_direction(
edges,
DT,
id = 'ID',
coords = c('X', 'Y'),
crs = 32736,
timegroup = 'timegroup'
)
print(dyad_directions)
#> timegroup ID1 ID2 dyadID distance direction_dyad
#> <int> <char> <char> <char> <num> <units>
#> 1: 1 G B B-G 5.782904 0.932704118 [rad]
#> 2: 1 H E E-H 65.061671 -2.236466737 [rad]
#> 3: 1 B G B-G 5.782904 -2.208889158 [rad]
#> 4: 1 E H E-H 65.061671 0.905132780 [rad]
#> 5: 2 H E E-H 79.659918 3.015321726 [rad]
#> ---
#> 17174: 1440 I C C-I 2.831071 2.145953261 [rad]
#> 17175: 1440 C F C-F 9.372972 -0.262152781 [rad]
#> 17176: 1440 I F F-I 7.512922 -0.007124986 [rad]
#> 17177: 1440 C I C-I 2.831071 -0.995639711 [rad]
#> 17178: 1440 F I F-I 7.512922 3.134467675 [rad]