getVelocity.RdCalculate the velocity function for an animal from (x,y,z,t) data such as from GPS collars, assuming a function of form Tobler (see ####).
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, ...)A data.frame or something coercible to a data.table containing all observations
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.
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.
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.
A character string representing the data column containing the net displacement between this observation and the previous in meters. Optional.
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).
A character string representing the data column containing the time difference from the previous observation in seconds.
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.
A number between 0 and 1, representing a global cutoff
value for tau_vmax and tau_nlrq. Ignored if the latter two are provided.
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.
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.
A number representing the value for the topographic sensitivity
at which to initiate the nonlinear regression. Default is k_init = 3.5.
A number representing the value for dimensionless slope of
maximum velocity at which to initiate the nonlinear regression. Default is
s_init = -0.05.
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.
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.
the maximum angle that will be considered. Any value
above this will be excluded from the regression. Default is slope_lim = 1.
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'.
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.
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.
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
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.
# 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])
#> x y elevation dt ID
#> 1: 10123.14 31369.57 196.89007 120 1
#> 2: 14728.42 31995.84 142.00460 120 1
#> 3: 15543.20 39382.71 108.43118 120 1
#> 4: 19652.02 33309.40 114.41404 120 1
#> 5: 15772.26 39028.60 92.39332 120 1
#> ---
#> 9996: 11136.10 30943.92 162.03904 120 10
#> 9997: 17307.29 32594.44 168.48583 120 10
#> 9998: 19017.89 30292.77 119.43149 120 10
#> 9999: 13805.53 32213.33 31.78615 120 10
#> 10000: 16877.45 38002.75 63.23896 120 10
# 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)]
#> x y z
#> 1: 0.01 0.01 1.0146139
#> 2: 0.02 0.01 1.0404641
#> 3: 0.03 0.01 1.0675194
#> 4: 0.04 0.01 1.0958300
#> 5: 0.05 0.01 1.1254477
#> ---
#> 249996: 4.96 5.00 1.0711366
#> 249997: 4.97 5.00 1.0428260
#> 249998: 4.98 5.00 1.0157707
#> 249999: 4.99 5.00 0.9899205
#> 250000: 5.00 5.00 0.9652271
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))
#> [1] "Cropping Tile SECTOR_01 (1 of 3)"
#> [1] "Cropping Tile SECTOR_02 (2 of 3)"
#> [1] "Cropping Tile SECTOR_07 (3 of 3)"
#> [1] "Cropping Tile SECTOR_03 (1 of 3)"
#> [1] "Cropping Tile SECTOR_04 (2 of 3)"
#> [1] "Cropping Tile SECTOR_08 (3 of 3)"
#> [1] "Cropping Tile SECTOR_17 (1 of 6)"
#> [1] "Cropping Tile SECTOR_18 (2 of 6)"
#> [1] "Cropping Tile SECTOR_19 (3 of 6)"
#> [1] "Cropping Tile SECTOR_22 (4 of 6)"
#> [1] "Cropping Tile SECTOR_23 (5 of 6)"
#> [1] "Cropping Tile SECTOR_24 (6 of 6)"
#> [1] "Cropping Tile SECTOR_10 (1 of 3)"
#> [1] "Cropping Tile SECTOR_14 (2 of 3)"
#> [1] "Cropping Tile SECTOR_15 (3 of 3)"
#> [1] "Cropping Tile SECTOR_11 (1 of 1)"
#> [1] "Cropping Tile SECTOR_16 (1 of 2)"
#> [1] "Cropping Tile SECTOR_21 (2 of 2)"
#> [1] "Cropping Tile SECTOR_13 (1 of 1)"
#> [1] "Cropping Tile SECTOR_20 (1 of 1)"
#' # 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)]