Skip to contents

Retrieve/replace timestamps or get the interval duration between locations

Source: R/mt_time.R
mt_time.Rd

  • 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)

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.

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. Each element is the timelag to the next location. The last value for each track will be NA.

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.

See also

Other track-measures: mt_azimuth(), mt_distance()

Examples

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

## 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()
#> [1] "1970-01-01 01:00:00 UTC" "1970-01-01 02:00:00 UTC"
#> [3] "1970-01-01 03:00:00 UTC"
x |> mt_time_lags()
#> Units: [h]
#> [1]  1  1 NA
x <- mt_sim_brownian_motion(as.Date(1:3, "1990-1-1"), tracks = 2)
x |> mt_time()
#> [1] "1990-01-02" "1990-01-03" "1990-01-04" "1990-01-02" "1990-01-03"
#> [6] "1990-01-04"
x |> mt_time_lags()
#> Units: [d]
#> [1]  1  1 NA  1  1 NA

## 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)
#> Units: [h]
#> [1] 24 24 NA 24 24 NA

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))
#> [1] "1970-01-01 00:00:01 UTC" "1970-01-01 00:00:02 UTC"
#> [3] "1970-01-01 00:00:03 UTC" "1970-01-01 00:00:01 UTC"
#> [5] "1970-01-01 00:00:02 UTC" "1970-01-01 00:00:03 UTC"
mt_time(x) <- 1:nrow(x)
head(mt_time(x))
#> [1] 1 2 3 4 5 6

## renaming the column defining time
mt_time_column(x)
#> [1] "time"
mt_time(x) <- "my_new_time_name"
mt_time_column(x)
#> [1] "my_new_time_name"

## 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)
#> [1] "new_time"
head(mt_time(x))
#> [1] "2020-01-01 00:00:01 UTC" "2020-01-01 00:00:02 UTC"
#> [3] "2020-01-01 00:00:03 UTC" "2020-01-01 00:00:04 UTC"
#> [5] "2020-01-01 00:00:05 UTC" "2020-01-01 00:00:06 UTC"