# variogram: Calculate an empirical variogram from movement data In ctmm-initiative/ctmm: Continuous-Time Movement Modeling

## Description

This function calculates the empirical variogram of multi-dimensional tracking data for visualizing stationary (time-averaged) autocorrelation structure. One of two algorithms is used. The slow O(n^2) algorithm is based upon Fleming et al (2014), but with interval-weights instead of lag-weights. Additional modifications have also been included to accommodate drift in the sampling rate. The fast O(n \log n) algorithm is based upon the FFT method of Marcotte (1996), with some tweaks to better handle irregularly sampled data. Both methods reduce to the unbiased “method of moments” estimator in the case of evenly scheduled data, even with missing observations, but they produce slightly different outputs for irregularly sampled data.

## Usage

 `1` ```variogram(data,dt=NULL,fast=TRUE,res=1,CI="Markov",axes=c("x","y")) ```

## Arguments

 `data` `telemetry` data object of the 2D timeseries data. `dt` Lag bin width. An ordered array will yield a progressive coarsening of the lags. Defaults to the median sampling interval. `fast` Use the interval-weighted algorithm if `FALSE` or the FFT algorithm if `TRUE`. The slow algorithm outputs a progress bar. `res` Increase the discretization resolution for irregularly sampled data with `res>1`. Decreases bias at the cost of smoothness. `CI` Defaults to only consider non-overlapping lags independent. All unique lags are considered independent with "IID". `axes` Array of axes to calculate an average (isotropic) variogram for.

## Details

If no `dt` is specified, the median sampling interval is used. This is typically a good assumption for most data, even when there are gaps. A `dt` coarser than the sampling interval may bias the variogram (particuarly if `fast=TRUE`) and so this should be reserved for poor data quality.

For irregularly sampled data, it may be useful to provide an array of time-lag bin widths to progressively coarsen the variogram. I.e., if you made the very bad choice of changing your sampling interval on the fly from `dt1` to `dt2`, where `dt1` < `dt2`, the an appropriate choice would be `dt=c(dt1,dt2)`. On the other hand, if your sampling is itself a noisy process, then you might want to introduce larger and larger `dt` components as the visual appearance of the variogram breaks down with increasing lags. Alternatively, you might try the `fast=FALSE` option or aggregating multiple individuals with `mean.variogram`.

With irregularly sampled data, different size lags must be aggregated together, and with current fast methods there is a tradeoff between bias and smoothness. The default settings produce a relatively smooth estimate, while increasing `res` (or setting `fast=FALSE`) will produce a less biased estimate, which is very useful for `correlogram`.

In standard variogram regression treatments, all lags are considered as independent (`CI="IID"`) for the purposes of confidence-interval estimation, even if they overlap in time. However, in high resolution datasets this will produce vastly underestimated confidence intervals. Therefore, the default `CI="Markov"` behavior is to consider only the maximum number of non-overlapping lags in calculating confidence intervals.

## Value

Returns a variogram object (class variogram) which is a dataframe containing the time-lag, `lag`, the semi-variance estimate at that lag, `SVF`, and the approximate number of degrees of freedom associated with that semi-variance, `DOF`, with which its confidence intervals can be estimated.

## Note

Prior to `ctmm` v0.3.6, `fast=FALSE` used the lag-weighted esitmator of Fleming et al (2014). Lag weights have been abandoned in favor of interval weights, which are less sensitive to sampling irregularity. The same weighting formulas are used, but with `dt` instead of the current lag.

## Author(s)

C. H. Fleming and J. M. Calabrese.

## References

D. Marcotte. Fast variogram computation with FFT. Computers and Geosciences 22(10), 1175-1186 (1996).

C. H. Fleming, J. M. Calabrese, T. Mueller, K.A. Olson, P. Leimgruber, W. F. Fagan. From fine-scale foraging to home ranges: A semi-variance approach to identifying movement modes across spatiotemporal scales. The American Naturalist, 183:5, E154-E167 (2014).

`vignette("variogram")`, `correlogram`, `mean.variogram`, `plot.variogram`, `variogram.fit`.
 ``` 1 2 3 4 5 6 7 8 9 10 11 12``` ```#Load package and data library(ctmm) data(buffalo) #Extract movement data for a single animal Cilla <- buffalo\$Cilla #Calculate variogram SVF <- variogram(Cilla) #Plot the variogram with 50% and 95% CIs plot(SVF,level=c(0.5,0.95)) ```