,
Quinn Webber [aut] ,
Eric Vander Wal [aut] | 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] ,
Quinn Webber [aut] ,
Eric Vander Wal [aut] |
| Maintainer: | Alec L. Robitaille <[email protected]> |
| License: | GPL-3 | file LICENSE |
| Version: | 0.2.7 |
| Built: | 2024-11-01 15:16:31 UTC |
| Source: | https://github.com/ropensci/spatsoc |
build_lines generates a simple feature collection with LINESTRINGs from a
data.table. The function expects 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. Note: the order is assumed X followed by Y 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 expects 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. Note: the order is assumed X followed by Y 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')
centroid_dyad calculates the centroid (mean location) of a dyad in
each observation identified by edge_nn or edge_dist. The
function accepts an edge list generated by edge_nn or edge_dist
and a data.table with relocation data appended with a timegroup
column from group_times. It is recommended to use the argument
fillNA = FALSE for edge_dist when using centroid_dyad to
avoid unnecessarily merging additional rows. Relocation data should be in two
columns representing the X and Y coordinates.
centroid_dyad( edges = NULL, DT = NULL, id = NULL, coords = NULL, timegroup = "timegroup", na.rm = FALSE )centroid_dyad( edges = NULL, DT = NULL, id = NULL, coords = NULL, timegroup = "timegroup", na.rm = FALSE )
edges |
edge list generated generated by |
DT |
input data.table with timegroup column generated with
|
id |
character string of ID column name |
coords |
character vector of X coordinate and Y coordinate column names. Note: the order is assumed X followed by Y column names. |
timegroup |
timegroup field in the DT within which the grouping will be calculated |
na.rm |
if NAs should be removed in calculating mean location, see
|
The edges and DT must be data.table. If your data is a
data.frame, you can convert it by reference using
data.table::setDT or by reassigning using
data.table::data.table.
The edges and DT are internally merged in this function using
the columns id, dyadID and timegroup. This function
expects a dyadID present, generated with the dyad_id function.
The dyadID and timegroup arguments expect the names of a column
in edges which correspond to the dyadID and timegroup columns. The
id and timegroup arguments expect the names of a column in
DT which correspond to the X and Y coordinates and group columns. The
na.rm argument is passed to the rowMeans function to control if
NA values are removed before calculation.
centroid_dyad returns the input edges appended with
centroid columns for the X and Y coordinate columns.
These columns represents the centroid coordinate columns for the dyad. The naming of these columns will correspond to the provided coordinate column names prefixed with "centroid_".
Note: due to the merge required within this function, the output needs to be
reassigned unlike some other spatsoc functions like dyad_id
and group_pts.
A message is returned when centroid columns are already exists in
the input edges, because they will be overwritten.
dyad_id edge_dist edge_nn group_pts
Other Centroid functions:
centroid_fusion(),
centroid_group()
# 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 = FALSE ) # Generate dyad id dyad_id(edges, id1 = 'ID1', id2 = 'ID2') # Calculate dyad centroid centroids <- centroid_dyad( edges, DT, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', na.rm = TRUE ) print(centroids)# 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 = FALSE ) # Generate dyad id dyad_id(edges, id1 = 'ID1', id2 = 'ID2') # Calculate dyad centroid centroids <- centroid_dyad( edges, DT, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', na.rm = TRUE ) print(centroids)
centroid_fusion calculates the centroid (mean location) of each
timestep in fusion events. The function accepts an edge list of fusion events
identified by fusion_id from edge lists generated with
edge_dist and a data.table with relocation data appended with a
timegroup column from group_times. It is recommended to use the
argument fillNA = FALSE for edge_dist when using
centroid_fusion to avoid unnecessarily merging additional rows.
Relocation data should be in two columns representing the X and Y
coordinates.
centroid_fusion( edges = NULL, DT = NULL, id = NULL, coords = NULL, timegroup = "timegroup", na.rm = FALSE )centroid_fusion( edges = NULL, DT = NULL, id = NULL, coords = NULL, timegroup = "timegroup", na.rm = FALSE )
edges |
edge list generated generated by |
DT |
input data.table with timegroup column generated with
|
id |
character string of ID column name |
coords |
character vector of X coordinate and Y coordinate column names. Note: the order is assumed X followed by Y column names. |
timegroup |
timegroup field in the DT within which the grouping will be calculated |
na.rm |
if NAs should be removed in calculating mean location, see
|
The edges and DT must be data.table. If your data is a
data.frame, you can convert it by reference using
data.table::setDT or by reassigning using
data.table::data.table.
The edges and DT are internally merged in this function using
the columns timegroup (from group_times) and ID1 and
ID2 (in edges, from dyad_id) and id (in
DT). This function expects a fusionID present, generated with
the fusion_id function. The timegroup argument expects the
names of a column in edges which correspond to the timegroup column.
The id, coords and timegroup arguments expect the names
of a column in DT which correspond to the id, X and Y coordinates and
timegroup columns. The na.rm argument is passed to the rowMeans
function to control if NA values are removed before calculation.
centroid_fusion returns the input edges appended with
centroid columns for the X and Y coordinate columns.
These columns represents the centroid coordinate columns for each timestep in a fusion event. The naming of these columns will correspond to the provided coordinate column names prefixed with "centroid_".
Note: due to the merge required within this function, the output needs to
be reassigned unlike some other spatsoc functions like
fusion_id and group_pts.
A message is returned when centroid columns are already exists in the input
edges, because they will be overwritten.
Other Centroid functions:
centroid_dyad(),
centroid_group()
# 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 = FALSE ) # Generate dyad id dyad_id(edges, id1 = 'ID1', id2 = 'ID2') # Generate fusion id fusion_id(edges, threshold = 100) # Calculate fusion centroid centroids <- centroid_fusion( edges, DT, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', na.rm = TRUE ) print(centroids)# 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 = FALSE ) # Generate dyad id dyad_id(edges, id1 = 'ID1', id2 = 'ID2') # Generate fusion id fusion_id(edges, threshold = 100) # Calculate fusion centroid centroids <- centroid_fusion( edges, DT, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup', na.rm = TRUE ) print(centroids)
centroid_group calculates the centroid (mean location) of all
individuals in each spatiotemporal group identified by group_pts. The
function accepts a data.table with relocation data appended with a
group column from group_pts. Relocation data should be in two
columns representing the X and Y coordinates.
centroid_group(DT = NULL, coords = NULL, group = "group", na.rm = FALSE)centroid_group(DT = NULL, coords = NULL, group = "group", na.rm = FALSE)
DT |
input data.table with group column generated with |
coords |
character vector of X coordinate and Y coordinate column names. Note: the order is assumed X followed by Y column names. |
group |
Character string of group column |
na.rm |
if NAs should be removed in calculating mean location, see |
The DT must be a data.table. If your data is a
data.frame, you can convert it by reference using
data.table::setDT or by reassigning using
data.table::data.table.
The coords and group arguments expect the names of a column in
DT which correspond to the X and Y coordinates and group columns. The
na.rm argument is passed to the mean function to control if NA
values are removed before calculation.
centroid_group returns the input DT appended with
centroid columns for the X and Y coordinate columns.
These columns represents the centroid coordinate columns. The naming of these columns will correspond to the provided coordinate column names prefixed with "centroid_".
A message is returned when centroid columns are already exists in
the input DT, because they will be overwritten.
Other Centroid functions:
centroid_dyad(),
centroid_fusion()
# 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') # Spatial grouping with timegroup group_pts(DT, threshold = 5, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate group centroid centroid_group(DT, coords = c('X', 'Y'), group = 'group', na.rm = 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') # Spatial grouping with timegroup group_pts(DT, threshold = 5, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate group centroid centroid_group(DT, coords = c('X', 'Y'), group = 'group', na.rm = TRUE)
direction_group calculates the mean direction of all individuals in
each spatiotemporal group identified by group_pts. The function
accepts a data.table with relocation data appended with a
direction column from direction_step and a group column
from group_pts.
direction_group(DT, direction = "direction", group = "group")direction_group(DT, direction = "direction", group = "group")
DT |
input data.table with direction column generated by
|
direction |
character string of direction column name, default "direction" |
group |
character string of group column name, default "group" |
The DT must be a data.table. If your data is a
data.frame, you can convert it by reference using
data.table::setDT or by reassigning using
data.table::data.table.
The direction and group arguments expect the names of columns
in DT which correspond to the direction and group columns. The
direction column is expected in units of radians and the mean calculated with
CircStats::circ.mean().
direction_group returns the input DT appended with a
group_direction column representing the mean direction of
all individuals in each spatiotemporal group.
The mean direction is calculated using CircStats::circ.mean()
which expects units of radians.
A message is returned when the group_direction columns already
exists in the input DT, because it will be overwritten.
See examples of using mean group direction:
direction_step, group_pts,
CircStats::circ.mean()
Other Direction functions:
direction_polarization(),
direction_step(),
direction_to_leader()
# 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') # Spatial grouping with timegroup group_pts(DT, threshold = 50, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate direction at each step direction_step( DT = DT, id = 'ID', coords = c('X', 'Y'), projection = 32736 ) # Calculate group direction direction_group(DT)# 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') # Spatial grouping with timegroup group_pts(DT, threshold = 50, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate direction at each step direction_step( DT = DT, id = 'ID', coords = c('X', 'Y'), projection = 32736 ) # Calculate group direction direction_group(DT)
direction_polarization calculates the polarization of individual
directions in each spatiotemporal group identified by group_pts. The
function expects a data.table with relocation data appended with a
direction column from direction_step and a group column
from group_pts.
direction_polarization(DT, direction = "direction", group = "group")direction_polarization(DT, direction = "direction", group = "group")
DT |
input data.table with direction column generated by
|
direction |
character string of direction column name, default "direction" |
group |
character string of group column name, default "group" |
The DT must be a data.table. If your data is a
data.frame, you can convert it by reference using
data.table::setDT or by reassigning using
data.table::data.table.
The direction and group arguments expect the names of columns
in DT which correspond to the direction and group columns. The
direction column is expected in units of radians and the polarization is
calculated with CircStats::r.test().
direction_polarization returns the input DT appended
with a polarization column representing the direction polarization
of all individuals in each spatiotemporal group.
The direction polarization is calculated using CircStats::r.test()
which expects units of radians.
A message is returned when the polarization columns already
exists in the input DT, because it will be overwritten.
See examples of using polarization:
direction_step, group_pts,
CircStats::r.test()
Other Direction functions:
direction_group(),
direction_step(),
direction_to_leader()
# 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') # Spatial grouping with timegroup group_pts(DT, threshold = 50, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate direction at each step direction_step( DT = DT, id = 'ID', coords = c('X', 'Y'), projection = 32736 ) # Calculate polarization direction_polarization(DT)# 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') # Spatial grouping with timegroup group_pts(DT, threshold = 50, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate direction at each step direction_step( DT = DT, id = 'ID', coords = c('X', 'Y'), projection = 32736 ) # Calculate polarization direction_polarization(DT)
direction_step calculates the direction of movement steps in radians.
The function accepts a data.table with relocation data and individual
identifiers. Relocation data should be in two columns representing the X and
Y coordinates. Note the order of rows is not modified by this function and
therefore users must be cautious to set it explicitly. See example for one
approach to setting order of rows using a datetime field.
direction_step( DT = NULL, id = NULL, coords = NULL, projection = NULL, splitBy = NULL )direction_step( DT = NULL, id = NULL, coords = NULL, projection = NULL, splitBy = NULL )
DT |
input data.table |
id |
character string of ID column name |
coords |
character vector of X coordinate and Y coordinate column names. Note: the order is assumed X followed by Y column names. |
projection |
numeric or character defining the coordinate reference
system to be passed to sf::st_crs. For example, either
|
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 or by reassigning using
data.table::data.table.
The id, coords, and optional splitBy arguments expect
the names of a column 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 splitBy argument offers further control over grouping. If within
your DT, you have distinct sampling periods for each individual, you
can provide the column name(s) which identify them to splitBy. The
direction calculation by direction_step will only consider rows within
each id and splitBy subgroup.
direction_step returns the input DT appended with
a direction column with units set to radians using the units
package.
This column represents the azimuth between the sequence of points for
each individual computed using lwgeom::st_geod_azimuth. Note, the
order of points is not modified by this function and therefore it is
crucial the user sets the order of rows to their specific question
before using direction_step. In addition, the direction column
will include an NA value for the last point in each sequence of
points since there is no future point to calculate a direction to.
A message is returned when a direction column are already exists in
the input DT, because it will be overwritten.
amt::direction_abs(), geosphere::bearing()
Other Direction functions:
direction_group(),
direction_polarization(),
direction_to_leader()
# 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')] # Set order using data.table::setorder setorder(DT, datetime) # Calculate direction direction_step( DT = DT, id = 'ID', coords = c('X', 'Y'), projection = 32736 )# 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')] # Set order using data.table::setorder setorder(DT, datetime) # Calculate direction direction_step( DT = DT, id = 'ID', coords = c('X', 'Y'), projection = 32736 )
direction_to_centroid calculates the direction of each relocation to
the centroid of the spatiotemporal group identified by group_pts. The
function accepts a data.table with relocation data appended with a
group column from group_pts and centroid columns from
centroid_group. Relocation data should be in planar coordinates
provided in two columns representing the X and Y coordinates.
direction_to_centroid(DT = NULL, coords = NULL)direction_to_centroid(DT = NULL, coords = NULL)
DT |
input data.table with centroid columns generated by eg.
|
coords |
character vector of X coordinate and Y coordinate column names. Note: the order is assumed X followed by Y column names. |
The DT must be a data.table. If your data is a
data.frame, you can convert it by reference using
data.table::setDT or by reassigning using
data.table::data.table.
This function expects a group column present generated with the
group_pts function and centroid coordinate columns generated with the
centroid_group function. The coords and group arguments
expect the names of columns in DT which correspond to the X and Y
coordinates and group columns.
direction_to_centroid returns the input DT appended
with a direction_centroid column indicating the direction to group
centroid in radians. The direction is measured in radians in the range
of 0 to 2 * pi from the positive x-axis.
A message is returned when direction_centroid column already exist
in the input DT, because they will be overwritten.
See example of using direction to group centroid:
Other Distance functions:
distance_to_centroid(),
distance_to_leader()
# 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') # Spatial grouping with timegroup group_pts(DT, threshold = 5, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate group centroid centroid_group(DT, coords = c('X', 'Y'), group = 'group', na.rm = TRUE) # Calculate direction to group centroid direction_to_centroid(DT, coords = c('X', 'Y'))# 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') # Spatial grouping with timegroup group_pts(DT, threshold = 5, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate group centroid centroid_group(DT, coords = c('X', 'Y'), group = 'group', na.rm = TRUE) # Calculate direction to group centroid direction_to_centroid(DT, coords = c('X', 'Y'))
direction_to_leader calculates the direction to the leader of each
spatiotemporal group. The function accepts a data.table with
relocation data appended with a rank_position_group_direction column
indicating the ranked position along the group direction generated with
leader_direction_group(return_rank = TRUE). Relocation data should be
in planar coordinates provided in two columns representing the X and Y
coordinates.
direction_to_leader(DT = NULL, coords = NULL, group = "group")direction_to_leader(DT = NULL, coords = NULL, group = "group")
DT |
input data.table with 'rank_position_group_direction' column
generated by |
coords |
character vector of X coordinate and Y coordinate column names. Note: the order is assumed X followed by Y column names. |
group |
group column name, generated by |
The DT must be a data.table. If your data is a
data.frame, you can convert it by reference using
data.table::setDT or by reassigning using
data.table::data.table.
This function expects a rank_position_group_direction column
generated with leader_direction_group(return_rank = TRUE),
a group column generated with the
group_pts function. The coords and group arguments
expect the names of columns in DT which correspond to the X and Y
coordinates and group columns.
direction_to_leader returns the input DT appended with
a direction_leader column indicating the direction to the group leader.
A message is returned when the direction_leader column is already exist in the input DT
because it will be overwritten.
See examples of using direction to leader and position within group:
distance_to_leader, leader_direction_group, group_pts
Other Direction functions:
direction_group(),
direction_polarization(),
direction_step()
# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc")) # (Subset example data to reduce example run time) DT <- DT[year(datetime) == 2016] # 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 = 50, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate direction at each step direction_step( DT = DT, id = 'ID', coords = c('X', 'Y'), projection = 32736 ) # Calculate group centroid centroid_group(DT, coords = c('X', 'Y')) # Calculate group direction direction_group(DT) # Calculate leader in terms of position along group direction leader_direction_group( DT, coords = c('X', 'Y'), return_rank = TRUE ) # Calculate direction to leader direction_to_leader(DT, coords = c('X', 'Y'))# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc")) # (Subset example data to reduce example run time) DT <- DT[year(datetime) == 2016] # 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 = 50, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate direction at each step direction_step( DT = DT, id = 'ID', coords = c('X', 'Y'), projection = 32736 ) # Calculate group centroid centroid_group(DT, coords = c('X', 'Y')) # Calculate group direction direction_group(DT) # Calculate leader in terms of position along group direction leader_direction_group( DT, coords = c('X', 'Y'), return_rank = TRUE ) # Calculate direction to leader direction_to_leader(DT, coords = c('X', 'Y'))
distance_to_centroid calculates the distance of each relocation to the
centroid of the spatiotemporal group identified by group_pts. The
function accepts a data.table with relocation data appended with a
group column from group_pts and centroid columns from
centroid_group. Relocation data should be in planar coordinates
provided in two columns representing the X and Y coordinates.
distance_to_centroid( DT = NULL, coords = NULL, group = "group", return_rank = FALSE, ties.method = NULL )distance_to_centroid( DT = NULL, coords = NULL, group = "group", return_rank = FALSE, ties.method = NULL )
DT |
input data.table with centroid columns generated by eg.
|
coords |
character vector of X coordinate and Y coordinate column names. Note: the order is assumed X followed by Y column names. |
group |
group column name, generated by |
return_rank |
boolean if rank distance should also be returned, default FALSE |
ties.method |
The DT must be a data.table. If your data is a
data.frame, you can convert it by reference using
data.table::setDT or by reassigning using
data.table::data.table.
This function expects a group column present generated with the
group_pts function and centroid coordinate columns generated with the
centroid_group function. The coords and group arguments
expect the names of columns in DT which correspond to the X and Y
coordinates and group columns. The return_rank argument controls if
the rank of each individual's distance to the group centroid is also
returned. The ties.method argument is passed to
data.table::frank, see details at
?data.table::frank.
distance_to_centroid returns the input DT appended with
a distance_centroid column indicating the distance to group centroid
and, optionally, a rank_distance_centroid column indicating the
within group rank distance to group centroid (if return_rank =
TRUE).
A message is returned when distance_centroid and optional
rank_distance_centroid columns already exist in the input DT,
because they will be overwritten.
See examples of using distance to group centroid:
Other Distance functions:
direction_to_centroid(),
distance_to_leader()
# 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') # Spatial grouping with timegroup group_pts(DT, threshold = 5, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate group centroid centroid_group(DT, coords = c('X', 'Y'), group = 'group', na.rm = TRUE) # Calculate distance to group centroid distance_to_centroid( DT, coords = c('X', 'Y'), group = 'group', return_rank = 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') # Spatial grouping with timegroup group_pts(DT, threshold = 5, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate group centroid centroid_group(DT, coords = c('X', 'Y'), group = 'group', na.rm = TRUE) # Calculate distance to group centroid distance_to_centroid( DT, coords = c('X', 'Y'), group = 'group', return_rank = TRUE )
distance_to_leader calculates the distance to the leader of each
spatiotemporal group. The function accepts a data.table with
relocation data appended with a rank_position_group_direction column
indicating the ranked position along the group direction generated with
leader_direction_group(return_rank = TRUE). Relocation data should be
in planar coordinates provided in two columns representing the X and Y
coordinates.
distance_to_leader(DT = NULL, coords = NULL, group = "group")distance_to_leader(DT = NULL, coords = NULL, group = "group")
DT |
input data.table with 'rank_position_group_direction' column
generated by |
coords |
character vector of X coordinate and Y coordinate column names. Note: the order is assumed X followed by Y column names. |
group |
group column name, generated by |
The DT must be a data.table. If your data is a
data.frame, you can convert it by reference using
data.table::setDT or by reassigning using
data.table::data.table.
This function expects a rank_position_group_direction column
generated with leader_direction_group(return_rank = TRUE),
a group column generated with the
group_pts function. The coords and group arguments
expect the names of columns in DT which correspond to the X and Y
coordinates and group columns.
distance_to_leader returns the input DT appended with
a distance_leader column indicating the distance to the group leader.
A message is returned when the distance_leader column is already exist in the input DT
because it will be overwritten.
See examples of using distance to leader and position within group:
direction_to_leader, leader_direction_group, group_pts
Other Distance functions:
direction_to_centroid(),
distance_to_centroid()
# 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')] # (Subset example data to reduce example run time) DT <- DT[year(datetime) == 2016] # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '20 minutes') # Spatial grouping with timegroup group_pts(DT, threshold = 50, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate direction at each step direction_step( DT = DT, id = 'ID', coords = c('X', 'Y'), projection = 32736 ) # Calculate group centroid centroid_group(DT, coords = c('X', 'Y')) # Calculate group direction direction_group(DT) # Calculate leader in terms of position along group direction leader_direction_group( DT, coords = c('X', 'Y'), return_rank = TRUE ) # Calculate distance to leader distance_to_leader(DT, coords = c('X', 'Y'))# 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')] # (Subset example data to reduce example run time) DT <- DT[year(datetime) == 2016] # Temporal grouping group_times(DT, datetime = 'datetime', threshold = '20 minutes') # Spatial grouping with timegroup group_pts(DT, threshold = 50, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate direction at each step direction_step( DT = DT, id = 'ID', coords = c('X', 'Y'), projection = 32736 ) # Calculate group centroid centroid_group(DT, coords = c('X', 'Y')) # Calculate group direction direction_group(DT) # Calculate leader in terms of position along group direction leader_direction_group( DT, coords = c('X', 'Y'), return_rank = TRUE ) # Calculate distance to leader distance_to_leader(DT, coords = c('X', 'Y'))
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 expects 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. Note: the order is assumed X followed by Y 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 expects 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. Note: the order is assumed X followed by Y 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)
fusion_id identifies fusion events in distance based edge lists.
The function accepts a distance based edge list generated by
edge_dist, a threshold argument and arguments controlling how fusion
events are defined.
fusion_id( edges = NULL, threshold = 50, n_min_length = 0, n_max_missing = 0, allow_split = FALSE )fusion_id( edges = NULL, threshold = 50, n_min_length = 0, n_max_missing = 0, allow_split = FALSE )
edges |
distance based edge list generated by |
threshold |
spatial distance threshold in the units of the projection |
n_min_length |
minimum length of fusion events |
n_max_missing |
maximum number of missing observations within a fusion event |
allow_split |
boolean defining if a single observation can be greater than the threshold distance without initiating fission event |
The edges must be a data.table returned by the edge_dist
function. In addition, fusion_id requires a dyad ID set on the edge
list generated by dyad_id. If your data is a data.frame, you
can convert it by reference using
data.table::setDT.
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 50 m distance threshold.
The n_min_length argument defines the minimum number of successive
fixes that are required to establish a fusion event. The n_max_missing
argument defines the the maximum number of allowable missing observations for
the dyad within a fusion event. The allow_split argument defines if a
single observation can be greater than the threshold distance without
initiating fission event.
fusion_id returns the input edges appended with a
fusionID column.
This column represents the fusion event id. As with spatsoc's
grouping functions, the actual value of fusionID is arbitrary and
represents the identity of a given fusion event. If the data was reordered,
the fusionID may change, but the membership of each fusion event
would not.
A message is returned when a column named fusionID already exists in
the input edges, because it will be overwritten.
See examples of identifying fission-fusion events with spatiotemporal data:
# 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 ) dyad_id(edges, 'ID1', 'ID2') fusion_id( edges = edges, threshold = 100, n_min_length = 1, n_max_missing = 0, allow_split = FALSE )# 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 ) dyad_id(edges, 'ID1', 'ID2') fusion_id( edges = edges, threshold = 100, n_min_length = 1, n_max_missing = 0, allow_split = FALSE )
get_gbi generates a group by individual matrix. The function expects 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 expects 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. Note: the order is assumed X followed by Y 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 expects 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. Note: the order is assumed X followed by Y 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 expects 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. Note: the order is assumed X followed by Y 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 or by reassigning using
data.table::data.table.
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 expects 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')
Given the mean direction of a group of animals, leader_direction_group
shifts the coordinate system to a new origin at the group centroid and
rotates the coordinate system by the mean direction to return each
individual's position along the mean direction, representing leadership in
terms of the front-back position in each group's mean direction.
leader_direction_group( DT = NULL, group_direction = "group_direction", coords = NULL, group = "group", return_rank = FALSE, ties.method = "average" )leader_direction_group( DT = NULL, group_direction = "group_direction", coords = NULL, group = "group", return_rank = FALSE, ties.method = "average" )
DT |
input data.table with group direction columns generated by
|
group_direction |
group_direction column name generated using
|
coords |
character vector of X coordinate and Y coordinate column names. Note: the order is assumed X followed by Y column names. |
group |
group column name, generated by |
return_rank |
boolean if rank distance should also be returned, default FALSE |
ties.method |
The function accepts a data.table with relocation data appended with a
group_direction column from direction_group and group centroid
columns from centroid_group. Relocation data should be in two columns
representing the X and Y coordinates.
The DT must be a data.table. If your data is a
data.frame, you can convert it by reference using
data.table::setDT or by reassigning using
data.table::data.table.
The group_direction argument expects the names of columns in DT
which correspond to the mean group direction generated by
direction_group. The mean group direction column is expected in units
of radians. The coords arguments expects the names of columns in
DT which correspond to the X and Y coordinate columns. The
return_rank argument controls if the rank of each individual's
distance to the group centroid is also returned. If return_rank is
TRUE, the group argument is required to specify the group column
generated by group_pts. The ties.method argument is passed to
data.table::frank, see details at
?data.table::frank.
leader_direction_group returns the input DT appended
with a position_group_direction column indicating the position along
the group direction in the units of the projection and, optionally when
return_rank = TRUE, a rank_position_group_direction column
indicating the the ranked position along the group direction.
A message is returned when position_group_direction or
rank_position_group_direction columns already exist in the input
DT, because they will be overwritten.
See examples of measuring leadership along group direction (also called forefront index):
direction_group, centroid_group
# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc")) # (Subset example data to reduce example run time) DT <- DT[year(datetime) == 2016] # 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 = 50, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate direction at each step direction_step( DT = DT, id = 'ID', coords = c('X', 'Y'), projection = 32736 ) # Calculate group centroid centroid_group(DT, coords = c('X', 'Y')) # Calculate group direction direction_group(DT) # Calculate leader in terms of position along group direction leader_direction_group(DT, coords = c('X', 'Y'))# Load data.table library(data.table) # Read example data DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc")) # (Subset example data to reduce example run time) DT <- DT[year(datetime) == 2016] # 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 = 50, id = 'ID', coords = c('X', 'Y'), timegroup = 'timegroup') # Calculate direction at each step direction_step( DT = DT, id = 'ID', coords = c('X', 'Y'), projection = 32736 ) # Calculate group centroid centroid_group(DT, coords = c('X', 'Y')) # Calculate group direction direction_group(DT) # Calculate leader in terms of position along group direction leader_direction_group(DT, coords = c('X', 'Y'))
randomizations performs data-stream social network randomization. The
function expects 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. Note: the order is assumed X followed by Y 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 types 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 )