lsp_mod: Lomb-Scargle Periodogram

In edpclau/circadian-dynamics: Period and Rythm Analysis of Timeseries Data

Lomb-Scargle Periodogram

Description

A modification on the lomb-pkg's lsp function [lomb::lsp()]. Automatically increases the oversampling factor when it is too small for the chosen from-to interval. Computes the Lomb-Scargle periodogram for a time series with irregular (or regular) sampling intervals. Allows selecting a frequency range to be inspected, as well as the spacing of frequencies scanned.

Usage

lsp_mod(x, times = NULL, from = NULL, to = NULL, type = c("frequency", "period"), ofac = 1, alpha = 0.01, plot = TRUE, ...)

Arguments

x	The data to be analysed. x can be either a two-column numerical dataframe or matrix, with sampling times in columnn 1 and measurements in column 2, a single numerical vector containing measurements, or a single vector ts object (which will be converted to a numerical vector).
times	If x is a single vector, times can be provided as a numerical vector of equal length containing sampling times. If x is a vector and times is NULL, the data are assumed to be equally sampled and times is set to 1:length(x).
from	The starting frequency (or period, depending on type) to begin scanning for periodic components.
to	The highest frequency (or period, depending on type) to scan.
type	Either “frequency” (the default) or “period”. Determines the type of the periodogram x-axis.
ofac	The oversampling factor. Must be an integer>=1. Larger values of ofac lead to finer scanning of frequencies but may be time-consuming for large datasets and/or large frequency ranges (from...to).
alpha	The significance level. The periodogram plot shows a horizontal dashed line. Periodogram peaks exceeding this line can be considered significant at alpha. Defaults to 0.01. Only used if plot=TRUE.
plot	Logical. If plot=TRUE the periodogram is plotted.
...	Further graphical parameters affecting the periodogram plot.

Value

A named list with the following components:

scanned A vector containing the frequencies/periods scanned.

power A vector containing the normalised power corresponding to scanned frequencies/periods.

data Names of the data vectors analysed.

n The length of the data vector.

type The periodogram type used, either "frequency" or "period".

ofac The oversampling factor used.

n.out The length of the output (powers). This can be >n if ofac >1.

alpha The false alarm probability used.

sig.level Powers > sig.level can be considered significant peaks at p=alpha.

peak The maximum power in the frequency/period interval inspected.

peak.at The frequency/period at which the maximum peak occurred.

p.value The probability that the maximum peak occurred by chance.

Note

For a description of the properties of the Lomb-Scargle Periodogram, its computation and comparsion with other methods see Ruf, T. (1999). Function lsp uses the algorithm given by Press et al (1994). The Lomb-Scargle Periodogram was originaly proposed by Lomb N.R. (1976) and furher extended by Scargle J.D. (1982).

Author(s)

Original code by: Thomas Ruf [e-mail] based on code by Press et al (1994).

Modified by: Eddie Perez Claudio [e-mail]

References

Lomb N.R. (1976) Least-squares frequency analysis of unequally spaced data. Astrophysics and Space Science 39:447–462 Press W.H., Teukolsky S.A., Vetterling S.T., Flannery, B.P. (1994) Numerical recipes in C: the art of scientific computing.2nd edition. Cambridge University Press, Cambridge, 994pp. Ruf, T. (1999) The Lomb-Scargle Periodogram in Biological Rhythm Research: Analysis of Incomplete and Unequally Spaced Time-Series. Biological Rhythm Research 30: 178–201. Scargle J.D. (1982) Studies in astronomical time series. II. Statistical aspects of spectral analysis of unevenly spaced data. The Astrophysical Journal 302: 757–763.

Examples

# ibex contains an unevenly sampled time series
data(ibex)
lsp(ibex[2:3],)
lsp(ibex$temp,times=ibex$hours,type='period',ofac=5)
# lynx contains evenly sampled data
lsp(lynx)
lynx.spec <- lsp(lynx,type='period',from=2,to=20,ofac=5)
summary(lynx.spec)

edpclau/circadian-dynamics documentation built on Aug. 25, 2023, 12:18 p.m.