Skip to contents

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 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 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://www.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

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

# 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 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
#> ...
#>