speed | R Documentation |
Given a ctmm
movement model and telemetry
data, speed
simulates multiple realizations of the individual's trajectory to estimate the time-averaged speed, which is proportional to distance traveled, while speeds
estimates instantaneous speeds at a specified array of times t
. Both tortuosity (non straight-line motion between the data) and telemetry error can be accounted for. Given only a ctmm
movement model and no data, speed
calculates the mean speed of the Gaussian movement process. All methods are described in Noonan & Fleming et al (2019).
speed(object,...)
## S3 method for class 'ctmm'
speed(object,data=NULL,t=NULL,level=0.95,robust=FALSE,units=TRUE,prior=TRUE,fast=TRUE,
cor.min=0.5,dt.max=NULL,error=0.01,cores=1,trace=TRUE,...)
## S3 method for class 'telemetry'
speed(object,CTMM,t=NULL,level=0.95,robust=FALSE,units=TRUE,prior=TRUE,fast=TRUE,
cor.min=0.5,dt.max=NULL,error=0.01,cores=1,trace=TRUE,...)
speeds(object,...)
## S3 method for class 'ctmm'
speeds(object,data=NULL,t=NULL,cycle=Inf,level=0.95,robust=FALSE,prior=FALSE,fast=TRUE,
error=0.01,cores=1,trace=TRUE,...)
## S3 method for class 'telemetry'
speeds(object,CTMM,t=NULL,cycle=Inf,level=0.95,robust=FALSE,prior=FALSE,fast=TRUE,
error=0.01,cores=1,trace=TRUE,...)
object |
A |
data |
Optional |
CTMM |
Movement model object. |
t |
Array of times to estimate instantaneous speeds at, or range of times to estimate mean speed over. |
cycle |
Average over time |
level |
Confidence level to report on the estimated average speed. |
robust |
Use robust statistics for the ensemble average and its confidence intervals (see Details). |
units |
Convert result to natural units. |
prior |
Account for model parameter uncertainty. |
fast |
Whether or not to invoke the central-limit theorem when propagating parameter uncertainty (see |
cor.min |
Velocity correlation threshold for skipping gaps. |
dt.max |
Absolute gap sizes to skip (in seconds), alternative to |
error |
Target (relative) standard error. |
cores |
Number of simulations to run in parallel. |
trace |
Display a progress bar. |
... |
Arguments passed to |
The cor.min
or dt.max
arguments are used to constrain the estimate to be derived from simulations near the data, and therefore ensure that the estimate is more reflective of the data than the model.
If data quality is poor and velocity can barely be resolved, then the sampling distribution may occassionally include impersistent motion and its mean will be infinite. In these cases robust=TRUE
can be used to report the sampling distribution's median rather than its mean. The time average of speed
, in either case, is still the mean average of times and the resulting quantity is still proportional to distance traveled. Furthermore, note that medians should be compared to medians and means to means, so the robust
option should be the same for all compared individuals.
Returns the estimated mean speed of the sampled trajectory with CIs by default. If level=NULL
, then the ensemble of mean speeds is returned instead.
The mean speed estimated by speed
is applicable only during the sampling periods. If an individual is diurnal/nocturnal and only tracked during the day/night, then the output of speed
will only be the mean speed during the day/night. For instance, if an individual is tracked the 12 hours per day during which it is active, and speed
reports a mean speed of 10 kilometers per day during those periods, then the average distance traveled per day is only 5 kilometers (from 10 kilometers /
day *
12 hours). An average of 10 kilometers would only result if the individual were similarly active for 24 hours a day.
The average speeds estimated here are mean speeds. The speeds reported by summary.ctmm
are root-mean-square (RMS) speeds. These quantities are sometimes proportional, but not equivalent.
C. H. Fleming.
M. J. Noonan, C. H. Fleming, T. S. Akre, J. Drescher-Lehman, E. Gurarie, A.-L. Harrison, R. Kays, Justin Calabrese, “Scale-insensitive estimation of speed and distance traveled from animal tracking data”, Movement Ecology, 7:35 (2019).
emulate
, simulate
# Load package and data
library(ctmm)
data(buffalo)
DATA <- buffalo$Gabs
GUESS <- ctmm.guess(DATA,interactive=FALSE)
# in general, you should use ctmm.select instead
FIT <- ctmm.fit(DATA,GUESS)
# stationary Gaussian estimate
speed(FIT)
# conditional estimate
# you will likely want trace=TRUE
speed(FIT,DATA,trace=FALSE)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.