group_polys
groups rows into spatial groups by overlapping polygons
(home ranges). The function accepts a data.table
with relocation data,
individual identifiers and an area
argument. The relocation data is
transformed into home range SpatialPolygons
. If the area
argument is FALSE
, group_polys
returns grouping calculated by
overlap. If the area
argument is TRUE
, the area and proportion
of overlap is calculated. Relocation data should be in two columns
representing the X and Y coordinates.
Usage
group_polys(
DT = NULL,
area = NULL,
hrType = NULL,
hrParams = NULL,
projection = NULL,
id = NULL,
coords = NULL,
splitBy = NULL,
spPolys = NULL
)
Arguments
- DT
input data.table
- area
boolean indicating either overlap group (when
FALSE
) or area and proportion of overlap (whenTRUE
)- hrType
type of HR estimation, either 'mcp' or 'kernel'
- hrParams
a named list of parameters for
adehabitatHR
functions- projection
character string defining the projection to be passed to
sp::CRS
. For example, for UTM zone 36S (EPSG 32736), the projection argument is 'EPSG:32736'. See details.- id
Character string of ID column name
- coords
Character vector of X coordinate and Y coordinate column names
- splitBy
(optional) character string or vector of grouping column name(s) upon which the grouping will be calculated
- spPolys
Alternatively, provide solely a SpatialPolygons object
Value
When area
is FALSE
, group_polys
returns the
input DT
appended with a group
column. As with the other
grouping functions, the actual value of 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 group
may
change, but the contents of each group would not. When area
is
TRUE
, group_polys
returns a proportional area overlap
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 area
is FALSE
, a message is returned when a column named
group
already exists in the input DT
, because it will be
overwritten.
Details
The DT
must be a data.table
. If your data is a
data.frame
, you can convert it by reference using
data.table::setDT
.
The id
, coords
(and optional splitBy
) arguments expect
the names of respective columns in DT
which correspond to the
individual identifier, X and Y coordinates, and additional grouping columns.
The projection
argument expects a character string defining the EPSG
code. For example, for UTM zone 36N (EPSG 32736), the projection argument is
'EPSG:32736'. See https://spatialreference.org for a list of EPSG
codes. Please note, R spatial has followed updates to GDAL and PROJ for
handling projections, see more at
https://r-spatial.org/r/2020/03/17/wkt.html. It is likely
that build_polys
will return "Warning in proj4string(xy) :
CRS object has comment, which is lost in output" due to these changes.
The hrType
must be either one of "kernel" or "mcp". The
hrParams
must be a named list of arguments matching those of
adehabitatHR::kernelUD
or adehabitatHR::mcp
.
The splitBy
argument offers further control over grouping. If within
your DT
, you have multiple populations, subgroups or other distinct
parts, you can provide the name of the column which identifies them to
splitBy
. The grouping performed by group_polys
will only
consider rows within each splitBy
subgroup.
See also
Other Spatial grouping:
group_lines()
,
group_pts()
Examples
# Load data.table
library(data.table)
# 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')]
#> ID X Y datetime population
#> 1: A 715851.4 5505340 2016-11-01 00:00:54 1
#> 2: A 715822.8 5505289 2016-11-01 02:01:22 1
#> 3: A 715872.9 5505252 2016-11-01 04:01:24 1
#> 4: A 715820.5 5505231 2016-11-01 06:01:05 1
#> 5: A 715830.6 5505227 2016-11-01 08:01:11 1
#> ---
#> 14293: J 700616.5 5509069 2017-02-28 14:00:54 1
#> 14294: J 700622.6 5509065 2017-02-28 16:00:11 1
#> 14295: J 700657.5 5509277 2017-02-28 18:00:55 1
#> 14296: J 700610.3 5509269 2017-02-28 20:00:48 1
#> 14297: J 700744.0 5508782 2017-02-28 22:00:39 1
# EPSG code for example data
utm <- 'EPSG:32736'
group_polys(DT, area = FALSE, hrType = 'mcp',
hrParams = list(percent = 95), projection = utm,
id = 'ID', coords = c('X', 'Y'))
#> ID X Y datetime population group
#> 1: A 715851.4 5505340 2016-11-01 00:00:54 1 1
#> 2: A 715822.8 5505289 2016-11-01 02:01:22 1 1
#> 3: A 715872.9 5505252 2016-11-01 04:01:24 1 1
#> 4: A 715820.5 5505231 2016-11-01 06:01:05 1 1
#> 5: A 715830.6 5505227 2016-11-01 08:01:11 1 1
#> ---
#> 14293: J 700616.5 5509069 2017-02-28 14:00:54 1 1
#> 14294: J 700622.6 5509065 2017-02-28 16:00:11 1 1
#> 14295: J 700657.5 5509277 2017-02-28 18:00:55 1 1
#> 14296: J 700610.3 5509269 2017-02-28 20:00:48 1 1
#> 14297: J 700744.0 5508782 2017-02-28 22:00:39 1 1
areaDT <- group_polys(DT, area = TRUE, hrType = 'mcp',
hrParams = list(percent = 95), projection = utm,
id = 'ID', coords = c('X', 'Y'))
#> Warning: GEOS support is provided by the sf and terra packages among others