build_lines: Build Lines

Description Usage Arguments Details Value See Also Examples

View source: R/build_lines.R

Description

build_lines creates a SpatialLines object from a data.table. The function accepts a data.table with relocation data, individual identifiers a sorting column and a projection. The relocation data is transformed into SpatialLines for each individual and optionally, each splitBy. Relocation data should be in two columns representing the X and Y coordinates.

Usage

1
2
build_lines(DT = NULL, projection = NULL, id = NULL, coords = NULL,
  sortBy = NULL, splitBy = NULL)

Arguments

DT

input data.table

projection

PROJ.4 character string

id

Character string of ID column name

coords

Character vector of X coordinate and Y coordinate column names

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

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 splitBy) arguments expect the names of respective columns in DT which correspond to the individual identifier, X and Y coordinates, sorting column, and additional splitting columns.

The projection expects a PROJ.4 character string (such as those available on spatialreference.org).

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 splitBy argument offers further control building SpatialLines. If in your DT, you have multiple temporal groups (e.g.: years) for example, you can provide the name of the column which identifies them and build SpatialLines for each individual in each year.

build_lines is used by group_lines for grouping overlapping lines created from relocations.

Value

build_lines returns a SpatialLines object with a line for each individual (and optionally splitBy combination).

An error is returned when an individual has less than 2 relocations, making it impossible to build a line.

See Also

group_lines

Other Build functions: build_polys

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# 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')]

# Proj4 string for example data
utm <- '+proj=utm +zone=36 +south +ellps=WGS84 +datum=WGS84 +units=m +no_defs'

# Build lines for each individual
build_lines(DT, projection = utm, id = 'ID', coords = c('X', 'Y'),
            sortBy = 'datetime')

# Build lines for each individual by year
DT[, yr := year(datetime)]
build_lines(DT, projection = utm, id = 'ID', coords = c('X', 'Y'),
            sortBy = 'datetime', splitBy = 'yr')

ropensci/spatsoc documentation built on Oct. 27, 2018, 12:15 a.m.