% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/edge_zones.R
\name{edge_zones}
\alias{edge_zones}
\title{Behavioural zones}
\usage{
edge_zones(
  edges = NULL,
  zone_thresholds = NULL,
  zone_labels = NULL,
  blind_volume = NULL
)
}
\arguments{
\item{edges}{distance based edge-list generated by \code{edge_dist},
optionally with direction columns from \code{direction_step} and
\code{edge_direction} (see Details)}

\item{zone_thresholds}{upper thresholds to define behavioural zones, eg.
c(10, 20, 30) defines behavioural zones (0-10], (10-20], (20-30]}

\item{zone_labels}{labels for zones defined by zone_thresholds, must match
zone_thresholds in length}

\item{blind_volume}{(optional) interindividual direction to define
symmetrical window outside of focal individual's perception, eg. 2 becomes
(-2, 2), see Details}
}
\value{
\code{edge_zones} returns the input \code{edges} appended with a zone
column indicating the behavioural zone, using the zone label provided.

See details for appending outputs using modify-by-reference in the
\href{https://docs.ropensci.org/spatsoc/articles/faq.html}{FAQ}.

A message is returned when a zone column already exists in the input
\code{edges}, because it will be overwritten.
}
\description{
\code{edge_zones} returns edge-lists defined by behavioural zones (Couzin
2002). The function expects a distance based edge-list generated by
\code{edge_dist} (optionally with directions measured by
\code{direction_step} and \code{edge_direction}), zone thresholds, labels
and (optionally) a blind volume.
}
\details{
\code{edge_zones} uses interindividual distances, and optionally directions,
to assign neighboring individuals to a focal individual's behavioural zones.
The user provides zone thresholds (eg. 25 m, 100 m, 250 m) along with zone
labels (eg. zone of repulsion, zone of orientation, zone of attraction),
according to their objectives, study species and system. The optional blind
volume can be provided to define a range of interindividual directions that
correspond to the limits of the focal individual's perception.

Two workflows for this function exist, depending on if the blind volume
argument is used:

a) If the blind volume is not provided, simply provide your distance based
edge-lists from \code{edge_dist} with zone thresholds and labels.

b) If the blind volume is provided, the following order of functions is
expected to ensure the relevant direction columns are available:
\enumerate{
\item direction_step(DT)
\item edges <- edge_dist(DT)
\item dyad_id(edges)
\item dyad_directions <- edge_direction(edges, DT)
\item edge_zones(dyad_directions)
}

Interindividual distances are converted into behavioural zones using
\code{cut}. The thresholds provided are used as cut points for a series of
intervals that are open on the left and closed on the right, starting at 0.
See details in \code{\link[base:cut]{base::cut()}}.

The (optional) blind volume defines the range of interindividual directions
between the focal individual (ID1) and the neighbour (ID2) that is outside
of the focal individual's perception. The interindividual direction (column
"direction_dyad" from \code{edge_direction}) is made relative to the focal
individual's movement direction (column "direction" from
\code{direction_step}). The argument blind_volume expects a single value to
define a symmetrical window behind the focal individual's movement direction
eg. where blind_volume = 2, the symmetrical window is from (-2, 2).

The \code{edges} 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()}}.
}
\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 = FALSE
)

# Calculate behavioural zones
edge_zones(
  edges,
  zone_thresholds = c(25, 50, 75),
  zone_labels = c('repulsion', 'orientation', 'attraction')
)

# Alternatively, if a user wants to specify a blind volume,
#   we need to measure directions
direction_step(
  DT = DT,
  id = 'ID',
  coords = c('X', 'Y'),
  crs = 32736
)

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

# Interindividual directions
dyad_directions <- edge_direction(
  edges,
  DT,
  id = 'ID',
  coords = c('X', 'Y'),
  crs = 32736,
  timegroup = 'timegroup'
)

# Calculate behavioural zones
edge_zones(
  dyad_directions,
  zone_thresholds = c(25, 50, 75),
  zone_labels = c('repulsion', 'orientation', 'attraction'),
  blind_volume = 2
)
print(dyad_directions[, .SD[1:3], by = zone])

# Or, using the new geometry interface
get_geometry(DT, coords = c('X', 'Y'), crs = 32736)
direction_step(DT, id = 'ID')
edges <- edge_dist(DT, threshold = 100, id = 'ID', timegroup = 'timegroup', returnDist = TRUE)
dyad_id(edges, id = 'ID1', id2 = 'ID2')
dyad_directions <- edge_direction(
  edges,
  DT,
  id = 'ID',
  timegroup = 'timegroup'
)
edge_zones(
  dyad_directions,
  zone_thresholds = c(25, 50, 75),
  zone_labels = c('repulsion', 'orientation', 'attraction'),
  blind_volume = 2
)
print(dyad_directions[, .SD[1:3], by = zone])
}
\references{
The behavioural zones metric is defined in Couzin et al. 2002
(\doi{doi:10.1006/jtbi.2002.3065}).

See examples of measuring behavioural zones:
\itemize{
\item \doi{doi:10.1073/pnas.1001763107}
\item \doi{doi:10.1371/journal.pcbi.1008832}
\item \doi{doi:10.3389/fphy.2021.715996}
}
}
\seealso{
\link{edge_dist} \link{direction_step} \link{edge_direction}

Other Distance functions: 
\code{\link{distance_to_centroid}()},
\code{\link{distance_to_leader}()},
\code{\link{edge_dist}()},
\code{\link{edge_nn}()}

Other Direction functions: 
\code{\link{direction_group}()},
\code{\link{direction_polarization}()},
\code{\link{direction_step}()},
\code{\link{direction_to_centroid}()},
\code{\link{direction_to_leader}()},
\code{\link{edge_alignment}()},
\code{\link{edge_delay}()},
\code{\link{edge_direction}()},
\code{\link{leader_direction_group}()},
\code{\link{leader_edge_delay}()}
}
\concept{Direction functions}
\concept{Distance functions}
\concept{Edge-list generating functions}
