randomizations {spatsoc} | R Documentation |
Data-stream randomizations
Description
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).
Usage
randomizations(
DT = NULL,
type = NULL,
id = NULL,
group = NULL,
coords = NULL,
datetime = NULL,
splitBy = NULL,
iterations = NULL
)
Arguments
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 |
Details
The DT
must be a data.table
. If your data is a
data.frame
, you can convert it by reference using
data.table::setDT
.
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
.
Value
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 stepdaily -
randomID
for each day andjul
indicating julian day-
trajectory - a random date time ("random" prefixed to
datetime
argument), observedjul
andrandomJul
indicating the random day relocations are swapped to.
References
See Also
Other Social network tools:
get_gbi()
Examples
# 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
)