Skip to contents

Detect periodicity using the Lomb-Scargle periodogram

Source: R/periodicity.R
detect_periodicity_ls.Rd

Computes the Scargle (1982) normalised Lomb-Scargle periodogram and evaluates the false-alarm probability (FAP) of the dominant peak using the analytic Baluev (2008) approximation. Unlike detect_periodicity(), this function works correctly on unevenly sampled series and is more robust to missing months.

Usage

detect_periodicity_ls(
  x,
  value_col = "value",
  time_col = "monyear",
  detrend = TRUE,
  ofac = 10L,
  period_min = 4,
  period_max = 60
)

# S3 method for class 'hmis_ls_periodicity'
plot(x, ...)

Arguments

x

An hmis_ls_periodicity object from detect_periodicity_ls().

value_col

Column name for values when x is a data frame. Default "value".

time_col

Column name for time when x is a data frame. Default "monyear". Parsed by parse_monyear() if character.

detrend

Logical. Subtract a linear trend before analysis. Default TRUE.

ofac

Integer oversampling factor for the frequency grid. Default 10. Higher values give finer frequency resolution.

period_min

Minimum period (in months) to consider. Default 4.

period_max

Maximum period (in months) to consider. Default 60.

...

Additional arguments (ignored).

Value

A list with class "hmis_ls_periodicity" containing:

is_periodic

Logical. TRUE if Baluev FAP < 0.05.

dominant_period

Period (months) at the highest LS power.

peak_power

Lomb-Scargle normalised power at the dominant peak.

fap

Baluev (2008) false-alarm probability of the peak.

frequencies

Data frame of frequency grid with columns frequency, period, power.

n

Number of observations used.

detrended

Whether linear detrending was applied.

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.

Baluev, R.V. (2008). Assessing the statistical significance of periodogram peaks. Monthly Notices of the Royal Astronomical Society, 385, 1279–1285.

Examples

if (FALSE) { # \dontrun{
births <- get_hmis("Number of female live births",
  state = "Kerala", category = "Total", sector = "Total"
)
result <- detect_periodicity_ls(births)
print(result)
plot(result)
} # }