group_lines groups rows into spatial groups by creating trajectories and grouping based on spatial overlap. The function accepts a data.table with relocation data, individual identifiers and a threshold. The relocation data is transformed into SpatialLines and overlapping SpatialLines are grouped. The threshold argument is used to specify the criteria for distance between lines. Relocation data should be in two columns representing the X and Y coordinates.

group_lines(
  DT = NULL,
  threshold = NULL,
  projection = NULL,
  id = NULL,
  coords = NULL,
  timegroup = NULL,
  sortBy = NULL,
  splitBy = NULL,
  spLines = NULL
)

Arguments

DT

input data.table

threshold

The width of the buffer around the lines in the units of the projection. Supply 0 to compare intersection without buffering.

projection

PROJ.4 character string

id

Character string of ID column name

coords

Character vector of X coordinate and Y coordinate column names

timegroup

timegroup field in the DT upon which the grouping will be calculated

sortBy

Character string of date time column(s) to sort rows by. Must be a POSIXct.

splitBy

(optional) character string or vector of grouping column name(s) upon which the grouping will be calculated

spLines

Alternatively to providing a DT, provide a SpatialLines object created with the sp package. If a spLines object is provided, groups cannot be calculated by a timegroup or splitBy.

Value

group_lines returns the input DT appended with a group column.

This column represents the spatial (and if timegroup was provided - spatiotemporal) group calculated by overlapping lines. As with the other grouping functions, the actual value of group is arbitrary and represents the identity of a given group where 1 or more individuals are assigned to a group. If the data was reordered, the group may change, but the contents of each group would not.

A message is returned when a column named group already exists in the input DT, because it will be overwritten.

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.

The id, coords, sortBy (and optional timegroup and splitBy) arguments expect the names of respective columns in DT which correspond to the individual identifier, X and Y coordinates, sorting, timegroup (generated by group_times) and additional grouping columns.

The sortBy is used to order the input data.table when creating SpatialLines. It must a POSIXct to ensure the rows are sorted by date time. The projection expects a PROJ.4 character string (such as those available on https://spatialreference.org/). group_lines expects planar coordinates (not unprojected latitude, longitude).

The threshold must be provided in the units of the coordinates. The threshold can be equal to 0 if strict overlap is required, else it needs to be greater than 0. The coordinates must be planar coordinates (e.g.: UTM). In the case of UTM, a threshold = 50 would indicate a 50m distance threshold.

The timegroup argument is optional, but recommended to pair with group_times. The intended framework is to group rows temporally with group_times then spatially with group_lines (or group_pts, group_polys). With group_lines, pick a relevant group_times threshold such as '1 day' or '7 days' which is informed by your study species and system.

The splitBy argument offers further control over grouping. If within your DT, you have multiple populations, subgroups or other distinct parts, you can provide the name of the column which identifies them to splitBy. The grouping performed by group_lines will only consider rows within each splitBy subgroup.

See also

build_lines group_times

Other Spatial grouping: group_polys(), group_pts()

Examples

# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc")) # Subset only individuals A, B, and C DT <- DT[ID %in% c('A', 'B', 'C')] # Cast the character column to POSIXct DT[, datetime := as.POSIXct(datetime, tz = 'UTC')]
#> ID X Y datetime population #> 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 #> --- #> 4265: C 702093.6 5510180 2017-02-28 14:00:44 1 #> 4266: C 702086.0 5510183 2017-02-28 16:00:42 1 #> 4267: C 702961.8 5509447 2017-02-28 18:00:53 1 #> 4268: C 703130.4 5509528 2017-02-28 20:00:54 1 #> 4269: C 702872.3 5508531 2017-02-28 22:00:18 1
# Proj4 string for example data utm <- '+proj=utm +zone=36 +south +ellps=WGS84 +datum=WGS84 +units=m +no_defs' group_lines(DT, threshold = 50, projection = utm, sortBy = 'datetime', id = 'ID', coords = c('X', 'Y'))
#> ID X Y datetime population group #> 1: A 715851.4 5505340 2016-11-01 00:00:54 1 1 #> 2: A 715822.8 5505289 2016-11-01 02:01:22 1 1 #> 3: A 715872.9 5505252 2016-11-01 04:01:24 1 1 #> 4: A 715820.5 5505231 2016-11-01 06:01:05 1 1 #> 5: A 715830.6 5505227 2016-11-01 08:01:11 1 1 #> --- #> 4265: C 702093.6 5510180 2017-02-28 14:00:44 1 1 #> 4266: C 702086.0 5510183 2017-02-28 16:00:42 1 1 #> 4267: C 702961.8 5509447 2017-02-28 18:00:53 1 1 #> 4268: C 703130.4 5509528 2017-02-28 20:00:54 1 1 #> 4269: C 702872.3 5508531 2017-02-28 22:00:18 1 1
## Daily movement tracks # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '1 day')
#> ID X Y datetime population group timegroup #> 1: A 715851.4 5505340 2016-11-01 00:00:54 1 1 1 #> 2: A 715822.8 5505289 2016-11-01 02:01:22 1 1 1 #> 3: A 715872.9 5505252 2016-11-01 04:01:24 1 1 1 #> 4: A 715820.5 5505231 2016-11-01 06:01:05 1 1 1 #> 5: A 715830.6 5505227 2016-11-01 08:01:11 1 1 1 #> --- #> 4265: C 702093.6 5510180 2017-02-28 14:00:44 1 1 120 #> 4266: C 702086.0 5510183 2017-02-28 16:00:42 1 1 120 #> 4267: C 702961.8 5509447 2017-02-28 18:00:53 1 1 120 #> 4268: C 703130.4 5509528 2017-02-28 20:00:54 1 1 120 #> 4269: C 702872.3 5508531 2017-02-28 22:00:18 1 1 120
# Subset only first 50 days DT <- DT[timegroup < 25] # Spatial grouping group_lines(DT, threshold = 50, projection = utm, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', sortBy = 'datetime')
#> group column will be overwritten by this function
#> ID X Y datetime population timegroup group #> 1: A 715851.4 5505340 2016-11-01 00:00:54 1 1 1 #> 2: A 715822.8 5505289 2016-11-01 02:01:22 1 1 1 #> 3: A 715872.9 5505252 2016-11-01 04:01:24 1 1 1 #> 4: A 715820.5 5505231 2016-11-01 06:01:05 1 1 1 #> 5: A 715830.6 5505227 2016-11-01 08:01:11 1 1 1 #> --- #> 857: C 710769.9 5507380 2016-11-24 14:00:55 1 24 63 #> 858: C 710930.9 5507290 2016-11-24 16:00:26 1 24 63 #> 859: C 711004.1 5507310 2016-11-24 18:00:49 1 24 63 #> 860: C 711274.1 5507269 2016-11-24 20:00:24 1 24 63 #> 861: C 711054.3 5506998 2016-11-24 22:00:41 1 24 63
## Daily movement tracks by population group_lines(DT, threshold = 50, projection = utm, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', sortBy = 'datetime', splitBy = 'population')
#> group column will be overwritten by this function
#> ID X Y datetime population timegroup group #> 1: A 715851.4 5505340 2016-11-01 00:00:54 1 1 1 #> 2: A 715822.8 5505289 2016-11-01 02:01:22 1 1 1 #> 3: A 715872.9 5505252 2016-11-01 04:01:24 1 1 1 #> 4: A 715820.5 5505231 2016-11-01 06:01:05 1 1 1 #> 5: A 715830.6 5505227 2016-11-01 08:01:11 1 1 1 #> --- #> 857: C 710769.9 5507380 2016-11-24 14:00:55 1 24 63 #> 858: C 710930.9 5507290 2016-11-24 16:00:26 1 24 63 #> 859: C 711004.1 5507310 2016-11-24 18:00:49 1 24 63 #> 860: C 711274.1 5507269 2016-11-24 20:00:24 1 24 63 #> 861: C 711054.3 5506998 2016-11-24 22:00:41 1 24 63