build_polys creates a SpatialPolygons object from a data.table. The function accepts a data.table with relocation data, individual identifiers, a projection, hrType and hrParams. The relocation data is transformed into SpatialPolygons for each individual and optionally, each splitBy. Relocation data should be in two columns representing the X and Y coordinates.

build_polys(DT = NULL, projection = NULL, hrType = NULL,
  hrParams = NULL, id = NULL, coords = NULL, splitBy = NULL,
  spPts = NULL)

Arguments

DT

input data.table

projection

PROJ.4 character string

hrType

type of HR estimation, either 'mcp' or 'kernel'

hrParams

a named list of parameters for adehabitatHR functions

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

spPts

alternatively, provide solely a SpatialPointsDataFrame with one column representing the ID of each point.

Value

build_polys returns a SpatialPolygons object with a polyon for each individual (and optionally splitBy combination).

An error is returned when hrParams do not match the arguments of the hrType adehabitatHR function.

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 expects a PROJ.4 character string (such as those available on spatialreference.org). build_polys expects planar coordinates (not unprojected latitude, longitude).

The hrType must be either one of "kernel" or "mcp". The hrParams must be a named list of arguments matching those of adehabitatHR::kernelUD and adehabitatHR::getverticeshr or adehabitatHR::mcp.

The splitBy argument offers further control building SpatialPolygons. If in your DT, you have multiple temporal groups (e.g.: years) for example, you can provide the name of the column which identifies them and build SpatialPolygons for each individual in each year.

group_polys uses build_polys for grouping overlapping polygons created from relocations.

See also

group_polys

Other Build functions: build_lines

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
# Proj4 string for example data utm <- '+proj=utm +zone=36 +south +ellps=WGS84 +datum=WGS84 +units=m +no_defs' # Build polygons for each individual using kernelUD and getverticeshr build_polys(DT, projection = utm, hrType = 'kernel', hrParams = list(grid = 60, percent = 95), id = 'ID', coords = c('X', 'Y'))
#> Object of class "SpatialPolygonsDataFrame" (package sp): #> #> Number of SpatialPolygons: 10 #> #> Variables measured: #> id area #> A A 19234.537 #> B B 1731.639 #> C C 15123.816 #> D D 1612.764 #> E E 7519.027 #> F F 11504.194 #> ... #>
# Build polygons for each individual by year DT[, yr := year(datetime)]
#> ID X Y datetime population yr #> 1: A 715851.4 5505340 2016-11-01 00:00:54 1 2016 #> 2: A 715822.8 5505289 2016-11-01 02:01:22 1 2016 #> 3: A 715872.9 5505252 2016-11-01 04:01:24 1 2016 #> 4: A 715820.5 5505231 2016-11-01 06:01:05 1 2016 #> 5: A 715830.6 5505227 2016-11-01 08:01:11 1 2016 #> --- #> 14293: J 700616.5 5509069 2017-02-28 14:00:54 1 2017 #> 14294: J 700622.6 5509065 2017-02-28 16:00:11 1 2017 #> 14295: J 700657.5 5509277 2017-02-28 18:00:55 1 2017 #> 14296: J 700610.3 5509269 2017-02-28 20:00:48 1 2017 #> 14297: J 700744.0 5508782 2017-02-28 22:00:39 1 2017
build_polys(DT, projection = utm, hrType = 'mcp', hrParams = list(percent = 95), id = 'ID', coords = c('X', 'Y'), splitBy = 'yr')
#> Object of class "SpatialPolygonsDataFrame" (package sp): #> #> Number of SpatialPolygons: 20 #> #> Variables measured: #> id area #> A-2016 A-2016 141208128 #> A-2017 A-2017 68039437 #> B-2016 B-2016 7851014 #> B-2017 B-2017 9473597 #> C-2016 C-2016 90247899 #> C-2017 C-2017 64419958 #> ... #>
# Build polygons from SpatialPointsDataFrame library(sp) pts <- SpatialPointsDataFrame(coords = DT[, .(X, Y)], proj4string = CRS(utm), data = DT[, .(ID)] ) build_polys(spPts = pts, hrType = 'mcp', hrParams = list(percent = 95))
#> Object of class "SpatialPolygonsDataFrame" (package sp): #> #> Number of SpatialPolygons: 10 #> #> Variables measured: #> id area #> A A 145142204 #> B B 10614922 #> C C 110112310 #> D D 11667275 #> E E 62373195 #> F F 93349803 #> ... #>