#' Dyad centroid
#'
#' `centroid_dyad` calculates the centroid (mean location) of a dyad in each
#' observation identified by `edge_nn` or `edge_dist`. The function expects an
#' edge-list generated by `edge_nn` or `edge_dist` and a `data.table` with
#' relocation data appended with a `timegroup` column from `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
#' [get_geometry()].
#'
#' The `edges` and `DT` must be `data.table`s. If your data is a `data.frame`,
#' you can convert it by reference using [data.table::setDT()] or by reassigning
#' using [data.table::data.table()].
#'
#' The `edges` and `DT` are internally merged in this function using the columns
#' `id`, `dyadID` and `timegroup`. This function expects a `dyadID` present,
#' generated with the `dyad_id` function. The `id` and `timegroup` arguments
#' expect the names of a column in `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.
#'
#' @inheritSection centroid_group Interface
#' @inheritSection centroid_group Centroid function
#'
#' @param edges edge-list generated generated by `edge_dist` or
#'  `edge_nn`, with dyad ID column generated by `dyad_id`
#' @param DT input data.table with timegroup column generated with
#'   `group_times` matching the input data.table used to generate the edge
#'   list with `edge_nn` or `edge_dist`
#' @inheritParams edge_alignment
#' @inheritParams group_pts
#' @inheritParams centroid_group
#'
#' @return `centroid_dyad` returns the input `edges` appended with centroid
#'   column(s) for each timestep and dyad id.
#'
#'  If `coords` are provided, the centroid columns will be named by prefixing
#'  the coordinate column names with "centroid_" (eg. "X" = "centroid_X"). If
#'  `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 `spatsoc` functions like `dyad_id` and
#'  `group_pts`. See details in
#'  [FAQ](https://docs.ropensci.org/spatsoc/articles/faq.html).
#'
#'  A message is returned when the centroid column(s) already exist in the input
#'  because they will be overwritten.
#'
#' @export
#' @family Centroid functions
#' @seealso [dyad_id] [edge_dist] [edge_nn] [group_pts]
#' @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)
centroid_dyad <- function(
    edges = NULL,
    DT = NULL,
    id = NULL,
    coords = NULL,
    crs = NULL,
    timegroup = 'timegroup',
    geometry = 'geometry') {

  centroid_(
    'dyadID',
    edges = edges,
    DT = DT,
    id = id,
    coords = coords,
    crs = crs,
    timegroup = timegroup,
    geometry = geometry
  )
}
