direction_to_centroid calculates the direction of each relocation to the
centroid of the spatiotemporal group identified by group_pts(). The
function expects a data.table with relocation data appended with a group
column from group_pts() and centroid columns from centroid_group().
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().
Arguments
- DT
input data.table
- 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- geometry
simple feature geometry list column name, generated by
get_geometry(). Default 'geometry', see details under Interface
Value
direction_to_centroid returns the input DT appended with a
direction_centroid column indicating the direction to the group centroid
in radians. A value of NaN is returned when the coordinates of the focal
individual equal the coordinates of the centroid.
A message is returned when direction_centroid column already exist in the
input DT, because they will be overwritten.
Missing values in coordinates / geometry are ignored and NA is returned.
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().
This function expects a group column present generated with the
group_pts() function and centroid coordinates generated with the
centroid_group() function. The group argument expects the name of the
column in DT which correspond to the group column.
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
centroid_group, group_pts, lwgeom::st_geod_azimuth()
Other Direction functions:
direction_group(),
direction_polarization(),
direction_step(),
direction_to_leader(),
edge_alignment(),
edge_delay(),
edge_direction(),
edge_zones(),
leader_direction_group(),
leader_edge_delay()
Other Centroid functions:
centroid_dyad(),
centroid_fusion(),
centroid_group(),
distance_to_centroid()
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 696191.5 5508362 2017-01-17 00:00:47 1 0 1
#> 2: A 696205.2 5508363 2017-01-17 02:00:48 1 0 2
#> 3: A 696745.8 5508225 2017-01-17 04:00:48 1 0 3
#> 4: A 696952.0 5508373 2017-01-17 06:00:54 1 0 4
#> 5: A 696079.0 5508218 2017-01-17 08:00:54 1 0 5
#> ---
#> 116: J 696996.5 5508024 2017-01-17 14:00:42 1 0 8
#> 117: J 697046.4 5507922 2017-01-17 16:00:47 1 0 9
#> 118: J 697037.5 5507924 2017-01-17 18:00:54 1 0 10
#> 119: J 697303.0 5508347 2017-01-17 20:00:24 1 0 11
#> 120: J 696616.7 5508736 2017-01-17 22:00:42 1 0 12
# Spatial grouping with timegroup
group_pts(DT, threshold = 5, id = 'ID',
coords = c('X', 'Y'), timegroup = 'timegroup')
#> ID X Y datetime population minutes timegroup
#> <char> <num> <num> <POSc> <int> <int> <int>
#> 1: A 696191.5 5508362 2017-01-17 00:00:47 1 0 1
#> 2: A 696205.2 5508363 2017-01-17 02:00:48 1 0 2
#> 3: A 696745.8 5508225 2017-01-17 04:00:48 1 0 3
#> 4: A 696952.0 5508373 2017-01-17 06:00:54 1 0 4
#> 5: A 696079.0 5508218 2017-01-17 08:00:54 1 0 5
#> ---
#> 116: J 696996.5 5508024 2017-01-17 14:00:42 1 0 8
#> 117: J 697046.4 5507922 2017-01-17 16:00:47 1 0 9
#> 118: J 697037.5 5507924 2017-01-17 18:00:54 1 0 10
#> 119: J 697303.0 5508347 2017-01-17 20:00:24 1 0 11
#> 120: J 696616.7 5508736 2017-01-17 22:00:42 1 0 12
#> group
#> <int>
#> 1: 1
#> 2: 2
#> 3: 3
#> 4: 4
#> 5: 5
#> ---
#> 116: 109
#> 117: 110
#> 118: 111
#> 119: 112
#> 120: 59
# Calculate group centroid
centroid_group(DT, coords = c('X', 'Y'), group = 'group')
#> ID X Y datetime population minutes timegroup
#> <char> <num> <num> <POSc> <int> <int> <int>
#> 1: A 696191.5 5508362 2017-01-17 00:00:47 1 0 1
#> 2: A 696205.2 5508363 2017-01-17 02:00:48 1 0 2
#> 3: A 696745.8 5508225 2017-01-17 04:00:48 1 0 3
#> 4: A 696952.0 5508373 2017-01-17 06:00:54 1 0 4
#> 5: A 696079.0 5508218 2017-01-17 08:00:54 1 0 5
#> ---
#> 116: J 696996.5 5508024 2017-01-17 14:00:42 1 0 8
#> 117: J 697046.4 5507922 2017-01-17 16:00:47 1 0 9
#> 118: J 697037.5 5507924 2017-01-17 18:00:54 1 0 10
#> 119: J 697303.0 5508347 2017-01-17 20:00:24 1 0 11
#> 120: J 696616.7 5508736 2017-01-17 22:00:42 1 0 12
#> group centroid_X centroid_Y
#> <int> <num> <num>
#> 1: 1 696191.5 5508362
#> 2: 2 696205.2 5508363
#> 3: 3 696745.8 5508225
#> 4: 4 696952.0 5508373
#> 5: 5 696074.7 5508214
#> ---
#> 116: 109 696996.5 5508024
#> 117: 110 697046.4 5507922
#> 118: 111 697037.5 5507924
#> 119: 112 697303.0 5508347
#> 120: 59 696617.8 5508734
# Calculate direction to group centroid
direction_to_centroid(DT, coords = c('X', 'Y'), crs = 32736)
#> ID X Y datetime population minutes timegroup
#> <char> <num> <num> <POSc> <int> <int> <int>
#> 1: A 696191.5 5508362 2017-01-17 00:00:47 1 0 1
#> 2: A 696205.2 5508363 2017-01-17 02:00:48 1 0 2
#> 3: A 696745.8 5508225 2017-01-17 04:00:48 1 0 3
#> 4: A 696952.0 5508373 2017-01-17 06:00:54 1 0 4
#> 5: A 696079.0 5508218 2017-01-17 08:00:54 1 0 5
#> ---
#> 116: J 696996.5 5508024 2017-01-17 14:00:42 1 0 8
#> 117: J 697046.4 5507922 2017-01-17 16:00:47 1 0 9
#> 118: J 697037.5 5507924 2017-01-17 18:00:54 1 0 10
#> 119: J 697303.0 5508347 2017-01-17 20:00:24 1 0 11
#> 120: J 696616.7 5508736 2017-01-17 22:00:42 1 0 12
#> group centroid_X centroid_Y direction_centroid
#> <int> <num> <num> <units>
#> 1: 1 696191.5 5508362 NaN [rad]
#> 2: 2 696205.2 5508363 NaN [rad]
#> 3: 3 696745.8 5508225 NaN [rad]
#> 4: 4 696952.0 5508373 NaN [rad]
#> 5: 5 696074.7 5508214 -2.374202 [rad]
#> ---
#> 116: 109 696996.5 5508024 NaN [rad]
#> 117: 110 697046.4 5507922 NaN [rad]
#> 118: 111 697037.5 5507924 NaN [rad]
#> 119: 112 697303.0 5508347 NaN [rad]
#> 120: 59 696617.8 5508734 2.581654 [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 696191.5 5508362 2017-01-17 00:00:47 1 0 1
#> 2: A 696205.2 5508363 2017-01-17 02:00:48 1 0 2
#> 3: A 696745.8 5508225 2017-01-17 04:00:48 1 0 3
#> 4: A 696952.0 5508373 2017-01-17 06:00:54 1 0 4
#> 5: A 696079.0 5508218 2017-01-17 08:00:54 1 0 5
#> ---
#> 116: J 696996.5 5508024 2017-01-17 14:00:42 1 0 8
#> 117: J 697046.4 5507922 2017-01-17 16:00:47 1 0 9
#> 118: J 697037.5 5507924 2017-01-17 18:00:54 1 0 10
#> 119: J 697303.0 5508347 2017-01-17 20:00:24 1 0 11
#> 120: J 696616.7 5508736 2017-01-17 22:00:42 1 0 12
#> group centroid_X centroid_Y direction_centroid geometry
#> <int> <num> <num> <units> <sfc_POINT>
#> 1: 1 696191.5 5508362 NaN [rad] POINT (696191.5 5508362)
#> 2: 2 696205.2 5508363 NaN [rad] POINT (696205.2 5508363)
#> 3: 3 696745.8 5508225 NaN [rad] POINT (696745.8 5508225)
#> 4: 4 696952.0 5508373 NaN [rad] POINT (696952 5508373)
#> 5: 5 696074.7 5508214 -2.374202 [rad] POINT (696079 5508218)
#> ---
#> 116: 109 696996.5 5508024 NaN [rad] POINT (696996.5 5508024)
#> 117: 110 697046.4 5507922 NaN [rad] POINT (697046.4 5507922)
#> 118: 111 697037.5 5507924 NaN [rad] POINT (697037.5 5507924)
#> 119: 112 697303.0 5508347 NaN [rad] POINT (697303 5508347)
#> 120: 59 696617.8 5508734 2.581654 [rad] POINT (696616.7 5508736)
group_pts(DT, threshold = 5, id = 'ID', timegroup = 'timegroup')
#> group column will be overwritten by this function
#> ID X Y datetime population minutes timegroup
#> <char> <num> <num> <POSc> <int> <int> <int>
#> 1: A 696191.5 5508362 2017-01-17 00:00:47 1 0 1
#> 2: A 696205.2 5508363 2017-01-17 02:00:48 1 0 2
#> 3: A 696745.8 5508225 2017-01-17 04:00:48 1 0 3
#> 4: A 696952.0 5508373 2017-01-17 06:00:54 1 0 4
#> 5: A 696079.0 5508218 2017-01-17 08:00:54 1 0 5
#> ---
#> 116: J 696996.5 5508024 2017-01-17 14:00:42 1 0 8
#> 117: J 697046.4 5507922 2017-01-17 16:00:47 1 0 9
#> 118: J 697037.5 5507924 2017-01-17 18:00:54 1 0 10
#> 119: J 697303.0 5508347 2017-01-17 20:00:24 1 0 11
#> 120: J 696616.7 5508736 2017-01-17 22:00:42 1 0 12
#> centroid_X centroid_Y direction_centroid geometry group
#> <num> <num> <units> <sfc_POINT> <int>
#> 1: 696191.5 5508362 NaN [rad] POINT (696191.5 5508362) 1
#> 2: 696205.2 5508363 NaN [rad] POINT (696205.2 5508363) 2
#> 3: 696745.8 5508225 NaN [rad] POINT (696745.8 5508225) 3
#> 4: 696952.0 5508373 NaN [rad] POINT (696952 5508373) 4
#> 5: 696074.7 5508214 -2.374202 [rad] POINT (696079 5508218) 5
#> ---
#> 116: 696996.5 5508024 NaN [rad] POINT (696996.5 5508024) 109
#> 117: 697046.4 5507922 NaN [rad] POINT (697046.4 5507922) 110
#> 118: 697037.5 5507924 NaN [rad] POINT (697037.5 5507924) 111
#> 119: 697303.0 5508347 NaN [rad] POINT (697303 5508347) 112
#> 120: 696617.8 5508734 2.581654 [rad] POINT (696616.7 5508736) 59
centroid_group(DT)
#> ID X Y datetime population minutes timegroup
#> <char> <num> <num> <POSc> <int> <int> <int>
#> 1: A 696191.5 5508362 2017-01-17 00:00:47 1 0 1
#> 2: A 696205.2 5508363 2017-01-17 02:00:48 1 0 2
#> 3: A 696745.8 5508225 2017-01-17 04:00:48 1 0 3
#> 4: A 696952.0 5508373 2017-01-17 06:00:54 1 0 4
#> 5: A 696079.0 5508218 2017-01-17 08:00:54 1 0 5
#> ---
#> 116: J 696996.5 5508024 2017-01-17 14:00:42 1 0 8
#> 117: J 697046.4 5507922 2017-01-17 16:00:47 1 0 9
#> 118: J 697037.5 5507924 2017-01-17 18:00:54 1 0 10
#> 119: J 697303.0 5508347 2017-01-17 20:00:24 1 0 11
#> 120: J 696616.7 5508736 2017-01-17 22:00:42 1 0 12
#> centroid_X centroid_Y direction_centroid geometry group
#> <num> <num> <units> <sfc_POINT> <int>
#> 1: 696191.5 5508362 NaN [rad] POINT (696191.5 5508362) 1
#> 2: 696205.2 5508363 NaN [rad] POINT (696205.2 5508363) 2
#> 3: 696745.8 5508225 NaN [rad] POINT (696745.8 5508225) 3
#> 4: 696952.0 5508373 NaN [rad] POINT (696952 5508373) 4
#> 5: 696074.7 5508214 -2.374202 [rad] POINT (696079 5508218) 5
#> ---
#> 116: 696996.5 5508024 NaN [rad] POINT (696996.5 5508024) 109
#> 117: 697046.4 5507922 NaN [rad] POINT (697046.4 5507922) 110
#> 118: 697037.5 5507924 NaN [rad] POINT (697037.5 5507924) 111
#> 119: 697303.0 5508347 NaN [rad] POINT (697303 5508347) 112
#> 120: 696617.8 5508734 2.581654 [rad] POINT (696616.7 5508736) 59
#> centroid
#> <sfc_POINT>
#> 1: POINT (696191.5 5508362)
#> 2: POINT (696205.2 5508363)
#> 3: POINT (696745.8 5508225)
#> 4: POINT (696952 5508373)
#> 5: POINT (696074.7 5508214)
#> ---
#> 116: POINT (696996.5 5508024)
#> 117: POINT (697046.4 5507922)
#> 118: POINT (697037.5 5507924)
#> 119: POINT (697303 5508347)
#> 120: POINT (696617.8 5508734)
direction_to_centroid(DT)
#> direction_centroid column will be overwritten by this function
#> ID X Y datetime population minutes timegroup
#> <char> <num> <num> <POSc> <int> <int> <int>
#> 1: A 696191.5 5508362 2017-01-17 00:00:47 1 0 1
#> 2: A 696205.2 5508363 2017-01-17 02:00:48 1 0 2
#> 3: A 696745.8 5508225 2017-01-17 04:00:48 1 0 3
#> 4: A 696952.0 5508373 2017-01-17 06:00:54 1 0 4
#> 5: A 696079.0 5508218 2017-01-17 08:00:54 1 0 5
#> ---
#> 116: J 696996.5 5508024 2017-01-17 14:00:42 1 0 8
#> 117: J 697046.4 5507922 2017-01-17 16:00:47 1 0 9
#> 118: J 697037.5 5507924 2017-01-17 18:00:54 1 0 10
#> 119: J 697303.0 5508347 2017-01-17 20:00:24 1 0 11
#> 120: J 696616.7 5508736 2017-01-17 22:00:42 1 0 12
#> centroid_X centroid_Y geometry group
#> <num> <num> <sfc_POINT> <int>
#> 1: 696191.5 5508362 POINT (696191.5 5508362) 1
#> 2: 696205.2 5508363 POINT (696205.2 5508363) 2
#> 3: 696745.8 5508225 POINT (696745.8 5508225) 3
#> 4: 696952.0 5508373 POINT (696952 5508373) 4
#> 5: 696074.7 5508214 POINT (696079 5508218) 5
#> ---
#> 116: 696996.5 5508024 POINT (696996.5 5508024) 109
#> 117: 697046.4 5507922 POINT (697046.4 5507922) 110
#> 118: 697037.5 5507924 POINT (697037.5 5507924) 111
#> 119: 697303.0 5508347 POINT (697303 5508347) 112
#> 120: 696617.8 5508734 POINT (696616.7 5508736) 59
#> centroid direction_centroid
#> <sfc_POINT> <units>
#> 1: POINT (696191.5 5508362) NaN [rad]
#> 2: POINT (696205.2 5508363) NaN [rad]
#> 3: POINT (696745.8 5508225) NaN [rad]
#> 4: POINT (696952 5508373) NaN [rad]
#> 5: POINT (696074.7 5508214) -2.374202 [rad]
#> ---
#> 116: POINT (696996.5 5508024) NaN [rad]
#> 117: POINT (697046.4 5507922) NaN [rad]
#> 118: POINT (697037.5 5507924) NaN [rad]
#> 119: POINT (697303 5508347) NaN [rad]
#> 120: POINT (696617.8 5508734) 2.581654 [rad]