Skip to contents

Group Polygons

Source: R/group_polys.R
group_polys.Rd

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 (when TRUE)

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

build_polys group_times

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