easyclimate.field.equatorial_wave.wk_spectra

Wheeler-Kiladis Space-Time Spectra

This module provides functions for analyzing and visualizing Wheeler-Kiladis space-time spectra, including signal processing, symmetric/asymmetric decomposition, spectral analysis, and plotting of equatorial wave dispersion relationships.

See also

• https://github.com/mmaiergerber/wk_spectra

• Wheeler, M., & Kiladis, G. N. (1999). Convectively Coupled Equatorial Waves: Analysis of Clouds and Temperature in the Wavenumber–Frequency Domain. Journal of the Atmospheric Sciences, 56(3), 374-399. https://journals.ametsoc.org/view/journals/atsc/56/3/1520-0469_1999_056_0374_ccewao_2.0.co_2.xml

• Kiladis, G. N., M. C. Wheeler, P. T. Haertel, K. H. Straub, and P. E. Roundy (2009), Convectively coupled equatorial waves, Rev. Geophys., 47, RG2003, doi:https://doi.org/10.1029/2008RG000266

• Wheeler, M. C., & Nguyen, H. (2015). TROPICAL METEOROLOGY AND CLIMATE | Equatorial Waves. In Encyclopedia of Atmospheric Sciences (pp. 102–112). Elsevier. https://doi.org/10.1016/B978-0-12-382225-3.00414-X

• Yoshikazu Hayashi, A Generalized Method of Resolving Disturbances into Progressive and Retrogressive Waves by Space Fourier and Time Cross-Spectral Analyses, Journal of the Meteorological Society of Japan. Ser. II, 1971, Volume 49, Issue 2, Pages 125-128, Released on J-STAGE May 27, 2008, Online ISSN 2186-9057, Print ISSN 0026-1165, https://doi.org/10.2151/jmsj1965.49.2_125, https://www.jstage.jst.go.jp/article/jmsj1965/49/2/49_2_125/_article/-char/en

Functions

remove_dominant_signals(→ xarray.DataArray)	Removes the dominant signals by removing the long term linear trend (conserving the mean) and
decompose_symasym(da[, lat_dim])	Decompose data into symmetric and asymmetric parts about the equator.
calc_spectral_coefficients(data, spd, nDayWin, nDaySkip)	Calculate Wheeler-Kiladis spectral coefficients.
draw_wk_anti_analysis([max_freq, max_wn, ax, ...])	Plot antisymmetric Wheeler-Kiladis analysis with Matsuno dispersion curves.
draw_wk_sym_analysis([max_freq, max_wn, ax, ...])	Plot symmetric Wheeler-Kiladis analysis with Matsuno dispersion curves.

Module Contents

easyclimate.field.equatorial_wave.wk_spectra.remove_dominant_signals(data: xarray.DataArray, spd: float, nDayWin: float, nDaySkip: float, time_dim: str = 'time', lon_dim: str = 'lon', lat_dim: str = 'lat') → xarray.DataArray

Removes the dominant signals by removing the long term linear trend (conserving the mean) and by eliminating the annual cycle by removing all time periods less than a corresponding critical frequency.

Parameters

dataxarray.DataArray

Input data array with time, lat, lon dimensions

Caution

data must be daily data, and the length of time should be longer than one year (i.e., >365 day).

spdfloat

Samples per day (frequency of observations)

nDayWinfloat

Number of days in each analysis window

nDaySkipfloat

Number of days to skip between windows

time_dimstr, optional

Name of time dimension, default ‘time’

lon_dimstr, optional

Name of longitude dimension, default ‘lon’

lat_dimstr, optional

Name of latitude dimension, default ‘lat’

Returns

xarray.DataArray

Data with dominant signals removed

Example

>>> data = xr.DataArray(np.random.rand(730, 10, 20),
...                    dims=['time', 'lat', 'lon'])
>>> cleaned = remove_dominant_signals(data, spd=1, nDayWin=90, nDaySkip=30)

easyclimate.field.equatorial_wave.wk_spectra.decompose_symasym(da, lat_dim='lat')

Decompose data into symmetric and asymmetric parts about the equator.

The symmetric part is stored in the Southern Hemisphere and the asymmetric part in the Northern Hemisphere.

Parameters

daxarray.DataArray

Input array with latitude dimension

lat_dimstr, optional

Name of latitude dimension, default ‘lat’

Returns

xarray.DataArray

Array with decomposed components (symmetric in SH, asymmetric in NH)

Example

>>> data = xr.DataArray(np.random.rand(10, 20), dims=['lat', 'lon'])
>>> decomposed = decompose_symasym(data)

easyclimate.field.equatorial_wave.wk_spectra.calc_spectral_coefficients(data: xarray.DataArray, spd: float, nDayWin: float, nDaySkip: float, time_dim: str = 'time', lon_dim: str = 'lon', lat_dim: str = 'lat', max_freq: float = 0.5, max_wn: float = 15)

Calculate Wheeler-Kiladis spectral coefficients.

Parameters

dataxarray.DataArray

Input data array.

Caution

data must be daily data, and the length of time should be longer than one year (i.e., >365 day).

spdfloat

Samples per day

nDayWinfloat

Number of days in analysis window

nDaySkipfloat

Number of days to skip between windows

time_dimstr, optional

Time dimension name, default ‘time’

lon_dimstr, optional

Longitude dimension name, default ‘lon’

lat_dimstr, optional

Latitude dimension name, default ‘lat’

max_freqfloat, optional

Maximum frequency to return (CPD), default 0.5

max_wnfloat, optional

Maximum wavenumber to return, default 15

Returns

xarray.Dataset

Dataset containing:

• psumanti_r: Antisymmetric power spectrum (background removed)

• psumsym_r: Symmetric power spectrum (background removed)

Example

>>> data = xr.DataArray(np.random.rand(730, 10, 20),
...                    dims=['time', 'lat', 'lon'])
>>> spectra = calc_spectral_coefficients(data, spd=1, nDayWin=90, nDaySkip=30)

easyclimate.field.equatorial_wave.wk_spectra.draw_wk_anti_analysis(max_freq: float = 0.5, max_wn: float = 15, ax=None, add_xylabel: bool = True, add_central_line: bool = True, add_westward_and_eastward: bool = True, auto_determine_xyrange: bool = True, freq_lines: bool = True, matsuno_modes_labels: bool = True, cpd_lines_levels: list = [3, 6, 30], matsuno_lines: bool = True, he: list = [12, 25, 50], meridional_modes: list = [1])

Plot antisymmetric Wheeler-Kiladis analysis with Matsuno dispersion curves.

Parameters

max_freqfloat, optional

Maximum frequency to plot (CPD), default 0.5

max_wnfloat, optional

Maximum wavenumber to plot, default 15

axmatplotlib.axes.Axes, optional

Axes to plot on, creates new if None

add_xylabelbool, optional

Add x/y labels, default True

add_central_linebool, optional

Add central vertical line, default True

add_westward_and_eastwardbool, optional

Add eastward/westward labels, default True

auto_determine_xyrangebool, optional

Auto-set axis ranges, default True

freq_linesbool, optional

Add frequency lines, default True

matsuno_modes_labelsbool, optional

Add Matsuno mode labels, default True

cpd_lines_levelslist, optional

Periods (days) for frequency lines, default [3, 6, 30]

matsuno_linesbool, optional

Plot Matsuno dispersion curves, default True

helist, optional

Equivalent depths for Matsuno curves, default [12, 25, 50]

meridional_modeslist, optional

Meridional mode numbers, default [1]

Example

>>> fig, ax = plt.subplots()
>>> draw_wk_anti_analysis(ax=ax)

easyclimate.field.equatorial_wave.wk_spectra.draw_wk_sym_analysis(max_freq: float = 0.5, max_wn: float = 15, ax=None, add_xylabel: bool = True, add_central_line: bool = True, add_westward_and_eastward: bool = True, auto_determine_xyrange: bool = True, freq_lines: bool = True, matsuno_modes_labels: bool = True, cpd_lines_levels: list = [3, 6, 30], matsuno_lines: bool = True, he: list = [12, 25, 50], meridional_modes: list = [1])

Plot symmetric Wheeler-Kiladis analysis with Matsuno dispersion curves.

Parameters

max_freqfloat, optional

Maximum frequency to plot (CPD), default 0.5

max_wnfloat, optional

Maximum wavenumber to plot, default 15

axmatplotlib.axes.Axes, optional

Axes to plot on, creates new if None

add_xylabelbool, optional

Add x/y labels, default True

add_central_linebool, optional

Add central vertical line, default True

add_westward_and_eastwardbool, optional

Add eastward/westward labels, default True

auto_determine_xyrangebool, optional

Auto-set axis ranges, default True

freq_linesbool, optional

Add frequency lines, default True

matsuno_modes_labelsbool, optional

Add Matsuno mode labels, default True

cpd_lines_levelslist, optional

Periods (days) for frequency lines, default [3, 6, 30]

matsuno_linesbool, optional

Plot Matsuno dispersion curves, default True

helist, optional

Equivalent depths for Matsuno curves, default [12, 25, 50]

meridional_modeslist, optional

Meridional mode numbers, default [1]

Example

>>> fig, ax = plt.subplots()
>>> draw_wk_sym_analysis(ax=ax)