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, or in a geometry column prepared by the helper function
get_geometry().
Usage
edge_direction(
edges = NULL,
DT = NULL,
id = NULL,
coords = NULL,
crs = NULL,
timegroup = "timegroup",
geometry = "geometry",
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. Used only if coords are provided, see details under Interface- timegroup
character string of timegroup column name, default "timegroup"
- geometry
simple feature geometry list column name, generated by
get_geometry(). Default 'geometry', see details under Interface- 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 in
radians. A value of NaN is returned when the coordinates of ID1 equal the
coordinates of ID2.
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()).
Missing values in coordinates / geometry are ignored and NA is returned.
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 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, and timegroup arguments
expect the names of columns which correspond to the ID, and timegroup
columns.
See below under "Interface" for details on providing coordinates and under "Direction function" for details on the underlying direction function used.
Interface
Two interfaces are available for providing coordinates:
Provide
coordsandcrs. Thecoordsargument expects the names of the X and Y coordinate columns. Thecrsargument 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 iscrs = "EPSG:32736"orcrs = 32736. See https://spatialreference.org for a list of EPSG codes.(New!) Provide
geometry. Thegeometryargument allows the user to supply ageometrycolumn that represents the coordinates as a simple feature geometry list column. This interface expects the user to prepare their input DT withget_geometry(). To use this interface, leave thecoordsandcrsargumentsNULL, and the default argument forgeometry('geometry') will be used directly.
Direction function
The underlying distance function used depends on the crs of the coordinates or geometry provided.
If the crs is provided and longlat degrees (as determined by
sf::st_is_longlat()), the distance function islwgeom::st_geod_azimuth().If the crs is provided and not longlat degrees (eg. a projected UTM), the coordinates or geometry are transformed to
sf::st_crs(4326)before the distance is measured usinglwgeom::st_geod_azimuth().If the crs is NULL or NA_crs_, the distance function cannot be used and an error is returned.
See also
dyad_id, edge_dist, edge_nn, group_times,
lwgeom::st_geod_azimuth()
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_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]
# Or, using the new geometry interface
get_geometry(DT, coords = c('X', 'Y'), crs = 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
#> geometry
#> <sfc_POINT>
#> 1: POINT (715851.4 5505340)
#> 2: POINT (715822.8 5505289)
#> 3: POINT (715872.9 5505252)
#> 4: POINT (715820.5 5505231)
#> 5: POINT (715830.6 5505227)
#> ---
#> 14293: POINT (700616.5 5509069)
#> 14294: POINT (700622.6 5509065)
#> 14295: POINT (700657.5 5509277)
#> 14296: POINT (700610.3 5509269)
#> 14297: POINT (700744 5508782)
dyad_directions <- edge_direction(
edges,
DT,
id = 'ID',
timegroup = 'timegroup'
)