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

# S3 method for 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,...)

speeds(object,...)

# S3 method for ctmm
speeds(object,data=NULL,t=NULL,cycle=Inf,level=0.95,robust=FALSE,prior=FALSE,fast=TRUE,
       error=0.01,cores=1,...)

# S3 method for telemetry
speeds(object,CTMM,t=NULL,cycle=Inf,level=0.95,robust=FALSE,prior=FALSE,fast=TRUE,
       error=0.01,cores=1,...)

Arguments

object

A ctmm movement-model or telemetry object, which requires an additional CTMM argument.

data

Optional telemetry object on which the simulations will be conditioned.

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 t indices modulo cycle. E.g., for t sequenced by hours, cycle=24 gives daily the cycle of speeds. (Not yet supported.)

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

cor.min

Velocity correlation threshold for skipping gaps.

dt.max

Absolute gap sizes to skip (in seconds), alternative to cor.min.

error

Target (relative) standard error.

cores

Number of simulations to run in parallel. cores=0 will use all cores, while cores<0 will reserve abs(cores).

...

Arguments passed to emulate.

Details

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.

Value

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.

References

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

Author

C. H. Fleming.

Note

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.

See also

Examples

# \donttest{ # Load package and data library(ctmm) data(buffalo) Gabs <- buffalo$Gabs GUESS <- ctmm.guess(Gabs,interactive=FALSE) FIT <- ctmm.fit(Gabs,GUESS) # stationary Gaussian estimate speed(FIT)
#> low est high #> speed (kilometers/day) 11.82123 12.16713 12.51548
# conditional estimate speed(FIT,Gabs)
#> | | | 0% | |======= | 10% | |========== | 15% | |============== | 20% | |================== | 25% | |===================== | 30% | |======================== | 35% | |============================ | 40% | |================================ | 45% | |=================================== | 50% | |====================================== | 55% | |========================================== | 60% | |============================================== | 65% | |================================================= | 70% | |==================================================== | 75% | |======================================================== | 80% | |============================================================ | 85% | |=============================================================== | 90% | |================================================================== | 95% | |======================================================================| 100%
#> low est high #> speed (kilometers/day) 11.03669 11.46068 11.88858
# }