evaluate.pm.wn: Statistical significance of periodogram peaks (classical)

Description

Calculates the Lomb-Scargle periodogram for the given time series and estimates the statistical significance of the global periodogram maximum based on the null hypothesis of uncorrelated (white) noise. Available for historical reasons and for comparison purposes.

Usage

evaluate.pm.wn(times, signal, minPeakFreq=0, minFitFreq=0)

Arguments

times

Numerical vector. Time points of the time series.

signal

Numerical vector of same size as times. Values of the time series.

minPeakFreq

Single non-negative number. Minimum considered frequency when determining periodogram peak. Use this to ignore low-frequency components from the spectrum.

minFitFreq

Single non-negative number. Minimum considered frequency when fitting the white noise null model to the periodogram. Use this to ignore low-frequency components from the spectrum.

Value

A list with the entries
errorWill be TRUE if an error occured, FALSE otherwise.
errorMessageA short error message if error==TRUE.
If error==FALSE, the returned list also includes:
frequenciesAvailable periodogram frequencies as a numerical vector.
periodogramPeriodogram powers corresponding to the returned frequencies, as a numerical vector.
peakModeAn integer indicating the position of the global periodogram maximum (starting at minPeakFreq) in the vector frequencies.
powerEstimateThe estimated white noise power. Estimated from the average periodogram power, which corresponds to using the total variance of the time series (if minFitFreq==0).
minPeakModeThe minimum periodogram mode considered for determining the periodogram peak. This will be 1 if minPeakFreq==0.
minFitModeThe minimum periodogram mode considered for estimating the white noise power. This will be 1 if minFitFreq==0.
RSSThe sum of squared residuals of the periodogram from the estimated white noise power.
PStatistical significance of periodogram peak. This is the probability that a white noise periodogram (of the estimated power) would generate a peak at least as strong as the observed peak (among the considered frequencies). The calculated P-value is only an approximation that becomes exact for long regular time series.

References

Scargle, J. D. (1982) - Studies in astronomical time series analysis. II Statistical aspects of spectral analysis of unevenly spaced data, The Astrophysical Journal 263, 835--853

Horne, J. H., Baliunas, S. L. (1986) - A prescription for period analysis of unevenly sampled time series, The Astrophysical Journal 302, 757--763

Louca, S., Doebeli, M. - Detecting cyclicity in ecological time series (in review, as of June 2014)

Examples

Run this code

# generate time series
times  = seq(0,10,0.1);
signal = rnorm(n=length(times));
report = evaluate.pm.wn(times=times, signal=signal);

# plot time series
old.par <- par(mfrow=c(1, 2));
plot(ts(times), ts(signal), 
     xy.label=FALSE, type="l", 
     ylab="signal", xlab="time", main="OUSS time series");
     
# plot periodogram
title = sprintf("Periodogram OUSS analysis
(peak freq=%.3g, P=%.2g)",
                report$frequencies[report$peakMode],report$P);
plot(ts(report$frequencies),
     ts(report$periodogram), 
     xy.label=FALSE, type="l", 
     ylab="power", xlab="frequency", 
     main=title, col="black");
	
# plot fitted flat WN power
lines(c(report$frequencies[1],tail(report$frequencies,1)), 
      c(report$powerEstimate, report$powerEstimate ), col="blue");
par(old.par)