getVelocity: Calculate a velocity function from data

In andresgmejiar/lbmech: A Package to Study the Mechanics of Landscape and Behavior

Calculate a velocity function from data

Description

Calculate the velocity function for an animal from (x,y,z,t) data such as from GPS collars, assuming a function of form Tobler (see ####).

Usage

getVelocity(
  data,
  x = "x",
  y = "y",
  degs = FALSE,
  dl = NULL,
  z = "z",
  dt = "dt",
  ID = "ID",
  tau = NULL,
  tau_vmax = 0.95,
  tau_nlrq = 0.5,
  k_init = 3.5,
  s_init = -0.05,
  v_min = 0,
  v_lim = Inf,
  slope_lim = 1,
  tile_id = "TILEID",
  vals = "location",
  dir = tempdir(),
  ...
)

dtVelocity(data, ...)

Arguments

data	A data.frame or something coercible to a data.table containing all observations
x	A character string representing the data column containing the 'x' coordinates in meters or degrees. Ignored if data is of class SpatVector or Spatial, and ignored for distance calculations if dl is provided but required to extract elevations if z is of class Raster* or SpatialPolygonsDataFrame.
y	A character string representing the data column containing the 'y' coordinates in meters or degrees. Ignored if data is of class SpatVector or Spatial, and ignored for distance calculations if dl is provided but required to extract elevations if z is of class SpatRaster, Raster*, or SpatVector, SpatialPolygonsDataFrame.
degs	Logical. If FALSE, the getVelocity proceeds as if the input coordinates are meters in a projected coordinate system. If TRUE, assumes the input coordinates are decimal degrees in lat/long, with x giving the longitude column name and y the latitude. See distGeo.
dl	A character string representing the data column containing the net displacement between this observation and the previous in meters. Optional.
z	Either a character string, a SpatRaster or Raster*, or a SpatVector object. If character string, it represents the data column containing the 'z' coordinates/elevations in meters. If a SpatRaster or Raster*, a DEM containing the elevation in meters. If SpatVector, it must represent the sectors and filepaths/URLs corresponding to the region's elevations (see the output of makeGrid).
dt	A character string representing the data column containing the time difference from the previous observation in seconds.
ID	A character string representing the data column containing the unique ID for each observed trajectory. In other words, each set of points for each continuous observation for each observed individual would merit a unique id.
tau	A number between 0 and 1, representing a global cutoff value for tau_vmax and tau_nlrq. Ignored if the latter two are provided.
tau_vmax	A number between 0 and 1, representing the percentile at which the maximum velocity is calculated. In other words, if tau_vmax = 0.95 (the default), the maximum velocity will be at the 99.5th percentile of all observations.
tau_nlrq	A number between 0 and 1, representing the percentile at which the nonlinear regression is calculated. In other words, if tau_nlrq = 0.50 (the default), the total curve will attempt to have at each interval 5% of the observations above the regression and 95% below.
k_init	A number representing the value for the topographic sensitivity at which to initiate the nonlinear regression. Default is k_init = 3.5.
s_init	A number representing the value for dimensionless slope of maximum velocity at which to initiate the nonlinear regression. Default is s_init = -0.05.
v_min	The maximum velocity that will be considered. Any value equal to or below this will be excluded from the regression. Default is v_lim = 0.
v_lim	The maximum velocity that will be considered. Any value above this will be excluded from the regression. Default is v_lim = Inf, but it should be set to an animal's maximum possible velocity.
slope_lim	the maximum angle that will be considered. Any value above this will be excluded from the regression. Default is slope_lim = 1.
tile_id	a character string representing the name of the column in the z polygon containing the unique Tile IDs. Ignored if elevations are provided as a column or Raster*. Otherwise default is tile_id = 'TILEID'.
vals	A character string or a Raster* object. Required only if the z parameter is a polygon NOT the output of the makeGrid function as the default is the character string 'location'. If not, the vals parameter should be set to the column name containing the URL or file path to the DEM for that sector.
dir	A filepath to the directory being used as the workspace. Default is tempdir() but unless the analyses will only be performed a few times it is highly recommended to define a permanent workspace.
...	Additional parameters to pass to importMap. Ignored unless z is a polygon pointing to source dem files.

Details

dtVelocity is a wrapper for getVelocity for use inside of a data.table with observations from multiple sources (be it different individual animals and/or different instances from the same animal). In a data.table, use this function in the j slot, passing it along .SD.

Value

A list, containing the following entries:

(1) $model, containing an object of class nlrq containing the output model from the nonlinear quantitative regression.

(2) $vmax, containing the identified maximum velocity.

(3) $s, containing the identified angle of maximum velocity.

(4) $k, containing the identified topographic sensitivity factor.

(5) $tau_max, containing the employed tau_max.

(6) $tau_nlrq, containing the employed tau_nlrq.

(7) $data, containing a data.table with the original data in a standardized format

Examples

# Note that the output results should be senseless since they
# are computed on random data

#### Example 1:
# If the data contains an 'elevation' or 'z' column
data <- data.table(x = runif(10000,10000,20000),
                   y = runif(10000,30000,40000),
                   elevation = runif(10000,0,200),
                   dt = 120,
                   ID = rep(1:10,each=1000))
velocity <- getVelocity(data = data, z = 'elevation')


#### Example 2:
# If the data do not contain elevation, and 'z' is a raster
suppressWarnings( data[, z := NULL])

# Generate a DEM
n <- 5
dem <- expand.grid(list(x = 1:(n * 100),
                        y = 1:(n * 100))) / 100
dem <- as.data.table(dem)
dem[, z := 250 * exp(-(x - n/2)^2) + 
      250 * exp(-(y - n/2)^2)]
dem <- rast(dem)
ext(dem) <- c(10000, 20000, 30000, 40000)
crs(dem) <- "+proj=lcc +lat_1=48 +lat_2=33 +lon_0=-100 +datum=WGS84"

velocity <- getVelocity(data = data, z = dem)


### Example 3:
# If the data do not contain elevation, and 'z' is a sector grid pointing
# to file locations

# Export the DEM so it's not just stored on the memory
dir <- tempdir()
writeRaster(dem, paste0(dir,"/DEM.tif"),overwrite=TRUE)

# Import raster, get the grid
dem <- rast(paste0(dir,"/DEM.tif"))
grid <- makeGrid(dem = dem, nx = n, ny = n, sources = TRUE)

velocity <- getVelocity(data = data, z = grid, dir = dir, res = res(dem))

#' # Example 4:
# If you want to get the values by group within a data.table

# Generate fake data with x,y coordinates, z elevation, and a t
# column representing the number of seconds into the observation
data <- data.table(x = runif(10000,10000,20000),
                   y = runif(10000,30000,40000),
                   z = runif(10000,0,200),
                   dt = 15,
                   ID = rep(1:10,each=1000))
                   
# To get the velocity function for all observations together
v1 <- getVelocity(data)

# This is the same as above, but it only returns a list with the 
# coefficients and p-values
v2 <- dtVelocity(data)

# Instead this function is best to get the coefficients for 
# each individual track un a data.table using .SD
v3 <- data[, dtVelocity(.SD), by = 'ID', .SDcols = names(data)]

andresgmejiar/lbmech documentation built on Feb. 2, 2025, 12:37 a.m.