amt (version 0.0.7)

steps: Functions to create and work with steps

Description

step_lengths can be use to calculate step lengths of a track. direction_abs and direction_rel calculate the absolute and relative direction of steps. steps converts a track_xy* from a point representation to a step representation and automatically calculates step lengths and relative turning angles.

Usage

direction_abs(x, ...)
# S3 method for track_xy
direction_abs(x, full_circle = FALSE,
  zero_dir = "E", clockwise = FALSE, append_last = TRUE,
  lonlat = FALSE, ...)
direction_rel(x, ...)
# S3 method for track_xy
direction_rel(x, lonlat = FALSE, append_last = TRUE,
  zero_dir = "E", ...)
step_lengths(x, ...)
# S3 method for track_xy
step_lengths(x, lonlat = FALSE, append_last = TRUE,
  ...)
steps_by_burst(x, ...)
# S3 method for track_xyt
steps_by_burst(x, lonlat = FALSE, keep_cols = NULL,
  ...)
steps(x, ...)
# S3 method for track_xy
steps(x, lonlat = FALSE, keep_cols = NULL, ...)
# S3 method for track_xyt
steps(x, lonlat = FALSE, keep_cols = NULL,
  diff_time_units = "auto", ...)

Arguments

x

[track_xy, track_xyt] A track created with make_track.

...

Further arguments, none implemented

full_circle

[logical(1)=FALSE] If TRUE angles are returned between 0 and $2pi$, otherwise angles are between $-pi$ and $pi$.

zero_dir

[character(1)='E'] Indicating the zero direction. Must be either N, E, S, or W.

clockwise

[logical(1)=FALSE] Should angles be calculated clock or anti-clockwise?

append_last

[logical(1)=TRUE] If TRUE an NA is appended at the end of all angles.

lonlat

[logical(1)=TRUE] Should geographical or planar coordinates be used? If TRUE geographic distances are calculated.

keep_cols

[character(1)=NULL]{'start', 'end', 'both'} Should columns with attribute information be transfered to steps? If keep_cols = 'start' the attributes from the starting point are use, otherwise the columns from the end points are used.

diff_time_units

[character(1)='auto'] The unit for time differences, see ?difftime.

Value

[numeric] For step_lengths() and direction_* a numeric vector. [data.frame] For steps and steps_by_burst, containing the steps.

Details

step_lengths calculates the step lengths between points a long the path. The last value returned is NA, because no observed step is 'started' at the last point. If lonlat = TRUE, step_lengths() wraps raster::pointDistance().

Examples

# NOT RUN {
xy <- tibble(
  x = c(1, 4, 8, 8, 12, 8, 0, 0, 4, 2),
  y = c(0, 0, 0, 8, 12, 12, 12, 8, 4, 2))
trk <- make_track(xy, x, y)

# append last
direction_abs(trk, append_last = TRUE)
direction_abs(trk, append_last = FALSE)

# degrees
direction_abs(trk) %>% as_degree

# full circle or not: check
direction_abs(trk, full_circle = TRUE)
direction_abs(trk, full_circle = FALSE)
direction_abs(trk, full_circle = TRUE) %>% as_degree()
direction_abs(trk, full_circle = FALSE) %>% as_degree()

# direction of 0
direction_abs(trk, full_circle = TRUE, zero_dir = "N")
direction_abs(trk, full_circle = TRUE, zero_dir = "E")
direction_abs(trk, full_circle = TRUE, zero_dir = "S")
direction_abs(trk, full_circle = TRUE, zero_dir = "W")

# clockwise or not
direction_abs(trk, full_circle = TRUE, zero_dir = "N", clockwise = FALSE)
direction_abs(trk, full_circle = TRUE, zero_dir = "N", clockwise = TRUE)

# Bearing (i.e. azimuth): only for lon/lat
direction_abs(trk, full_circle = FALSE, zero_dir = "N", lonlat = FALSE, clockwise = TRUE)
direction_abs(trk, full_circle = FALSE, zero_dir = "N", lonlat = TRUE, clockwise = TRUE)

# How do results compare to other packages
# adehabitatLT
df <- adehabitatLT::as.ltraj(data.frame(x = xy$x, y = xy$y), typeII = FALSE, id = 1)
df[[1]]$abs.angle
amt::direction_abs(trk)

# bcpa
df <- bcpa::MakeTrack(xy$x, xy$y, lubridate::now() +  lubridate::hours(1:10))
bcpa::GetVT(df)$Phi
direction_abs(trk, full_circle = FALSE, append_last = FALSE)

# move
m <- move::move(xy$x, xy$y, lubridate::now() + lubridate::hours(1:10),
 proj = sp::CRS("+init=epsg:4326"))
move::angle(m)
direction_abs(trk, lonlat = TRUE, zero_dir = "E") %>% as_degree()

# trajectories
t1 <- trajectories::Track(
  spacetime::STIDF(sp::SpatialPoints(cbind(xy$x, xy$y)),
  lubridate::now(tzone = "UTC") + lubridate::hours(1:10), data = data.frame(1:10)))

t1[["direction"]]
direction_abs(trk, full_circle = TRUE, zero_dir = "N",
  clockwise = TRUE, append_last = FALSE) %>% as_degree

# moveHMM (only rel. ta)
df <- data.frame(ID = 1, x = xy$x, y = xy$y)
moveHMM::prepData(df, type = "UTM")$angle
direction_rel(trk)
# How do results compare to other packages
xy <- tibble(
  x = c(1, 4, 8, 8, 12, 8, 0, 0, 4, 2),
  y = c(0, 0, 0, 8, 12, 12, 12, 8, 4, 2))
trk <- mk_track(xy, x, y)
# adehabitatLT
df <- adehabitatLT::as.ltraj(data.frame(x = xy$x, y = xy$y), typeII = FALSE, id = 1)
df[[1]]$rel.angle
amt::direction_rel(trk, degrees = FALSE, full_circle = FALSE)

# trajectories
t1 <- trajectories::Track(
  spacetime::STIDF(sp::SpatialPoints(cbind(xy$x, xy$y)),
  lubridate::now() + lubridate::hours(1:10), data = data.frame(1:10)))

t1[["direction"]]
direction_abs(trk, degrees = TRUE, full_circle = TRUE, zero_dir = "N",
  clockwise = TRUE, append_last = FALSE)

# moveHMM (only rel. ta)
df <- data.frame(ID = 1, x = xy$x, y = xy$y)
moveHMM::prepData(df, type = "UTM")

trk

# step_lengths ------------------------------------------------------------
xy <- tibble(
  x = c(0, 1, 2),
  y = c(0, 1, 2)
)
xy <- mk_track(xy, x, y)

step_lengths(xy, lonlat = FALSE)
step_lengths(xy, lonlat = TRUE) # in m, but coords are assumed in degrees


# }