ctmm (version 0.3.1)

periodogram: Calculate the Lomb-Scargle periodogram of animal-tracking data

Description

This function calculates isotropic Lomb-Scargle periodogram (LSP, Scargle, 1982) from a telemetry object. One of two algorithms is used. The slow $O(n^2)$ algorithm vectorizes the exact relations of Scargle (1982), while the fast $O(n \log n)$ algorithm uses the FFT method described in Péron et al (2016). The latter method is only exact if the data are evenly scheduled, permitting gaps, and otherwise it produces some distortion at high frequencies.

Usage

periodogram(data,CTMM=NULL,T=NULL,dt=NULL,res=1,fast=NULL)

## S3 method for class 'periodogram':
plot(x,diagnostic=FALSE,col="black",transparency=0.25,grid=TRUE,...)

Arguments

data

telemetry data object or list of such objects.

CTMM

An optional ctmm model object for specifying the mean.

T

Sampling period for frequency resolution.

dt

Sampling interval for frequency cutoff.

res

Multiplier to inflate the frequency resolution.

fast

Use the exact algorithm if FALSE or the FFT algorithm if TRUE. The default behavior switches from slow to fast at length(data$t)>=10000.

x

Output object of periodogram.

diagnostic

Plot the sampling schedule's periodogram to check for spurious periodicities.

col

Color of periodogram.

transparency

Adds transparency to clustered data if greater than zero. Should be less than one.

grid

Whether or not to plot gridlines at common periodicities.

...

Optional arguments fed to plot.

Value

• Returns a periodogram object (class periodogram) which is a dataframe containing the frequency, f and the Lomb-Scargle periodogram at that frequency, LSP.

encoding

UTF-8

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 and this choice corresponds to the discrete Fourier transform (DFT) periodogram for evenly-sampled data. If no T is specified, the full sampling period is used. The frequency grid interval is finally given by 1/(2*(T+dt)*res) and the frequency cutoff is given by 1/(2*dt), both in accordance with the DFT periodogram. Increasing res beyond res=1 will make for a smooth periodogram, but sequential frequencies will be highly correlated. If a ctmm argument is provided, the ML mean will be detrended from the data prior to calculating the periodogram. Otherwise, the sample mean will be detrended. If a list of telemetry objects are fed into periodogram, then a mean periodogram object will be returned with the default T and dt arguments selected on a worst case basis according to the method described by Péron et al (2016).

References

J. D. Scargle. (1952). Studies in astronomical time-series analysis. II. Statistical aspects of spectral analysis of unevenly-sampled data. The Astrophysical Journal, 263, 835-853. G. Péron, C. H. Fleming, J. M. Calabrese. (2016).

Examples

#Load package and data
library(ctmm)
data(buffalo)

#Extract movement data for a single animal
cilla <- buffalo[[1]]

#Calculate periodogram (fast=TRUE for example)
LSP <- periodogram(cilla,fast=TRUE)

#Plot the periodogram
plot(LSP)