wwz_psd (pyleoclim.utils.spectral.wwz_psd)

pyleoclim.utils.spectral.wwz_psd(ys, ts, freq=None, freq_method='log', freq_kwargs=None, tau=None, c=0.001, nproc=8, detrend=False, sg_kwargs=None, gaussianize=False, standardize=False, Neff=3, anti_alias=False, avgs=2, method='Kirchner_numba', wwa=None, wwz_Neffs=None, wwz_freq=None)[source]

Returns the power spectral density (PSD) of a timeseries using the Weighted Wavelet Z-transform

The Weighted wavelet Z-transform (WWZ) is based on Morlet wavelet spectral estimation, using least squares minimization to suppress the energy leakage caused by the data gaps. WWZ does not rely on interpolation or detrending, and is appropriate for unevenly-spaced datasets. In particular, we use the variant of Kirchner & Neal (2013), in which basis rotations mitigate the numerical instability that occurs in pathological cases with the original algorithm (Foster, 1996). The WWZ method has one adjustable parameter, a decay constant c that balances the time and frequency resolutions of the analysis. The smaller this constant is, the sharper the peaks.

We choose the value 1e-3 to obtain smooth spectra that lend themselves to better scaling exponent estimation, while still capturing the main periodicities.

Note that scalogram applications use the larger value (8π2)−1, justified elsewhere (Foster, 1996).

Parameters

ys (array) – a time series, NaNs will be deleted automatically
ts (array) – the time points, if ys contains any NaNs, some of the time points will be deleted accordingly
freq (array) – vector of frequency
freq_method (str, {'log', 'lomb_scargle', 'welch', 'scale', 'nfft'}) –
Method to generate the frequency vector if not set directly. The following options are avialable:
- ’log’ (default)
- ’lomb_scargle’
- ’welch’
- ’scale’
- ’nfft’
See pyleoclim.utils.wavelet.make_freq_vector() for details
freq_kwargs (dict) – Arguments for the method chosen in freq_method. See specific functions in pyleoclim.utils.wavelet for details
tau (array) – the evenly-spaced time vector for the analysis, namely the time shift for wavelet analysis
c (float) – the decay constant that will determine the analytical resolution of frequency for analysis, the smaller the higher resolution; the default value 1e-3 is good for most of the spectral analysis cases
nproc (int) – the number of processes for multiprocessing
detrend (str, {None, 'linear', 'constant', 'savitzy-golay'}) –
available methods for detrending, including
- None: the original time series is assumed to have no trend;
- ’linear’: a linear least-squares fit to ys is subtracted;
- ’constant’: the mean of ys is subtracted
- ’savitzy-golay’: ys is filtered using the Savitzky-Golay filters and the resulting filtered series is subtracted from y.
sg_kwargs (dict) – The parameters for the Savitzky-Golay filters. See pyleoclim.utils.filter.savitzky_golay() for details.
gaussianize (bool) – If True, gaussianizes the timeseries
standardize (bool) – If True, standardizes the timeseries
method (string, {'Foster', 'Kirchner', 'Kirchner_f2py', 'Kirchner_numba'}) –
available specific implementation of WWZ, including
- ’Foster’: the original WWZ method;
- ’Kirchner’: the method Kirchner adapted from Foster;
- ’Kirchner_f2py’: the method Kirchner adapted from Foster, implemented with f2py for acceleration;
- ’Kirchner_numba’: the method Kirchner adapted from Foster, implemented with Numba for acceleration (default);
Neff (int) – effective number of points
anti_alias (bool) – If True, uses anti-aliasing
avgs (int) – flag for whether spectrum is derived from instantaneous point measurements (avgs<>1) OR from measurements averaged over each sampling interval (avgs==1)
wwa (array) – the weighted wavelet amplitude, returned from pyleoclim.utils.wavelet.wwz
wwz_Neffs (array) – the matrix of effective number of points in the time-scale coordinates, returned from pyleoclim.utils.wavelet.wwz
wwz_freq (array) – the returned frequency vector from pyleoclim.utils.wavelet.wwz

Returns

res – a namedtuple that includes below items

psdarray: power spectral density
freqarray: vector of frequency

Return type

namedtuple