% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/centroid_dyad.R
\name{centroid_dyad}
\alias{centroid_dyad}
\title{Dyad centroid}
\usage{
centroid_dyad(
  edges = NULL,
  DT = NULL,
  id = NULL,
  coords = NULL,
  crs = NULL,
  timegroup = "timegroup",
  geometry = "geometry"
)
}
\arguments{
\item{edges}{edge-list generated generated by \code{edge_dist} or
\code{edge_nn}, with dyad ID column generated by \code{dyad_id}}

\item{DT}{input data.table with timegroup column generated with
\code{group_times} matching the input data.table used to generate the edge
list with \code{edge_nn} or \code{edge_dist}}

\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{timegroup}{character string of timegroup column name, default "timegroup"}

\item{geometry}{simple feature geometry list column name, generated by
\code{\link[=get_geometry]{get_geometry()}}. Default 'geometry', see details under Interface}
}
\value{
\code{centroid_dyad} returns the input \code{edges} appended with centroid
column(s) for each timestep and dyad id.

If \code{coords} are provided, the centroid columns will be named by prefixing
the coordinate column names with "centroid_" (eg. "X" = "centroid_X"). If
\code{geometry} is used, the centroid column will be named "centroid".

Note: due to the merge required within this function, the output needs to be
reassigned unlike some other \code{spatsoc} functions like \code{dyad_id} and
\code{group_pts}. See details in
\href{https://docs.ropensci.org/spatsoc/articles/faq.html}{FAQ}.

A message is returned when the centroid column(s) already exist in the input
because they will be overwritten.
}
\description{
\code{centroid_dyad} calculates the centroid (mean location) of a dyad in each
observation identified by \code{edge_nn} or \code{edge_dist}. The function expects an
edge-list generated by \code{edge_nn} or \code{edge_dist} and a \code{data.table} with
relocation data appended with a \code{timegroup} column from \code{group_times}.
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()}}.
}
\details{
The \code{edges} and \code{DT} must be \code{data.table}s. 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{edges} and \code{DT} are internally merged in this function using the columns
\code{id}, \code{dyadID} and \code{timegroup}. This function expects a \code{dyadID} present,
generated with the \code{dyad_id} function. The \code{id} and \code{timegroup} arguments
expect the names of a column in \code{DT} which correspond to the id and timegroup
columns.

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

Two interfaces are available for providing coordinates:
\enumerate{
\item Provide \code{coords} and optionally \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. For centroid
calculations, if \code{crs} is NULL, it will be internally set to \code{NA_crs_}.
\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{Centroid function}{


The underlying centroid function used depends on the crs of the coordinates
or geometry provided.
\itemize{
\item If the crs is longlat degrees (as determined by
\code{\link[sf:st_is_longlat]{sf::st_is_longlat()}}) and \code{\link[sf:s2]{sf::sf_use_s2()}} is TRUE, the distance function
is \code{\link[sf:geos_unary]{sf::st_centroid()}} which passes to \code{\link[s2:s2_boundary]{s2::s2_centroid()}}.
\item If the crs is longlat degrees but \code{\link[sf:s2]{sf::sf_use_s2()}} is FALSE, the centroid
calculated will be incorrect. See \code{\link[sf:geos_unary]{sf::st_centroid()}}.
\item If the crs is not longlat degrees (eg. NULL, NA_crs_, or projected), the
centroid function used is mean.
}

Note: if the input is length 1, the input 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"))
\dontshow{
# (Subset example data to reduce runtime on CRAN)
if (isFALSE(rlang::is_interactive())) {
  DT <- DT[as.Date(datetime) == '2017-01-17']
}
}
# Cast the character column to POSIXct
DT[, datetime := as.POSIXct(datetime, tz = 'UTC')]

# Temporal grouping
group_times(DT, datetime = 'datetime', threshold = '20 minutes')

# Edge-list generation
edges <- edge_dist(
    DT,
    threshold = 100,
    id = 'ID',
    coords = c('X', 'Y'),
    timegroup = 'timegroup',
    returnDist = TRUE,
    fillNA = FALSE
  )

# Generate dyad id
dyad_id(edges, id1 = 'ID1', id2 = 'ID2')

# Calculate dyad centroid
centroids <- centroid_dyad(
  edges,
  DT,
  id = 'ID',
  coords = c('X', 'Y'),
  timegroup = 'timegroup'
)

print(centroids)

# Or, using the new geometry interface
get_geometry(DT, coords = c('X', 'Y'), crs = 32736)
edges <- edge_dist(DT, threshold = 100, id = 'ID', timegroup = 'timegroup')
dyad_id(edges, id = 'ID1', id2 = 'ID2')
centroids <- centroid_dyad(
  edges,
  DT,
  id = 'ID',
  timegroup = 'timegroup'
)
print(centroids)
}
\seealso{
\link{dyad_id} \link{edge_dist} \link{edge_nn} \link{group_pts}

Other Centroid functions: 
\code{\link{centroid_fusion}()},
\code{\link{centroid_group}()},
\code{\link{direction_to_centroid}()},
\code{\link{distance_to_centroid}()}
}
\concept{Centroid functions}
