Title: | Group Animal Relocation Data by Spatial and Temporal Relationship |
---|---|
Description: | Detects spatial and temporal groups in GPS relocations (Robitaille et al. (2019) <doi:10.1111/2041-210X.13215>). It can be used to convert GPS relocations to gambit-of-the-group format to build proximity-based social networks In addition, the randomizations function provides data-stream randomization methods suitable for GPS data. |
Authors: | Alec L. Robitaille [aut, cre] |
Maintainer: | Alec L. Robitaille <[email protected]> |
License: | GPL-3 | file LICENSE |
Version: | 0.2.3 |
Built: | 2024-08-29 22:55:36 UTC |
Source: | https://github.com/ropensci/spatsoc |
build_lines
generates a simple feature collection with LINESTRINGs from a
data.table
. The function accepts a data.table
with relocation data,
individual identifiers, a sorting column and a projection
. The relocation
data is transformed into LINESTRINGs for each individual and, optionally,
combination of columns listed in splitBy
. Relocation data should be in two
columns representing the X and Y coordinates.
build_lines( DT = NULL, projection = NULL, id = NULL, coords = NULL, sortBy = NULL, splitBy = NULL )
build_lines( DT = NULL, projection = NULL, id = NULL, coords = NULL, sortBy = NULL, splitBy = NULL )
DT |
input data.table |
projection |
numeric or character defining the coordinate reference
system to be passed to sf::st_crs. For example, either
|
id |
Character string of ID column name |
coords |
Character vector of X coordinate and Y coordinate column names |
sortBy |
Character string of date time column(s) to sort rows by. Must be a POSIXct. |
splitBy |
(optional) character string or vector of grouping column name(s) upon which the grouping will be calculated |
Please note, spatsoc has followed updates from R spatial, GDAL and PROJ for handling projections, see more at https://r-spatial.org/r/2020/03/17/wkt.html.
In addition, build_lines
previously used sp::SpatialLines but has been
updated to use sf::st_as_sf and sf::st_linestring according to the
R-spatial evolution, see more at
https://r-spatial.org/r/2022/04/12/evolution.html.
The projection
argument expects a numeric or character defining the
coordinate reference system.
For example, for UTM zone 36N (EPSG 32736), the projection argument is either
projection = 'EPSG:32736'
or projection = 32736
.
See details in sf::st_crs()
and https://spatialreference.org
for a list of EPSG codes.
The sortBy
argument is used to order the input DT
when creating
sf LINESTRINGs. It must a column in the input DT
of type
POSIXct to ensure the rows are sorted by date time.
The splitBy
argument offers further control building LINESTRINGs.
If in your input DT
, you have multiple temporal groups (e.g.: years) for
example, you can provide the name of the column which identifies them and
build LINESTRINGs for each individual in each year.
build_lines
is used by group_lines
for grouping overlapping
lines generated from relocations.
build_lines
returns an sf LINESTRING object with a line
for each individual (and optionally splitBy
combination).
Individuals (or combinations of individuals and splitBy
) with less than two
relocations are dropped since it requires at least two relocations to
build a line.
Other Build functions:
build_polys()
# 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')] # EPSG code for example data utm <- 32736 # Build lines for each individual lines <- build_lines(DT, projection = utm, id = 'ID', coords = c('X', 'Y'), sortBy = 'datetime') # Build lines for each individual by year DT[, yr := year(datetime)] lines <- build_lines(DT, projection = utm, id = 'ID', coords = c('X', 'Y'), sortBy = 'datetime', splitBy = 'yr')
# 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')] # EPSG code for example data utm <- 32736 # Build lines for each individual lines <- build_lines(DT, projection = utm, id = 'ID', coords = c('X', 'Y'), sortBy = 'datetime') # Build lines for each individual by year DT[, yr := year(datetime)] lines <- build_lines(DT, projection = utm, id = 'ID', coords = c('X', 'Y'), sortBy = 'datetime', splitBy = 'yr')
build_polys
generates a simple feature collection with POLYGONs from a
data.table
. The function accepts a data.table
with
relocation data, individual identifiers, a projection,
home range type and parameters. The relocation
data is transformed into POLYGONs using either adehabitatHR::mcp or
adehabitatHR::kernelUD for each individual and, optionally,
combination of columns listed in 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 )
build_polys( DT = NULL, projection = NULL, hrType = NULL, hrParams = NULL, id = NULL, coords = NULL, splitBy = NULL, spPts = NULL )
DT |
input data.table |
projection |
numeric or character defining the coordinate reference
system to be passed to sf::st_crs. For example, either
|
hrType |
type of HR estimation, either 'mcp' or 'kernel' |
hrParams |
a named list of parameters for |
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, as specified by adehabitatHR::mcp or adehabitatHR::kernelUD |
group_polys uses build_polys
for grouping overlapping
polygons created from relocations.
Please note, spatsoc has followed updates from R spatial, GDAL and PROJ for handling projections, see more below and details at https://r-spatial.org/r/2020/03/17/wkt.html.
In addition, build_polys
previously used sp::SpatialPoints but has been
updated to use sf::st_as_sf according to the R-spatial evolution, see more
at https://r-spatial.org/r/2022/04/12/evolution.html.
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 or numeric
defining the coordinate reference system to be passed to sf::st_crs.
For example, for UTM zone 36S (EPSG 32736), the projection
argument is projection = "EPSG:32736"
or projection = 32736
.
See https://spatialreference.org
for a list of EPSG codes.
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
POLYGONs. 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 POLYGONs
for each individual in each year.
build_polys
returns a simple feature collection with POLYGONs
for each individual (and optionally splitBy
combination).
An error is returned when hrParams
do not match the arguments
of the respective hrType
adehabitatHR
function.
Other Build functions:
build_lines()
# 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')] # EPSG code for example data utm <- 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')) # Build polygons for each individual by year DT[, yr := year(datetime)] build_polys(DT, projection = utm, hrType = 'mcp', hrParams = list(percent = 95), id = 'ID', coords = c('X', 'Y'), splitBy = 'yr')
# 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')] # EPSG code for example data utm <- 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')) # Build polygons for each individual by year DT[, yr := year(datetime)] build_polys(DT, projection = utm, hrType = 'mcp', hrParams = list(percent = 95), id = 'ID', coords = c('X', 'Y'), splitBy = 'yr')
A dataset containing the GPS relocations of 10 individuals in winter 2016-2017.
A data.table with 14297 rows and 5 variables:
individual identifier
X coordinate of the relocation (UTM 36N)
Y coordinate of the relocation (UTM 36N)
character string representing the date time
sub population within the individuals
# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc"))
# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc"))
Generate a dyad ID for edge list generated by edge_nn
or
edge_dist
.
dyad_id(DT = NULL, id1 = NULL, id2 = NULL)
dyad_id(DT = NULL, id1 = NULL, id2 = NULL)
DT |
input data.table with columns id1 and id2, as generated by
|
id1 |
ID1 column name generated by |
id2 |
ID2 column name generated by |
An undirected edge identifier between, for example individuals A and B will be A-B (and reverse B and A will be A-B). Internally sorts and pastes id columns.
More details in the edge and dyad vignette (in progress).
dyad_id
returns the input data.table
with appended "dyadID"
column
# 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')] # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '20 minutes') # Edge list generation edges <- edge_dist( DT, threshold = 100, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', returnDist = TRUE, fillNA = TRUE ) # Generate dyad IDs dyad_id(edges, 'ID1', 'ID2')
# 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')] # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '20 minutes') # Edge list generation edges <- edge_dist( DT, threshold = 100, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', returnDist = TRUE, fillNA = TRUE ) # Generate dyad IDs dyad_id(edges, 'ID1', 'ID2')
edge_dist
returns edge lists defined by a spatial distance within the
user defined threshold. The function accepts a data.table
with
relocation data, individual identifiers and a threshold argument. The
threshold argument is used to specify the criteria for distance between
points which defines a group. Relocation data should be in two columns
representing the X and Y coordinates.
edge_dist( DT = NULL, threshold, id = NULL, coords = NULL, timegroup, splitBy = NULL, returnDist = FALSE, fillNA = TRUE )
edge_dist( DT = NULL, threshold, id = NULL, coords = NULL, timegroup, splitBy = NULL, returnDist = FALSE, fillNA = TRUE )
DT |
input data.table |
threshold |
distance for grouping points, in the units of the coordinates |
id |
Character string of ID column name |
coords |
Character vector of X coordinate and Y coordinate column names |
timegroup |
timegroup field in the DT within which the grouping will be calculated |
splitBy |
(optional) character string or vector of grouping column name(s) upon which the grouping will be calculated |
returnDist |
boolean indicating if the distance between individuals should be returned. If FALSE (default), only ID1, ID2 columns (and timegroup, splitBy columns if provided) are returned. If TRUE, another column "distance" is returned indicating the distance between ID1 and ID2. |
fillNA |
boolean indicating if NAs should be returned for individuals that were not within the threshold distance of any other. If TRUE, NAs are returned. If FALSE, only edges between individuals within the threshold distance are returned. |
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
timegroup
(and optional splitBy
)
arguments expect the names of a column in DT
which correspond to the
individual identifier, X and Y coordinates, timegroup (generated by
group_times
) and additional grouping columns.
If provided, the threshold
must be provided in the units of the coordinates and must be larger than 0.
If the threshold
is NULL, the distance to all other individuals will be returned. The coordinates must be planar
coordinates (e.g.: UTM). In the case of UTM, a threshold
= 50 would
indicate a 50m distance threshold.
The timegroup
argument is required to define the temporal groups
within which edges are calculated. The intended framework is to group rows
temporally with group_times
then spatially with edge_dist
.
If you have already calculated temporal groups without
group_times
, you can pass this column to the timegroup
argument. Note that the expectation is that each individual will be observed
only once per timegroup. Caution that accidentally including huge numbers of
rows within timegroups can overload your machine since all pairwise distances
are calculated within each timegroup.
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
. edge_dist
will only consider rows within each
splitBy
subgroup.
edge_dist
returns a data.table
with columns ID1, ID2,
timegroup (if supplied) and any columns provided in splitBy. If
'returnDist' is TRUE, column 'distance' is returned indicating the distance
between ID1 and ID2.
The ID1 and ID2 columns represent the edges defined by the spatial (and
temporal with group_times
) thresholds.
Other Edge-list generation:
edge_nn()
# 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')] # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '20 minutes') # Edge list generation edges <- edge_dist( DT, threshold = 100, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', returnDist = TRUE, fillNA = TRUE )
# 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')] # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '20 minutes') # Edge list generation edges <- edge_dist( DT, threshold = 100, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', returnDist = TRUE, fillNA = TRUE )
edge_nn
returns edge lists defined by the nearest neighbour. The
function accepts a data.table
with relocation data, individual
identifiers and a threshold argument. The threshold argument is used to
specify the criteria for distance between points which defines a group.
Relocation data should be in two columns representing the X and Y
coordinates.
edge_nn( DT = NULL, id = NULL, coords = NULL, timegroup, splitBy = NULL, threshold = NULL, returnDist = FALSE )
edge_nn( DT = NULL, id = NULL, coords = NULL, timegroup, splitBy = NULL, threshold = NULL, returnDist = FALSE )
DT |
input data.table |
id |
Character string of ID column name |
coords |
Character vector of X coordinate and Y coordinate column names |
timegroup |
timegroup field in the DT within which the grouping will be calculated |
splitBy |
(optional) character string or vector of grouping column name(s) upon which the grouping will be calculated |
threshold |
(optional) spatial distance threshold to set maximum distance between an individual and their neighbour. |
returnDist |
boolean indicating if the distance between individuals should be returned. If FALSE (default), only ID, NN columns (and timegroup, splitBy columns if provided) are returned. If TRUE, another column "distance" is returned indicating the distance between ID and NN. |
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
, timegroup
(and optional splitBy
)
arguments expect the names of a column in DT
which correspond to the
individual identifier, X and Y coordinates, timegroup (generated by
group_times
) and additional grouping columns.
The threshold
must be provided in the units of the coordinates. The
threshold
must be larger than 0. The coordinates must be planar
coordinates (e.g.: UTM). In the case of UTM, a threshold
= 50 would
indicate a 50m distance threshold.
The timegroup
argument is required to define the temporal groups
within which edge nearest neighbours are calculated. The intended framework
is to group rows temporally with group_times
then spatially
with edge_nn
. If you have already calculated temporal groups without
group_times
, you can pass this column to the timegroup
argument. Note that the expectation is that each individual will be observed
only once per timegroup. Caution that accidentally including huge numbers of
rows within timegroups can overload your machine since all pairwise distances
are calculated within each timegroup.
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
. edge_nn
will only consider rows within each
splitBy
subgroup.
edge_nn
returns a data.table
with three columns:
timegroup, ID and NN. If 'returnDist' is TRUE, column 'distance' is
returned indicating the distance between ID and NN.
The ID and NN columns represent the edges defined by the nearest neighbours
(and temporal thresholds with group_times
).
If an individual was alone in a timegroup or splitBy, or did not have any neighbours within the threshold distance, they are assigned NA for nearest neighbour.
Other Edge-list generation:
edge_dist()
# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc")) # Select only individuals A, B, C for this example DT <- DT[ID %in% c('A', 'B', 'C')] # Cast the character column to POSIXct DT[, datetime := as.POSIXct(datetime, tz = 'UTC')] # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '20 minutes') # Edge list generation edges <- edge_nn(DT, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Edge list generation using maximum distance threshold edges <- edge_nn(DT, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', threshold = 100) # Edge list generation, returning distance between nearest neighbours edge_nn(DT, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', threshold = 100, returnDist = TRUE)
# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc")) # Select only individuals A, B, C for this example DT <- DT[ID %in% c('A', 'B', 'C')] # Cast the character column to POSIXct DT[, datetime := as.POSIXct(datetime, tz = 'UTC')] # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '20 minutes') # Edge list generation edges <- edge_nn(DT, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Edge list generation using maximum distance threshold edges <- edge_nn(DT, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', threshold = 100) # Edge list generation, returning distance between nearest neighbours edge_nn(DT, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', threshold = 100, returnDist = TRUE)
get_gbi
generates a group by individual matrix. The function accepts a
data.table
with individual identifiers and a group column. The group
by individual matrix can then be used to build a network using
asnipe::get_network
.
get_gbi(DT = NULL, group = "group", id = NULL)
get_gbi(DT = NULL, group = "group", id = NULL)
DT |
input data.table |
group |
Character string of group column (generated from one of spatsoc's spatial grouping functions) |
id |
Character string of ID column name |
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 group
argument expects the name of a column which corresponds to
an integer group identifier (generated by spatsoc
's grouping
functions).
The id
argument expects the name of a column which corresponds to the
individual identifier.
get_gbi
returns a group by individual matrix (columns
represent individuals and rows represent groups).
Note that get_gbi
is identical in function for turning the outputs
of spatsoc
into social networks as
asnipe::get_group_by_individual
but is more efficient thanks to
data.table::dcast
.
group_pts
group_lines
group_polys
Other Social network tools:
randomizations()
# 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')] DT[, yr := year(datetime)] # 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'), splitBy = 'yr') gbiMtrx <- get_gbi(DT = DT, group = 'group', id = 'ID')
# 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')] DT[, yr := year(datetime)] # 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'), splitBy = 'yr') gbiMtrx <- get_gbi(DT = DT, group = 'group', id = 'ID')
group_lines
groups rows into spatial groups by generating LINESTRINGs and
grouping based on spatial intersection. The function accepts a data.table
with relocation data, individual identifiers and a distance threshold. The
relocation data is transformed into sf LINESTRINGs using build_lines and
intersecting LINESTRINGs are grouped. The threshold argument is used to
specify the distance criteria for grouping. Relocation data should be in two
columns representing the X and Y coordinates.
group_lines( DT = NULL, threshold = NULL, projection = NULL, id = NULL, coords = NULL, timegroup = NULL, sortBy = NULL, splitBy = NULL, sfLines = NULL )
group_lines( DT = NULL, threshold = NULL, projection = NULL, id = NULL, coords = NULL, timegroup = NULL, sortBy = NULL, splitBy = NULL, sfLines = NULL )
DT |
input data.table |
threshold |
The width of the buffer around the lines in the units of the
projection. Use |
projection |
numeric or character defining the coordinate reference
system to be passed to sf::st_crs. For example, either
|
id |
Character string of ID column name |
coords |
Character vector of X coordinate and Y coordinate column names |
timegroup |
timegroup field in the DT within which the grouping will be calculated |
sortBy |
Character string of date time column(s) to sort rows by. Must be a POSIXct. |
splitBy |
(optional) character string or vector of grouping column name(s) upon which the grouping will be calculated |
sfLines |
Alternatively to providing a DT, provide a simple feature LINESTRING object generated with the sf package. The id argument is required to provide the identifier matching each LINESTRING. If an sfLines object is provided, groups cannot be calculated by timegroup or splitBy. |
Please note, spatsoc has followed updates from R spatial, GDAL and PROJ for handling projections, see more at https://r-spatial.org/r/2020/03/17/wkt.html.
In addition, group_lines
(and build_lines) previously used
sp::SpatialLines, rgeos::gIntersects, rgeos::gBuffer but have been
updated to use sf::st_as_sf, sf::st_linestring, sf::st_intersects, and
sf::st_buffer according to the R-spatial evolution, see more at
https://r-spatial.org/r/2022/04/12/evolution.html.
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
, sortBy
(and optional timegroup
and splitBy
) arguments expect the names of respective columns in
DT
which correspond to the individual identifier, X and Y coordinates,
sorting, timegroup (generated by group_times) and additional grouping
columns.
The projection
argument expects a numeric or character defining the
coordinate reference system. For example, for UTM zone 36N (EPSG 32736), the
projection argument is either projection = 'EPSG:32736'
or projection = 32736
. See details in sf::st_crs()
and
https://spatialreference.org for a list of EPSG codes.
The sortBy
argument is used to order the input DT
when creating sf
LINESTRINGs. It must a column in the input DT
of type POSIXct to ensure the
rows are sorted by date time.
The threshold
must be provided in the units of the coordinates. The
threshold
can be equal to 0 if strict overlap is intended, otherwise it
should be some value greater than 0. The coordinates must be planar
coordinates (e.g.: UTM). In the case of UTM, a threshold = 50
would
indicate a 50m distance threshold.
The timegroup
argument is optional, but recommended to pair with
group_times. The intended framework is to group rows temporally with
group_times then spatially with group_lines (or group_pts,
group_polys). With group_lines, pick a relevant group_times threshold
such as '1 day'
or '7 days'
which is informed by your study species,
system or question.
The splitBy
argument offers further control building LINESTRINGs. If in
your input DT
, you have multiple temporal groups (e.g.: years) for example,
you can provide the name of the column which identifies them and build
LINESTRINGs for each individual in each year. The grouping performed by
group_lines will only consider rows within each splitBy
subgroup.
group_lines
returns the input DT
appended with a "group"
column.
This column represents the spatial (and if timegroup
was provided -
spatiotemporal) group calculated by intersecting lines. 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.
A message is returned when a column named "group" already exists in the
input DT
, because it will be overwritten.
Other Spatial grouping:
group_polys()
,
group_pts()
# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc")) # Subset only individuals A, B, and C DT <- DT[ID %in% c('A', 'B', 'C')] # Cast the character column to POSIXct DT[, datetime := as.POSIXct(datetime, tz = 'UTC')] # EPSG code for example data utm <- 32736 group_lines(DT, threshold = 50, projection = utm, sortBy = 'datetime', id = 'ID', coords = c('X', 'Y')) ## Daily movement tracks # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '1 day') # Subset only first 50 days DT <- DT[timegroup < 25] # Spatial grouping group_lines(DT, threshold = 50, projection = utm, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', sortBy = 'datetime') ## Daily movement tracks by population group_lines(DT, threshold = 50, projection = utm, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', sortBy = 'datetime', splitBy = 'population')
# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc")) # Subset only individuals A, B, and C DT <- DT[ID %in% c('A', 'B', 'C')] # Cast the character column to POSIXct DT[, datetime := as.POSIXct(datetime, tz = 'UTC')] # EPSG code for example data utm <- 32736 group_lines(DT, threshold = 50, projection = utm, sortBy = 'datetime', id = 'ID', coords = c('X', 'Y')) ## Daily movement tracks # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '1 day') # Subset only first 50 days DT <- DT[timegroup < 25] # Spatial grouping group_lines(DT, threshold = 50, projection = utm, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', sortBy = 'datetime') ## Daily movement tracks by population group_lines(DT, threshold = 50, projection = utm, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', sortBy = 'datetime', splitBy = 'population')
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 POLYGONs using build_polys()
with adehabitatHR::mcp or
adehabitatHR::kernelUD. If the area
argument is FALSE
, group_polys
returns grouping calculated by spatial overlap. If the area
argument is
TRUE
, group_polys
returns the area area and proportion of overlap.
Relocation data should be in two columns representing the X and Y
coordinates.
group_polys( DT = NULL, area = NULL, hrType = NULL, hrParams = NULL, projection = NULL, id = NULL, coords = NULL, splitBy = NULL, sfPolys = NULL )
group_polys( DT = NULL, area = NULL, hrType = NULL, hrParams = NULL, projection = NULL, id = NULL, coords = NULL, splitBy = NULL, sfPolys = NULL )
DT |
input data.table |
area |
boolean indicating either overlap group (when |
hrType |
type of HR estimation, either 'mcp' or 'kernel' |
hrParams |
a named list of parameters for |
projection |
numeric or character defining the coordinate reference
system to be passed to sf::st_crs. For example, either
|
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 |
sfPolys |
Alternatively, provide solely a simple features object with POLYGONs or MULTIPOLYGONs. If sfPolys are provided, id is required and splitBy cannot be used. |
Please note, spatsoc has followed updates from R spatial, GDAL and PROJ for handling projections, see more below and details at https://r-spatial.org/r/2020/03/17/wkt.html.
In addition, group_polys
previously used rgeos::gIntersection,
rgeos::gIntersects and rgeos::gArea but has been
updated to use sf::st_intersects, sf::st_intersection and sf::st_area
according to the R-spatial evolution, see more
at https://r-spatial.org/r/2022/04/12/evolution.html.
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 or numeric
defining the coordinate reference system to be passed to sf::st_crs.
For example, for UTM zone 36S (EPSG 32736), the projection
argument is projection = "EPSG:32736"
or projection = 32736
.
See https://spatialreference.org
for a list of EPSG codes.
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.
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.
Along with changes to follow the R-spatial evolution, group_polys
also
now returns area and proportion of overlap with units explicitly specified
through the units
package.
Other Spatial grouping:
group_lines()
,
group_pts()
# 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')] # EPSG code for example data utm <- 32736 group_polys(DT, area = FALSE, hrType = 'mcp', hrParams = list(percent = 95), projection = utm, id = 'ID', coords = c('X', 'Y')) areaDT <- group_polys(DT, area = TRUE, hrType = 'mcp', hrParams = list(percent = 95), projection = utm, id = 'ID', coords = c('X', 'Y')) print(areaDT)
# 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')] # EPSG code for example data utm <- 32736 group_polys(DT, area = FALSE, hrType = 'mcp', hrParams = list(percent = 95), projection = utm, id = 'ID', coords = c('X', 'Y')) areaDT <- group_polys(DT, area = TRUE, hrType = 'mcp', hrParams = list(percent = 95), projection = utm, id = 'ID', coords = c('X', 'Y')) print(areaDT)
group_pts
groups rows into spatial groups. The function accepts a
data.table
with relocation data, individual identifiers and a
threshold argument. The threshold argument is used to specify the criteria
for distance between points which defines a group. Relocation data should be
in two columns representing the X and Y coordinates.
group_pts( DT = NULL, threshold = NULL, id = NULL, coords = NULL, timegroup, splitBy = NULL )
group_pts( DT = NULL, threshold = NULL, id = NULL, coords = NULL, timegroup, splitBy = NULL )
DT |
input data.table |
threshold |
distance for grouping points, in the units of the coordinates |
id |
Character string of ID column name |
coords |
Character vector of X coordinate and Y coordinate column names |
timegroup |
timegroup field in the DT within which the grouping will be calculated |
splitBy |
(optional) character string or vector of grouping column name(s) upon which the grouping will be calculated |
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
, timegroup
(and optional splitBy
)
arguments expect the names of a column in DT
which correspond to the
individual identifier, X and Y coordinates, timegroup (typically generated by
group_times
) and additional grouping columns.
The threshold
must be provided in the units of the coordinates. The
threshold
must be larger than 0. The coordinates must be planar
coordinates (e.g.: UTM). In the case of UTM, a threshold
= 50 would
indicate a 50m distance threshold.
The timegroup
argument is required to define the temporal groups
within which spatial groups are calculated. The intended framework is to
group rows temporally with group_times
then spatially with
group_pts
(or group_lines
, group_polys
).
If you have already calculated temporal groups without
group_times
, you can pass this column to the timegroup
argument. Note that the expectation is that each individual will be observed
only once per timegroup. Caution that accidentally including huge numbers of
rows within timegroups can overload your machine since all pairwise distances
are calculated within each timegroup.
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_pts
will only consider
rows within each splitBy
subgroup.
group_pts
returns the input DT
appended with a
group
column.
This column represents the spatialtemporal group. 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.
A message is returned when a column named group
already exists in
the input DT
, because it will be overwritten.
Other Spatial grouping:
group_lines()
,
group_polys()
# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc")) # Select only individuals A, B, C for this example DT <- DT[ID %in% c('A', 'B', 'C')] # Cast the character column to POSIXct DT[, datetime := as.POSIXct(datetime, tz = 'UTC')] # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '20 minutes') # Spatial grouping with timegroup group_pts(DT, threshold = 5, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Spatial grouping with timegroup and splitBy on population group_pts(DT, threshold = 5, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', splitBy = 'population')
# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc")) # Select only individuals A, B, C for this example DT <- DT[ID %in% c('A', 'B', 'C')] # Cast the character column to POSIXct DT[, datetime := as.POSIXct(datetime, tz = 'UTC')] # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '20 minutes') # Spatial grouping with timegroup group_pts(DT, threshold = 5, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Spatial grouping with timegroup and splitBy on population group_pts(DT, threshold = 5, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', splitBy = 'population')
group_times
groups rows into time groups. The function accepts date
time formatted data and a threshold argument. The threshold argument is used
to specify a time window within which rows are grouped.
group_times(DT = NULL, datetime = NULL, threshold = NULL)
group_times(DT = NULL, datetime = NULL, threshold = NULL)
DT |
input data.table |
datetime |
name of date time column(s). either 1 POSIXct or 2 IDate and ITime. e.g.: 'datetime' or c('idate', 'itime') |
threshold |
threshold for grouping times. e.g.: '2 hours', '10 minutes', etc. if not provided, times will be matched exactly. Note that provided threshold must be in the expected format: '## unit' |
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 datetime
argument expects the name of a column in DT
which
is of type POSIXct
or the name of two columns in DT
which are
of type IDate
and ITime
.
threshold
must be provided in units of minutes, hours or days. The
character string should start with an integer followed by a unit, separated
by a space. It is interpreted in terms of 24 hours which poses the following
limitations:
minutes, hours and days cannot be fractional
minutes must divide evenly into 60
minutes must not exceed 60
minutes, hours which are nearer to the next day, are grouped as such
hours must divide evenly into 24
multi-day blocks should divide into the range of days, else the blocks may not be the same length
In addition, the threshold
is considered a fixed window throughout the
time series and the rows are grouped to the nearest interval.
If threshold
is NULL, rows are grouped using the datetime
column directly.
group_times
returns the input DT
appended with a
timegroup
column and additional temporal grouping columns to help
investigate, troubleshoot and interpret the timegroup.
The actual value of timegroup
is arbitrary and represents the
identity of a given timegroup
which 1 or more individuals are
assigned to. If the data was reordered, the group may change, but the
contents of each group would not.
The temporal grouping columns added depend on the threshold
provided:
threshold
with unit minutes: "minutes" column added
identifying the nearest minute group for each row.
threshold
with unit hours: "hours" column added identifying the nearest hour group
for each row.
threshold
with unit days: "block" columns added
identifying the multiday block for each row.
A message is returned when any of these columns already exist in the input
DT
, because they will be overwritten.
group_pts
group_lines
group_polys
# 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')] group_times(DT, datetime = 'datetime', threshold = '5 minutes') group_times(DT, datetime = 'datetime', threshold = '2 hours') group_times(DT, datetime = 'datetime', threshold = '10 days')
# 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')] group_times(DT, datetime = 'datetime', threshold = '5 minutes') group_times(DT, datetime = 'datetime', threshold = '2 hours') group_times(DT, datetime = 'datetime', threshold = '10 days')
randomizations
performs data-stream social network randomization. The
function accepts a data.table
with relocation data, individual
identifiers and a randomization type
. The data.table
is
randomized either using step
or daily
between-individual
methods, or within-individual daily trajectory
method described by
Spiegel et al. (2016).
randomizations( DT = NULL, type = NULL, id = NULL, group = NULL, coords = NULL, datetime = NULL, splitBy = NULL, iterations = NULL )
randomizations( DT = NULL, type = NULL, id = NULL, group = NULL, coords = NULL, datetime = NULL, splitBy = NULL, iterations = NULL )
DT |
input data.table |
type |
one of 'daily', 'step' or 'trajectory' - see details |
id |
Character string of ID column name |
group |
generated from spatial grouping functions - see details |
coords |
Character vector of X coordinate and Y coordinate column names |
datetime |
field used for providing date time or time group - see details |
splitBy |
List of fields in DT to split the randomization process by |
iterations |
The number of iterations to randomize |
The DT
must be a data.table
. If your data is a
data.frame
, you can convert it by reference using
data.table::setDT
.
Three randomization type
s are provided:
step - randomizes identities of relocations between individuals within each time step.
daily - randomizes identities of relocations between individuals within each day.
trajectory - randomizes daily trajectories within individuals (Spiegel et al. 2016).
Depending on the type
, the datetime
must be a certain format:
step - datetime is integer group created by
group_times
daily - datetime is POSIXct
format
trajectory - datetime is POSIXct
format
The id
, datetime
, (and optional splitBy
) arguments
expect the names of respective columns in DT
which correspond to the
individual identifier, date time, and additional grouping columns. The
coords
argument is only required when the type
is "trajectory",
since the coordinates are required for recalculating spatial groups with
group_pts
, group_lines
or group_polys
.
Please note that if the data extends over multiple years, a column indicating
the year should be provided to the splitBy
argument. This will ensure
randomizations only occur within each year.
The group
argument is expected only when type
is 'step' or
'daily'.
For example, using data.table::year
:
DT[, yr := year(datetime)] randomizations(DT, type = 'step', id = 'ID', datetime = 'timegroup', splitBy = 'yr')
iterations
is set to 1 if not provided. Take caution with a large
value for iterations
with large input DT
.
randomizations
returns the random date time or random id along
with the original DT
, depending on the randomization type
.
The length of the returned data.table
is the original number of rows
multiplied by the number of iterations + 1. For example, 3 iterations will
return 4x - one observed and three randomized.
Two columns are always returned:
observed - if the rows represent the observed (TRUE/FALSE)
iteration - iteration of rows (where 0 is the observed)
In addition, depending on the randomization type, random ID or random date time columns are returned:
step - randomID
each time step
daily -
randomID
for each day and jul
indicating julian day
trajectory - a random date time ("random" prefixed to datetime
argument), observed jul
and randomJul
indicating the random
day relocations are swapped to.
Other Social network tools:
get_gbi()
# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc")) # Select only individuals A, B, C for this example DT <- DT[ID %in% c('A', 'B', 'C')] # Date time columns DT[, datetime := as.POSIXct(datetime)] DT[, yr := year(datetime)] # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '5 minutes') # Spatial grouping with timegroup group_pts(DT, threshold = 5, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Randomization: step randStep <- randomizations( DT, type = 'step', id = 'ID', group = 'group', datetime = 'timegroup', splitBy = 'yr', iterations = 2 ) # Randomization: daily randDaily <- randomizations( DT, type = 'daily', id = 'ID', group = 'group', datetime = 'datetime', splitBy = 'yr', iterations = 2 ) # Randomization: trajectory randTraj <- randomizations( DT, type = 'trajectory', id = 'ID', group = NULL, coords = c('X', 'Y'), datetime = 'datetime', splitBy = 'yr', iterations = 2 )
# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc")) # Select only individuals A, B, C for this example DT <- DT[ID %in% c('A', 'B', 'C')] # Date time columns DT[, datetime := as.POSIXct(datetime)] DT[, yr := year(datetime)] # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '5 minutes') # Spatial grouping with timegroup group_pts(DT, threshold = 5, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Randomization: step randStep <- randomizations( DT, type = 'step', id = 'ID', group = 'group', datetime = 'timegroup', splitBy = 'yr', iterations = 2 ) # Randomization: daily randDaily <- randomizations( DT, type = 'daily', id = 'ID', group = 'group', datetime = 'datetime', splitBy = 'yr', iterations = 2 ) # Randomization: trajectory randTraj <- randomizations( DT, type = 'trajectory', id = 'ID', group = NULL, coords = c('X', 'Y'), datetime = 'datetime', splitBy = 'yr', iterations = 2 )