direction_step calculates the direction of movement steps in radians. The
function expects a data.table with relocation data and individual
identifiers. 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(). Note the order of rows is not modified by this function and
therefore users must be cautious to set it explicitly. See example for one
approach to setting order of rows using a datetime field.
Usage
direction_step(
DT = NULL,
id = NULL,
coords = NULL,
crs = NULL,
splitBy = NULL,
geometry = "geometry",
projection = NULL
)Arguments
- DT
input data.table
- 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- splitBy
(optional) character string or vector of grouping column name(s) upon which the output will be calculated
- geometry
simple feature geometry list column name, generated by
get_geometry(). Default 'geometry', see details under Interface- projection
(deprecated) use crs argument instead
Value
direction_step returns the input DT appended with a direction
column with units set to radians using the units package.
This column represents the azimuth between the sequence of points for each
individual computed using lwgeom::st_geod_azimuth(). Note, the order of
points is not modified by this function and therefore it is crucial the
user sets the order of rows to their specific question before using
direction_step. In addition, the direction column will include an NA
value for the last point in each sequence of points since there is no
future point to calculate a direction to.
A message is returned when a direction column are already exists in the
input DT, because it will be overwritten.
An error is returned if there are any missing values in coordinates /
geometry as the underlying direction function (lwgeom::st_geod_azimuth())
does not accept missing values.
See details for appending outputs using modify-by-reference in the FAQ.
Details
The DT must be a data.table. 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 id, and optional splitBy arguments expect the names of a column in
DT which correspond to the individual identifier and additional grouping
columns.
The splitBy argument offers further control over grouping. If within your
DT, you have distinct sampling periods for each individual, you can provide
the column name(s) which identify them to splitBy. The direction
calculation by direction_step() will only consider rows within each id
and splitBy subgroup.
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
lwgeom::st_geod_azimuth(), amt::direction_abs(),
geosphere::bearing()
Other Direction functions:
direction_group(),
direction_polarization(),
direction_to_centroid(),
direction_to_leader(),
edge_alignment(),
edge_delay(),
edge_direction(),
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
# Set order using data.table::setorder
setorder(DT, datetime)
# Calculate direction
direction_step(
DT = DT,
id = 'ID',
coords = c('X', 'Y'),
crs = 32736
)
#> ID X Y datetime population direction
#> <char> <num> <num> <POSc> <int> <units>
#> 1: I 711042.0 5506384 2016-11-01 00:00:24 1 1.2185092 [rad]
#> 2: C 710205.4 5505888 2016-11-01 00:00:44 1 0.1384333 [rad]
#> 3: D 700875.0 5490954 2016-11-01 00:00:47 1 3.0618533 [rad]
#> 4: E 701671.9 5504286 2016-11-01 00:00:48 1 -2.9977039 [rad]
#> 5: F 705583.0 5513813 2016-11-01 00:00:48 1 1.3261714 [rad]
#> ---
#> 14293: E 698956.7 5508224 2017-02-28 22:00:44 1 NA [rad]
#> 14294: G 698307.6 5509182 2017-02-28 22:00:46 1 NA [rad]
#> 14295: B 699759.4 5507878 2017-02-28 22:00:48 1 NA [rad]
#> 14296: F 702841.7 5508583 2017-02-28 22:00:53 1 NA [rad]
#> 14297: A 702780.3 5508592 2017-02-28 22:02:18 1 NA [rad]
# Or: sfc interface
get_geometry(DT, coords = c('X', 'Y'), crs = 32736)
#> ID X Y datetime population direction
#> <char> <num> <num> <POSc> <int> <units>
#> 1: I 711042.0 5506384 2016-11-01 00:00:24 1 1.2185092 [rad]
#> 2: C 710205.4 5505888 2016-11-01 00:00:44 1 0.1384333 [rad]
#> 3: D 700875.0 5490954 2016-11-01 00:00:47 1 3.0618533 [rad]
#> 4: E 701671.9 5504286 2016-11-01 00:00:48 1 -2.9977039 [rad]
#> 5: F 705583.0 5513813 2016-11-01 00:00:48 1 1.3261714 [rad]
#> ---
#> 14293: E 698956.7 5508224 2017-02-28 22:00:44 1 NA [rad]
#> 14294: G 698307.6 5509182 2017-02-28 22:00:46 1 NA [rad]
#> 14295: B 699759.4 5507878 2017-02-28 22:00:48 1 NA [rad]
#> 14296: F 702841.7 5508583 2017-02-28 22:00:53 1 NA [rad]
#> 14297: A 702780.3 5508592 2017-02-28 22:02:18 1 NA [rad]
#> geometry
#> <sfc_POINT>
#> 1: POINT (711042 5506384)
#> 2: POINT (710205.4 5505888)
#> 3: POINT (700875 5490954)
#> 4: POINT (701671.9 5504286)
#> 5: POINT (705583 5513813)
#> ---
#> 14293: POINT (698956.7 5508224)
#> 14294: POINT (698307.6 5509182)
#> 14295: POINT (699759.4 5507878)
#> 14296: POINT (702841.7 5508583)
#> 14297: POINT (702780.3 5508592)
direction_step(DT, id = 'ID')
#> direction column will be overwritten by this function
#> ID X Y datetime population
#> <char> <num> <num> <POSc> <int>
#> 1: I 711042.0 5506384 2016-11-01 00:00:24 1
#> 2: C 710205.4 5505888 2016-11-01 00:00:44 1
#> 3: D 700875.0 5490954 2016-11-01 00:00:47 1
#> 4: E 701671.9 5504286 2016-11-01 00:00:48 1
#> 5: F 705583.0 5513813 2016-11-01 00:00:48 1
#> ---
#> 14293: E 698956.7 5508224 2017-02-28 22:00:44 1
#> 14294: G 698307.6 5509182 2017-02-28 22:00:46 1
#> 14295: B 699759.4 5507878 2017-02-28 22:00:48 1
#> 14296: F 702841.7 5508583 2017-02-28 22:00:53 1
#> 14297: A 702780.3 5508592 2017-02-28 22:02:18 1
#> geometry direction
#> <sfc_POINT> <units>
#> 1: POINT (711042 5506384) 1.2185092 [rad]
#> 2: POINT (710205.4 5505888) 0.1384333 [rad]
#> 3: POINT (700875 5490954) 3.0618533 [rad]
#> 4: POINT (701671.9 5504286) -2.9977039 [rad]
#> 5: POINT (705583 5513813) 1.3261714 [rad]
#> ---
#> 14293: POINT (698956.7 5508224) NA [rad]
#> 14294: POINT (698307.6 5509182) NA [rad]
#> 14295: POINT (699759.4 5507878) NA [rad]
#> 14296: POINT (702841.7 5508583) NA [rad]
#> 14297: POINT (702780.3 5508592) NA [rad]
# Example result for East, North, West, South steps
example <- data.table(
X = c(0, 5, 5, 0, 0),
Y = c(0, 0, 5, 5, 0),
step = c('E', 'N', 'W', 'S', NA),
ID = 'A'
)
direction_step(example, 'ID', c('X', 'Y'), crs = 4326)
#> X Y step ID direction
#> <num> <num> <char> <char> <units>
#> 1: 0 0 E A 1.570796 [rad]
#> 2: 5 0 N A 0.000000 [rad]
#> 3: 5 5 W A -1.566991 [rad]
#> 4: 0 5 S A 3.141593 [rad]
#> 5: 0 0 <NA> A NA [rad]
example[, .(step, direction, units::set_units(direction, 'degree'))]
#> step direction V3
#> <char> <units> <units>
#> 1: E 1.570796 [rad] 90.00000 [°]
#> 2: N 0.000000 [rad] 0.00000 [°]
#> 3: W -1.566991 [rad] -89.78197 [°]
#> 4: S 3.141593 [rad] 180.00000 [°]
#> 5: <NA> NA [rad] NA [°]