environmentaltools.spectral.analysis.harmonic_analysis

environmentaltools.spectral.analysis.harmonic_analysis(data: DataFrame, lat: float, file_name: str = None)[source]

Perform harmonic (tidal) analysis on observational time series data.

This function uses the UTide package (Codiga, 2011) to extract tidal constituents from time series data, including amplitude, phase, and their uncertainties. The method can handle time series with gaps.

Parameters:

  • data (pd.DataFrame) – Time series data with datetime index. Missing values will be removed before analysis.

  • lat (float) – Latitude of the observation location in decimal degrees. Required for computing nodal corrections.

  • file_name (str, optional) – Path to save the tidal constituents as JSON file. If None, results are not saved to file.

Returns:

Dictionary containing tidal constituents with keys:

  • Amplitude and phase for each constituent

  • Confidence intervals (from Monte Carlo analysis)

  • Statistical information about the fit

Return type:

dict

Raises:

ValueError – If the UTide library is not installed.

Notes

The analysis uses the ordinary least squares (OLS) method with nodal corrections and Monte Carlo confidence intervals. The Rayleigh criterion is set to 0.95 to resolve closely spaced tidal constituents.

References

Codiga, D.L., 2011. Unified Tidal Analysis and Prediction Using the UTide Matlab Functions. Technical Report 2011-01. Graduate School of Oceanography, University of Rhode Island, Narragansett, RI. 59pp.