peacots (version 1.3.2)

ps_ouss: Expected periodogram of the OUSS process

Description

Returns the expected periodogram power of the Ornstein-Uhlenbeck state space (OUSS) process at a particular frequency, when sampled at regular time intervals for a finite time.

Usage

ps_ouss(freq, power_o, sigma, 
        rho, lambda, 
        power_e, epsilon, 
        time_step, series_size)

Value

Returns a numeric vector of the same size as freq, containing the corresponding expected periodogram powers of the OUSS process.

Arguments

freq

Single number or numeric vector. The frequency for which to the power spectrum is to be calculated.

power_o

Single non-negative number. Power at zero-frequency generated by the underlying OU process, when sampled at the given time_step. Either power_o or sigma (but not both) must be provided.

sigma

Single number. Standard deviation of OU fluctuations around equilibrium. Either power_o or sigma (but not both) must be provided.

rho

Single number between 0 (exclusive) and 1 (inclusive). Correlation of the OU process between two subsequent time points. Either rho or lambda (but not both) must be provided.

lambda

Single non-negative number. Resilience (or relaxation rate) of the OU process. This is also the inverse correlation time of the OU process. Either rho or lambda (but not both) must be provided.

power_e

Single non-negative number. Asymptotic power at large frequencies due to the random measurement errors. Setting this to zero corresponds to the classical OU process. Either power_e or epsilon (but not both) must be provided.

epsilon

Single number. Standard deviation of Gaussian measurement error. Setting this to zero corresponds to the classical OU process. Either power_e or epsilon (but not both) must be provided.

time_step

Positive number. The time step of the time series that was (or will be) used for periodogram generation.

series_size

Positive integer. The number of sampled time points.

Author

Stilianos Louca

Details

The OUSS parameters power_o, lambda and power_e will typically be maximum-likelihood fitted values returned by evaluate.pm. The value of time_step is also returned by evaluate.pm and is inferred from the analysed time series. More generally, power_o and power_e are proportional to the OUSS parameters sigma^2 and epsilon^2 (see generate_ouss), respectively, but the exact scaling depends on the normalization used for the periodogram.

In the limit where series_size becomes very large, ps_ouss becomes the same as ps_ouss_asymptotic.

References

Louca, S., Doebeli, M. (2015) Detecting cyclicity in ecological time series, Ecology 96: 1724--1732

See Also

evaluate.pm, generate_ouss

Examples

# generate OUSS time series
times  = seq(0,20,0.25);
signal = generate_ouss(times, mu=0, sigma=1, lambda=1, epsilon=0.5);

# calculate periodogram and fit OUSS model
report = evaluate.pm(times=times, signal=signal, startRadius=2);

# plot periodogram
plot(report$frequencies, report$periodogram, 
     type="l", ylab="power", xlab="frequency", main="periodogram & fitted OUSS power spectrum");

# plot expected OUSS periodogram
lines(report$frequencies, 
      ps_ouss(freq=report$frequencies, 
              power_o=report$power_o, 
              lambda=report$lambda, 
              power_e=report$power_e, 
              time_step=report$time_step,
              series_size=length(times)), 
      col="red");