% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fusion_id.R
\name{fusion_id}
\alias{fusion_id}
\title{Fission-fusion id}
\usage{
fusion_id(
  edges = NULL,
  threshold = NULL,
  n_min_length = 0,
  n_max_missing = 0,
  allow_split = FALSE
)
}
\arguments{
\item{edges}{distance based edge-list generated by \code{edge_dist} function,
with 'dyadID' column generated by \code{dyad_ID}}

\item{threshold}{spatial distance threshold in the units of the crs}

\item{n_min_length}{minimum length of fusion events}

\item{n_max_missing}{maximum number of missing observations within a fusion
event}

\item{allow_split}{logical defining if a single observation can be greater
than the threshold distance without initiating fission event}
}
\value{
\code{fusion_id} returns the input \code{edges} appended with a
\code{fusionID} column.

This column represents the fusion event id. As with \code{spatsoc}'s
grouping functions, the actual value of \code{fusionID} is arbitrary and
represents the identity of a given fusion event. If the data was reordered,
the \code{fusionID} may change, but the membership of each fusion event
would not.

A message is returned when a column named \code{fusionID} already exists in
the input \code{edges}, because it will be overwritten.

See details for appending outputs using modify-by-reference in the
\href{https://docs.ropensci.org/spatsoc/articles/faq.html}{FAQ}.
}
\description{
\code{fusion_id} identifies fusion events in distance based edge-lists.
The function expects a distance based edge-list generated by
\code{edge_dist}, a threshold argument and arguments controlling how fusion
events are defined.
}
\details{
The \code{edges} must be a \code{data.table} returned by the \code{edge_dist}
function. In addition, \code{fusion_id} requires a dyad ID set on the edge
list generated by \code{dyad_id}. If your data is a \code{data.frame}, you
can convert it by reference using
\code{\link[data.table:setDT]{data.table::setDT()}}.

The \code{threshold} must be provided in the units of the coordinates. The
\code{threshold} must be larger than 0. Eg. in the case of UTM, a \code{threshold} = 50
would indicate a 50 m distance threshold.

The \code{n_min_length} argument defines the minimum number of successive
fixes that are required to establish a fusion event. The \code{n_max_missing}
argument defines the the maximum number of allowable missing observations for
the dyad within a fusion event. The \code{allow_split} argument defines if a
single observation can be greater than the threshold distance without
initiating fission event.
}
\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')]

# 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 = TRUE
  )

dyad_id(edges, 'ID1', 'ID2')

fusion_id(
  edges = edges,
  threshold = 100,
  n_min_length = 1,
  n_max_missing = 0,
  allow_split = FALSE
  )

# 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', returnDist = TRUE)
dyad_id(edges, id = 'ID1', id2 = 'ID2')
fusion_id(edges, threshold = 100)
}
\references{
See examples of identifying fission-fusion events with spatiotemporal data:
\itemize{
\item \doi{doi:10.1111/ele.12457}
\item \doi{doi:10.1016/j.anbehav.2018.03.014}
\item \doi{doi:10.1890/08-0345.1}
}
}
\seealso{
\code{edge_dist}
}
