copower2d

copower2d(dx_lon, dx_time, y1, y2, /, axis_lon=0, axis_time=- 1, **kwargs)[source]

Return the 2D spectral decomposition of two real-valued arrays with along an arbitrary time dimension and cyclic dimension. For details, see [RH91].

Parameters

  • dx_lon (float or array-like) – Longitude or cyclic dimension step size in physical units. Used to scale fx_lon.

  • dx_time (float or array-like) – Time dimension step size in physical units. Used to scale fx_time.

  • y1 (array-like) – First input data.

  • y2 (array-like) – Second input data. Must have same shape as y1.

  • axis_lon (int, optional) – Location of the cyclic “space” axis, generally longitude.

  • axis_time (int, optional) – Location of the “time” axis.

  • wintype (str or (str, float), optional) – The window specification, passed to window. The resulting weights are used to window the data before carrying out spectral decompositions. See notes for details.

  • nperseg (int, optional) – The time dimension window or segment length, passed to window. If None, windowing is not carried out. See notes for details.

  • detrend ({‘constant’, ‘linear’}, optional) – Passed as the type argument to scipy.signal.detrend. 'constant' removes the mean and 'linear' removes the linear trend.

Returns

  • fx_lon (array-like) – Frequencies for longitude or cyclic axis. Units are the inverse of dx_lon.

  • fx_time (array-like) – Frequencies for time axis. Units are the inverse of the dx_time.

  • C (array-like) – Co-power spectrum.

  • Q (array-like) – Quadrature spectrum.

  • P1 (array-like) – Power spectrum for the first input data.

  • P2 (array-like) – Power spectrum for the second input data.

  • Coh (array-like, optional) – Coherence. Values should range from 0 to 1.

  • Phi (array-like, optional) – Phase difference in degrees.

Notes

The Fourier coefficients are scaled so that total variance is equal to one half the sum of the right-hand coefficients. This is more natural for the real-valued datasets typically used by physical scientists, and matches the convention from Professor Elizabeth Barnes’s objective analysis course notes. This differs from the numpy convention, which scales the coefficients so that total variance is equal to the sum of squares of all coefficients, or twice the right-hand coefficients.

Windowing is carried out by applying the wintype weights to successive time segments of length nperseg (overlapping by one half the window length), taking spectral decompositions of each weighted segment, then taking the average of the result for all segments. Note that non-boxcar windowing reduces the total power amplitude and results in loss of information. It may often be preferable to follow the example of [RH91] and smooth in frequency space with a Gaussian filter after the decomposition has been carried out.

The below example shows that the extent of power reduction resulting from non-boxcar windowing depends on the character of the signal.

>>> import numpy as np
>>> import climopy as climo
>>> state = np.random.RandomState(51423)
>>> w = climo.window(200, 'hanning')
>>> y1 = np.sin(np.arange(0, 8 * np.pi - 0.01, np.pi / 25)) # basic signal
>>> y2 = state.rand(200) # complex signal
>>> for y in (y1, y2):
...     yvar = y.var()
...     Y = (np.abs(np.fft.fft(y)[1:] / y.size) ** 2).sum()
...     Yw = (np.abs(np.fft.fft(y * w)[1:] / y.size) ** 2).sum()
...     print('Boxcar', Y / yvar)
...     print('Hanning', Yw / yvar)
Boxcar 1.0
Hanning 0.375
Boxcar 0.9999999999999999
Hanning 0.5728391743988162

References

RH91(1,2)

William J. Randel and Isaac M. Held. Phase Speed Spectra of Transient Eddy Fluxes and Critical Layer Absorption. Journal of the Atmospheric Sciences, 48(5):688–697, March 1991. doi:10.1175/1520-0469(1991)048<0688:PSSOTE>2.0.CO;2.