environmentaltools.spectral.analysis.lombscargle_periodogram

environmentaltools.spectral.analysis.lombscargle_periodogram(data, variable, max_period=None, nperiods=5, freq='H')[source]

Compute the Lomb-Scargle periodogram for unevenly sampled time series.

The Lomb-Scargle periodogram is designed for spectral analysis of time series with irregular sampling. It identifies significant periodicities in the data by computing the power spectral density across a range of periods.

Parameters:

  • data (pd.DataFrame) – Time series data with datetime index.

  • variable (str) – Name of the column containing the variable to analyze.

  • max_period (float, optional) – Maximum period (in years for hourly data, or years for daily data) to include in the analysis. If None, uses default range up to 2 years.

  • nperiods (int, default=5) – Number of most significant periods to identify.

  • freq ({'H', 'D'}, default='H') – Frequency of the data: ‘H’ for hourly, ‘D’ for daily.

Returns:

DataFrame with periods as index and columns:

  • ’psd’ : Power spectral density values

  • ’significant’ : Boolean indicating the top n most significant periods

Return type:

pd.DataFrame

Notes

The function normalizes periods to years and applies a moving average with window size of 100 to identify the most significant periodicities.

Examples

>>> import pandas as pd
>>> data = pd.DataFrame({'temp': [20, 21, 19, 22]},
...                      index=pd.date_range('2020-01-01', periods=4, freq='H'))
>>> psd = lombscargle_periodogram(data, 'temp', nperiods=2)