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. 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,
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.- splitBy
(optional) character string or vector of grouping column name(s) upon which the grouping will be calculated
- 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.
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, coords, and optional splitBy arguments expect
the names of a column in DT which correspond to the individual
identifier, X and Y coordinates, and additional grouping columns.
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 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 also
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_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
# 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]
# 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 [°]