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.
Usage
build_polys(
DT = NULL,
projection = NULL,
hrType = NULL,
hrParams = NULL,
id = NULL,
coords = NULL,
splitBy = NULL,
spPts = NULL
)Arguments
- DT
input data.table
- 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.- hrType
type of HR estimation, either 'mcp' or 'kernel'
- hrParams
a named list of parameters for
adehabitatHRfunctions- 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 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 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
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
# EPSG code for example data
utm <- 'EPSG:32736'
# 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'))
#> Registered S3 methods overwritten by 'adehabitatMA':
#> method from
#> print.SpatialPixelsDataFrame sp
#> print.SpatialPixels sp
#> Object of class "SpatialPolygonsDataFrame" (package sp):
#>
#> Number of SpatialPolygons: 10
#>
#> Variables measured:
#> id area
#> A A 192345367
#> B B 17316394
#> C C 151238156
#> D D 16127640
#> E E 75190273
#> F F 115041937
#> ...
#>
# 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
#> ...
#>