amt: steps – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

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 class 'track_xy'
direction_abs(
  x,
  full_circle = FALSE,
  zero_dir = "E",
  clockwise = FALSE,
  append_last = TRUE,
  lonlat = FALSE,
  ...
)

direction_rel(x, ...)

## S3 method for class 'track_xy'
direction_rel(x, lonlat = FALSE, append_last = TRUE, zero_dir = "E", ...)

step_lengths(x, ...)

## S3 method for class 'track_xy'
step_lengths(x, lonlat = FALSE, append_last = TRUE, ...)

steps_by_burst(x, ...)

## S3 method for class 'track_xyt'
steps_by_burst(x, lonlat = FALSE, keep_cols = NULL, ...)

steps(x, ...)

## S3 method for class 'track_xy'
steps(x, lonlat = FALSE, keep_cols = NULL, ...)

## S3 method for class '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 transferred 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`.

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().

Value

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

Examples

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

amt

Animal Movement Tools

v0.1.4

GPL-3

Authors

Johannes Signer [aut, cre], Brian Smith [ctb], Bjoern Reineking [ctb], Ulrike Schlaegel [ctb], John Fieberg [ctb], Scott LaPoint [dtc]

Initial release