clockSim (version 0.1.1)

compute_period: Compute periodicity of time series

Description

Supports the following methods: fft and lomb. lomb uses the lomb package for computation. Please note that lomb can be resource intensive and significantly slower than fft.

Usage

compute_period(ts_vector, ts_time = NULL, method = "fft", verbose = FALSE, ...)

Value

Named vector of length 4 (period, power, snr, p.value).

Arguments

ts_vector

Numeric vector of time series

ts_time

Numeric vector of time points (if NULL use "step" unit)

method

Period calculation method.

verbose

Whether to print verbose messages on, e.g., time resolution.

...

Passed to the specific method for finer control, see details.

Details

If ts_time is provided, it is passed to the Lomb-Scargle algorithm for unevenly sampled data computation. In this case, lomb method returns period in unit of ts_time. ts_time has no effect on the fft method as it requires even time spacing.

If ts_time is NULL, assume even time spacing and period unit will be in the (implicitly provided) time spacing of the time series vector.

Power, SNR, p-value, and ellipsis of the period detection are method-specific:

1. fft: power = Spectrum power of the peak. SNR = (power of peak)/(median power). p-value is not available (NA). In this case, ... is not used

2. lomb: power = LS power of the peak. SNR is not available (NA). p-value = LS p-value. In this case, ... is forwarded to lomb::lsp(). Note: It is assumed that the period of interest is >1. Otherwise result will be incorrect.

Examples

# Generate a period = 50 sine wave data with some noise (even spacing)
n <- 1000
time <- seq(1, n, by = 1)
ts_data <- sin(2 * pi * time / 50) + rnorm(n, sd = 0.5)
compute_period(ts_data)
compute_period(ts_data, method = "lomb")
# Uneven sampling of the previous data and run lomb method again
s <- sample(1:n, n/3)
compute_period(ts_data[s], time[s], method = "lomb")