fdars (version 0.3.3)

autoperiod: Autoperiod: Hybrid FFT + ACF Period Detection

Description

Implements the Autoperiod algorithm (Vlachos et al. 2005) which combines FFT-based candidate detection with ACF validation and gradient ascent refinement for robust period estimation.

Usage

autoperiod(
  fdataobj,
  n_candidates = 5,
  gradient_steps = 10,
  detrend_method = c("none", "linear", "auto")
)

Value

A list of class "autoperiod_result" with components:

period

Best detected period

confidence

Combined confidence (normalized FFT power * ACF validation)

fft_power

FFT power at the detected period

acf_validation

ACF validation score (0-1)

n_candidates

Number of candidates evaluated

candidates

Data frame of all candidate periods with their scores

Arguments

fdataobj

An fdata object.

n_candidates

Maximum number of FFT peaks to consider as candidates. Default: 5. More candidates increases robustness but also computation time.

gradient_steps

Number of gradient ascent steps for period refinement. Default: 10. More steps improves precision.

detrend_method

Detrending method to apply before period estimation:

"none"

No detrending (default)

"linear"

Remove linear trend

"auto"

Automatic AIC-based selection of detrending method

Details

The Autoperiod algorithm works in three stages:

1. Candidate Detection: Finds peaks in the FFT periodogram

2. ACF Validation: Validates each candidate using the autocorrelation function. Checks that the ACF shows a peak at the candidate period, and applies harmonic analysis to distinguish fundamental periods from harmonics.

3. Gradient Refinement: Refines each candidate using gradient ascent on the ACF to find the exact period that maximizes the ACF peak.

The final period is chosen based on the product of normalized FFT power and ACF validation score.

References

Vlachos, M., Yu, P., & Castelli, V. (2005). On periodicity detection and structural periodic similarity. In Proceedings of the 2005 SIAM International Conference on Data Mining.

See Also

sazed for an ensemble method, estimate.period for simpler single-method estimation

Examples

# Generate seasonal data with period = 2
t <- seq(0, 20, length.out = 400)
X <- matrix(sin(2 * pi * t / 2) + 0.1 * rnorm(400), nrow = 1)
fd <- fdata(X, argvals = t)

# Detect period using Autoperiod
result <- autoperiod(fd)
print(result)

# View all candidates
print(result$candidates)