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

\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{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{splitBy}{(optional) character string or vector of grouping column
name(s) upon which the output will be calculated}

\item{geometry}{simple feature geometry list column name, generated by
\code{\link[=get_geometry]{get_geometry()}}. Default 'geometry', see details under Interface}

\item{projection}{(deprecated) use crs argument instead}
}
\value{
\code{direction_step} returns the input \code{DT} appended with a \code{direction}
column with units set to radians using the \code{units} package.

This column represents the azimuth between the sequence of points for each
individual computed using \code{\link[lwgeom:st_geod_azimuth]{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
\code{direction_step}. In addition, the direction column will include an \code{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 \code{DT}, because it will be overwritten.

An error is returned if there are any missing values in coordinates /
geometry as the underlying direction function (\code{\link[lwgeom:st_geod_azimuth]{lwgeom::st_geod_azimuth()}})
does not accept missing values.

See details for appending outputs using modify-by-reference in the
\href{https://docs.ropensci.org/spatsoc/articles/faq.html}{FAQ}.
}
\description{
\code{direction_step} calculates the direction of movement steps in radians. The
function expects a \code{data.table} with relocation data and individual
identifiers. Relocation data should be in two columns representing the X and
Y coordinates, or in a geometry column prepared by the helper function
\code{\link[=get_geometry]{get_geometry()}}. 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.
}
\details{
The \code{DT} must be a \code{data.table}. If your data is a \code{data.frame}, you can
convert it by reference using \code{\link[data.table:setDT]{data.table::setDT()}} or by reassigning using
\code{\link[data.table:data.table]{data.table::data.table()}}.

The \code{id}, and optional \code{splitBy} arguments expect the names of a column in
\code{DT} which correspond to the individual identifier and additional grouping
columns.

The \code{splitBy} argument offers further control over grouping. If within your
\code{DT}, you have distinct sampling periods for each individual, you can provide
the column name(s) which identify them to \code{splitBy}. The direction
calculation by \code{\link[=direction_step]{direction_step()}} will only consider rows within each \code{id}
and \code{splitBy} subgroup.

See below under "Interface" for details on providing coordinates and under
"Direction function" for details on the underlying direction function used.
}
\section{Interface}{

Two interfaces are available for providing coordinates:
\enumerate{
\item Provide \code{coords} and \code{crs}. The \code{coords} argument expects the names of
the X and Y coordinate columns. The \code{crs} argument expects a character
string or numeric defining the coordinate reference system to be passed to
\link[sf:st_crs]{sf::st_crs}. For example, for UTM zone 36S (EPSG 32736), the crs argument
is \code{crs = "EPSG:32736"} or \code{crs = 32736}. See \url{https://spatialreference.org}
for a list of EPSG codes.
\item (New!) Provide \code{geometry}. The \code{geometry} argument allows the user to
supply a \code{geometry} column that represents the coordinates as a simple
feature geometry list column. This interface expects the user to prepare
their input DT with \code{\link[=get_geometry]{get_geometry()}}. To use this interface, leave the
\code{coords} and \code{crs} arguments \code{NULL}, and the default argument for \code{geometry}
('geometry') will be used directly.
}
}

\section{Direction function}{


The underlying distance function used depends on the crs of the coordinates
or geometry provided.
\itemize{
\item If the crs is provided and longlat degrees (as determined by
\code{\link[sf:st_is_longlat]{sf::st_is_longlat()}}), the distance function is
\code{\link[lwgeom:st_geod_azimuth]{lwgeom::st_geod_azimuth()}}.
\item If the crs is provided and not longlat degrees (eg. a projected UTM),
the coordinates or geometry are transformed to \code{sf::st_crs(4326)} before the
distance is measured using \code{\link[lwgeom:st_geod_azimuth]{lwgeom::st_geod_azimuth()}}.
\item If the crs is NULL or NA_crs_, the distance function cannot be used
and an error is returned.
}
}

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

# Set order using data.table::setorder
setorder(DT, datetime)

# Calculate direction
direction_step(
  DT = DT,
  id = 'ID',
  coords = c('X', 'Y'),
  crs = 32736
)

# Or: geometry interface
get_geometry(DT, coords = c('X', 'Y'), crs = 32736)
direction_step(DT, id = 'ID')

# 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)
example[, .(step, direction, units::set_units(direction, 'degree'))]
}
\seealso{
\code{\link[lwgeom:st_geod_azimuth]{lwgeom::st_geod_azimuth()}}, \code{\link[amt:steps]{amt::direction_abs()}},
\code{\link[geosphere:bearing]{geosphere::bearing()}}

Other Direction functions: 
\code{\link{direction_group}()},
\code{\link{direction_polarization}()},
\code{\link{direction_to_centroid}()},
\code{\link{direction_to_leader}()},
\code{\link{edge_alignment}()},
\code{\link{edge_delay}()},
\code{\link{edge_direction}()},
\code{\link{edge_zones}()},
\code{\link{leader_direction_group}()},
\code{\link{leader_edge_delay}()}
}
\concept{Direction functions}
