evaluate.pm.wn {peacots}

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

error

Will be TRUE if an error occured, FALSE otherwise.

errorMessage

A short error message if error==TRUE.

If error==FALSE, the returned list also includes:

frequencies

Available periodogram frequencies as a numerical vector.

periodogram

Periodogram powers corresponding to the returned frequencies, as a numerical vector.

peakMode

An integer indicating the position of the global periodogram maximum (starting at minPeakFreq) in the vector frequencies.

powerEstimate

The estimated white noise power. Estimated from the average periodogram power, which corresponds to using the total variance of the time series (if minFitFreq==0).

minPeakMode

The minimum periodogram mode considered for determining the periodogram peak. This will be 1 if minPeakFreq==0.

minFitMode

The minimum periodogram mode considered for estimating the white noise power. This will be 1 if minFitFreq==0.

RSS

The sum of squared residuals of the periodogram from the estimated white noise power.

P

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

Author(s)

Stilianos Louca

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. (2015) Detecting cyclicity in ecological time series, Ecology 96: 1724–1732

See Also

evaluate.pm

Examples

# generate time series
times  = seq(0,20,0.25);
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\n(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)