mt_time: Retrieve/replace timestamps or get the interval duration between locations

Description

mt_time() retrieve timestamps
mt_time(x) <- value and mt_set_time(x, value) replace timestamps with new values, set new column to define time or rename time column
mt_time_lags() returns time lags, i.e. duration interval between consecutive locations

Usage

mt_time(x)
mt_time(x) <- value
mt_set_time(x, value)
mt_time_lags(x, units)

Value

mt_time() returns a vector of timestamps, depending on the type of data these can be either POSIXct, dateor numeric

mt_time_lags() returns a vector of the time lags as numeric or units depending on the type of data.

Arguments

x: a move2 object
value: either a vector with new timestamps, the name of the new column to define time as a scalar character (this column must be present in the event table), or a scalar character to rename the time column.
units: Optional. Valid values are character, symbolic_units or units, for more details see the value argument of units::as_units. If no units are stated (default) the function flexibly determines the units to return. Fixing the units can be useful if specific return units are for example required for subsequent functions. This argument only takes effect if the initial return value already has units.

Details

Time lags are calculated as the time difference to the next location.

When calculating time lags between locations NA values are used for the transitions between tracks. This is because the interval between the last location of the previous track and first of the next track do not make sense.

Examples

Run this code

## in the simulated track, time is numeric, so the time lags are also numeric
x <- mt_sim_brownian_motion(1:3)
x |> mt_time()
x |> mt_time_lags()

## here the simulated track has timestamps, so the time lags have units
x <- mt_sim_brownian_motion(as.POSIXct((1:3) * 60^2, origin = "1970-1-1"), tracks = 1)
x |> mt_time()
x |> mt_time_lags()
x <- mt_sim_brownian_motion(as.Date(1:3, "1990-1-1"), tracks = 2)
x |> mt_time()
x |> mt_time_lags()

## units of the time lags can also be transformed, e.g. from days to hours
tl <- x |> mt_time_lags()
units::set_units(tl, h)

x <- mt_sim_brownian_motion(t = as.POSIXct(1:3, , origin = "1970-1-1"), tracks = 2)
## providing a vector with new timestamps
head(mt_time(x))
mt_time(x) <- 1:nrow(x)
head(mt_time(x))

## renaming the column defining time
mt_time_column(x)
mt_time(x) <- "my_new_time_name"
mt_time_column(x)

## setting a new column to define time
x$new_time <- as.POSIXct(1:6, origin = "2020-1-1")
mt_time(x) <- "new_time"
mt_time_column(x)
head(mt_time(x))