% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/build_lines.R
\name{build_lines}
\alias{build_lines}
\title{Build lines}
\usage{
build_lines(
  DT = NULL,
  crs = NULL,
  id = NULL,
  coords = NULL,
  sortBy = NULL,
  splitBy = NULL,
  projection = NULL
)
}
\arguments{
\item{DT}{input data.table}

\item{crs}{numeric or character defining the coordinate reference
system to be passed to \link[sf:st_crs]{sf::st_crs}. For example, either
\code{crs = "EPSG:32736"} or \code{crs = 32736}. Used only if coords are provided,
see details under Interface}

\item{id}{character string of ID column name}

\item{coords}{character vector of X coordinate and Y coordinate column names.
Note: the order is assumed X followed by Y column names}

\item{sortBy}{Character string of date time column(s) to sort rows by. Must
be a POSIXct.}

\item{splitBy}{(optional) character string or vector of grouping column
name(s) upon which the output will be calculated}

\item{projection}{(deprecated) use crs argument instead}
}
\value{
\code{build_lines} returns an sf LINESTRING object with a line
for each individual (and optionally \code{splitBy} combination).

Individuals (or combinations of individuals and \code{splitBy}) with less than two
relocations are dropped since it requires at least two relocations to
build a line.
}
\description{
\code{build_lines} generates a simple feature collection with LINESTRINGs from a
\code{data.table}. The function expects a \code{data.table} with relocation data,
individual identifiers, a sorting column and a \code{crs}. The relocation
data is transformed into LINESTRINGs for each individual and, optionally,
combination of columns listed in \code{splitBy}. Relocation data should be in two
columns representing the X and Y coordinates.
}
\details{
\subsection{R-spatial evolution}{

Please note, spatsoc has followed updates from R spatial, GDAL and PROJ
for handling coordinate reference systems, see more at
\url{https://r-spatial.org/r/2020/03/17/wkt.html}.

In addition, \code{build_lines} previously used \link[sp:SpatialLines]{sp::SpatialLines} but has been
updated to use \link[sf:st_as_sf]{sf::st_as_sf} and \link[sf:st]{sf::st_linestring} according to the
R-spatial evolution, see more at
\url{https://r-spatial.org/r/2022/04/12/evolution.html}.
}

\subsection{Notes on arguments}{

The \code{crs} argument expects a numeric or character defining the
coordinate reference system.
For example, for UTM zone 36N (EPSG 32736), the crs argument is either
\code{crs = 'EPSG:32736'} or \code{crs = 32736}.
See details in \code{\link[sf:st_crs]{sf::st_crs()}} and \url{https://spatialreference.org}
for a list of EPSG codes.

The \code{sortBy} argument is used to order the input \code{DT} when creating
sf LINESTRINGs. It must a column in the input \code{DT} of type
POSIXct to ensure the rows are sorted by date time.

The \code{splitBy} argument offers further control building LINESTRINGs.
If in your input \code{DT}, you have multiple temporal groups (e.g.: years) for
example, you can provide the name of the column which identifies them and
build LINESTRINGs for each individual in each year.

\code{build_lines} is used by \code{group_lines} for grouping overlapping
lines generated from relocations.
}
}
\examples{
# Load data.table
library(data.table)
\dontshow{data.table::setDTthreads(1)}

# 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')]

# EPSG code for example data
utm <- 32736

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

# Build lines for each individual by year
DT[, yr := year(datetime)]
lines <- build_lines(DT, crs = utm, id = 'ID', coords = c('X', 'Y'),
            sortBy = 'datetime', splitBy = 'yr')
}
\seealso{
\code{group_lines}

Other Build functions: 
\code{\link{build_polys}()}
}
\concept{Build functions}
