# speed: Estimate the average speed of a tracked animal In ctmm-initiative/ctmm: Continuous-Time Movement Modeling

## Description

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 average speed of the Gaussian movement process.

## Usage

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17``` ```speed(object,...) ## S3 method for class 'ctmm' speed(object,data=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 class 'telemetry' speed(object,CTMM,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 class 'ctmm' speeds(object,data,t=NULL,level=0.95,robust=FALSE,prior=FALSE,fast=TRUE,error=0.01,cores=1, ...) ## S3 method for class 'telemetry' speeds(object,CTMM,t=NULL,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. `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 uncertainty. `fast` Whether or not to invoke the central-limit theorem (see `emulate`) when `prior=TRUE`. `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 the ensemble mean will be infinite. In these cases `robust=TRUE` can be used to report the ensemble median rather than the ensemble mean. The time average of `speed`, in either case, is still the mean 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.

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

## Author(s)

C. H. Fleming.

`emulate`, `simulate`
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13``` ```# 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) # conditional estimate speed(FIT,Gabs) ```