% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/group_polys.R
\name{group_polys}
\alias{group_polys}
\title{Group polygons}
\usage{
group_polys(
  DT = NULL,
  area = NULL,
  hrType = NULL,
  hrParams = NULL,
  crs = NULL,
  id = NULL,
  coords = NULL,
  splitBy = NULL,
  sfPolys = NULL,
  projection = NULL
)
}
\arguments{
\item{DT}{input data.table}

\item{area}{logical indicating either overlap group (when \code{FALSE}) or
area and proportion of overlap (when \code{TRUE})}

\item{hrType}{type of HR estimation, either 'mcp' or 'kernel'}

\item{hrParams}{a named list of parameters for \code{adehabitatHR} functions}

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

\item{sfPolys}{Alternatively, provide solely a simple features object with
POLYGONs or MULTIPOLYGONs. If sfPolys are provided, id is required and
splitBy cannot be used.}

\item{projection}{(deprecated) use crs argument instead}
}
\value{
When \code{area} is \code{FALSE}, \code{group_polys} returns the input \code{DT} appended
with a \code{group} column. As with the other grouping functions,  the actual
value of \code{group} is arbitrary and represents the identity of a given group
where 1 or more individuals are assigned to a group. If the data was
reordered, the \code{group} may change, but the contents of each group would
not. When \code{area} is \code{TRUE}, \code{group_polys} returns a proportional area
overlap \code{data.table}. In this case, ID refers to the focal individual of
which the total area is compared against the overlapping area of ID2.

If \code{area} is \code{FALSE}, a message is returned when a column named \code{group}
already exists in the input \code{DT}, because it will be overwritten.

Along with changes to follow the R-spatial evolution, \code{group_polys} also
now returns area and proportion of overlap with units explicitly specified
through the \code{units} package.

Note: if area is TRUE, the output of \code{group_polys} needs to be
reassigned. See details in
\href{https://docs.ropensci.org/spatsoc/articles/faq.html}{FAQ}.
}
\description{
\code{group_polys} groups rows into spatial groups by overlapping polygons (home
ranges). The function expects a \code{data.table} with relocation data, individual
identifiers and an \code{area} argument.  The relocation data is transformed into
home range POLYGONs using \code{\link[=build_polys]{build_polys()}} with \link[adehabitatHR:mcp]{adehabitatHR::mcp} or
\link[adehabitatHR:kernelUD]{adehabitatHR::kernelUD}. If the \code{area} argument is \code{FALSE}, \code{group_polys}
returns grouping calculated by spatial overlap. If the \code{area} argument is
\code{TRUE}, \code{group_polys} returns the area area and proportion of overlap.
Relocation data should be in two columns representing the X and Y
coordinates.
}
\details{
\subsection{R-spatial evolution}{

Please note, spatsoc has followed updates from R spatial, GDAL and PROJ for
handling coordinate reference systems, see more below and  details at
\url{https://r-spatial.org/r/2020/03/17/wkt.html}.

In addition, \code{group_polys} previously used rgeos::gIntersection,
rgeos::gIntersects and rgeos::gArea but has been
updated to use \link[sf:geos_binary_pred]{sf::st_intersects}, \link[sf:geos_binary_ops]{sf::st_intersection} and \link[sf:geos_measures]{sf::st_area}
according to the R-spatial evolution, see more
at \url{https://r-spatial.org/r/2022/04/12/evolution.html}.
}

\subsection{Notes on arguments}{

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()}}.

The \code{id}, \code{coords} (and optional \code{splitBy}) arguments expect
the names of respective columns in \code{DT} which correspond to the
individual identifier, X and Y coordinates, and additional grouping 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.

The \code{hrType} must be either one of "kernel" or "mcp". The
\code{hrParams} must be a named list of arguments matching those of
\code{\link[adehabitatHR:kernelUD]{adehabitatHR::kernelUD()}} or \code{\link[adehabitatHR:mcp]{adehabitatHR::mcp()}}.

The \code{splitBy} argument offers further control over grouping. If within
your \code{DT}, you have multiple populations, subgroups or other distinct
parts, you can provide the name of the column which identifies them to
\code{splitBy}. The grouping performed by \code{group_polys} will only
consider rows within each \code{splitBy} subgroup.
}
}
\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')]

# EPSG code for example data
utm <- 32736

group_polys(DT, area = FALSE, hrType = 'mcp',
            hrParams = list(percent = 95), crs = utm,
            id = 'ID', coords = c('X', 'Y'))

areaDT <- group_polys(DT, area = TRUE, hrType = 'mcp',
                      hrParams = list(percent = 95), crs = utm,
                      id = 'ID', coords = c('X', 'Y'))
print(areaDT)
}
\seealso{
\code{\link[=build_polys]{build_polys()}} \code{\link[=group_times]{group_times()}}

Other Spatial grouping: 
\code{\link{group_lines}()},
\code{\link{group_pts}()}
}
\concept{Spatial grouping}
