Spectral Functions¶
This module allows analysis in the frequency domain
-
pyleoclim.Spectral.
ar1_fit
(ys, ts=None, detrend=None, params=['default', 4, 0, 1])¶ Returns the lag-1 autocorrelation from ar1 fit OR persistence from tauest.
- Args:
ys (array): the time series ts (array): the time axis of that series detrend (str): ‘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.
- params (list): The paramters for the Savitzky-Golay filters. The first parameter
corresponds to the window size (default it set to half of the data) while the second parameter correspond to the order of the filter (default is 4). The third parameter is the order of the derivative (the default is zero, which means only smoothing.)
- Returns:
g (float): lag-1 autocorrelation coefficient (for evenly-spaced time series) OR estimated persistence (for unevenly-spaced time series)
-
pyleoclim.Spectral.
ar1_sim
(ys, n, p, ts=None, detrend=False, params=['default', 4, 0, 1])¶ Produce p realizations of an AR1 process of length n with lag-1 autocorrelation g calculated from ys and ts
- Args:
ys (array): a time series n, p (int): dimensions as n rows by p columns ts (array): the time axis of that series detrend (str): ‘no’ - 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.
- params (list): The paramters for the Savitzky-Golay filters. The first parameter
corresponds to the window size (default it set to half of the data) while the second parameter correspond to the order of the filter (default is 4). The third parameter is the order of the derivative (the default is zero, which means only smoothing.)
- Returns:
red (matrix): n rows by p columns matrix of an AR1 process
-
pyleoclim.Spectral.
wwz
(ys, ts, tau=None, freqs=None, c=0.012665147955292222, Neff=3, Neff_coi=3, nMC=200, nproc=8, detrend=False, params=['default', 4, 0, 1], gaussianize=False, standardize=True, method='Kirchner_f2py', len_bd=0, bc_mode='reflect', reflect_type='odd')¶ Return the weighted wavelet amplitude (WWA) with phase, AR1_q, and cone of influence, as well as WT coefficients
- Args:
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 tau (array): the evenly-spaced time points freqs (array): vector of frequency c (float): the decay constant, the default value 1/(8*np.pi**2) is good for most of the cases Neff (int): effective number of points nMC (int): the number of Monte-Carlo simulations nproc (int): the number of processes for multiprocessing detrend (str): ‘no’ - 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.
- params (list): The paramters for the Savitzky-Golay filters. The first parameter
corresponds to the window size (default it set to half of the data) while the second parameter correspond to the order of the filter (default is 4). The third parameter is the order of the derivative (the default is zero, which means only smoothing.)
- method (str): ‘Foster’ - the original WWZ method;
‘Kirchner’ - the method Kirchner adapted from Foster; ‘Kirchner_f2py’ - the method Kirchner adapted from Foster with f2py
len_bd (int): the number of the ghost grids want to creat on each boundary bc_mode (str): see np.lib.pad() reflect_type (str): see np.lib.pad()
- Returns:
wwa (array): the weighted wavelet amplitude. AR1_q (array): AR1 simulations coi (array): cone of influence freqs (array): vector of frequency tau (array): the evenly-spaced time points, namely the time shift for wavelet analysis Neffs (array): the matrix of effective number of points in the time-scale coordinates coeff (array): the wavelet transform coefficents
-
pyleoclim.Spectral.
wwz_psd
(ys, ts, freqs=None, tau=None, c=0.001, nproc=8, nMC=200, detrend=False, params=['default', 4, 0, 1], gaussianize=False, standardize=True, Neff=3, anti_alias=False, avgs=2, method='Kirchner_f2py')¶ Return the psd of a timeseries directly using wwz method.
- Args:
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 freqs (array): vector of frequency tau (array): the evenly-spaced time points, namely the time shift for wavelet analysis c (float): the decay constant, the default value 1e-3 is good for most of the cases nproc (int): the number of processes for multiprocessing nMC (int): the number of Monte-Carlo simulations detrend (str): ‘no’ - 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.
- params (list): The paramters for the Savitzky-Golay filters. The first parameter
corresponds to the window size (default it set to half of the data) while the second parameter correspond to the order of the filter (default is 4). The third parameter is the order of the derivative (the default is zero, which means only smoothing.)
gaussianize (bool): If True, gaussianizes the timeseries standardize (bool): If True, standardizes the timeseries method (str): ‘Foster’ - the original WWZ method;
‘Kirchner’ - the method Kirchner adapted from Foster; ‘Kirchner_f2py’ - the method Kirchner adapted from Foster with f2py
Neff (int): anti_alias (bool): If True, uses anti-aliasing avgs (int):
- Returns:
psd (array): power spectral density freqs (array): vector of frequency psd_ar1_q95 (array): the 95% quantile of the psds of AR1 processes psd_ar1 (array): the psds of AR1 processes
-
pyleoclim.Spectral.
xwt
(ys1, ts1, ys2, ts2, tau=None, freqs=None, c=0.012665147955292222, Neff=3, Neff_coi=6, nproc=8, detrend=False, params=['default', 4, 0, 1], gaussianize=False, standardize=True, method='Kirchner_f2py')¶ Return the cross-wavelet transform of two time series.
- Args:
ys1, ys2 (array): the two time series ts1, ts2 (array): the time axis of the two time series tau (array): the evenly-spaced time points freqs (array): vector of frequency c (float): the decay constant, the default value 1/(8*np.pi**2) is good for most of the cases Neff (int): effective number of points nproc (int): the number of processes for multiprocessing detrend (str): ‘no’ - 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.
- params (list): The paramters for the Savitzky-Golay filters. The first parameter
corresponds to the window size (default it set to half of the data) while the second parameter correspond to the order of the filter (default is 4). The third parameter is the order of the derivative (the default is zero, which means only smoothing.)
gaussianize (bool): If True, gaussianizes the timeseries standardize (bool): If True, standardizes the timeseries method (str): ‘Foster’ - the original WWZ method;
‘Kirchner’ - the method Kirchner adapted from Foster; ‘Kirchner_f2py’ - the method Kirchner adapted from Foster with f2py
- Returns:
xw_amplitude (array): the cross wavelet amplitude xw_phase (array): the cross wavelet phase freqs (array): vector of frequency tau (array): the evenly-spaced time points AR1_q (array): AR1 simulations coi (array): cone of influence
-
pyleoclim.Spectral.
xwc
(ys1, ts1, ys2, ts2, smooth_factor=0.25, tau=None, freqs=None, c=0.012665147955292222, Neff=3, nproc=8, detrend=False, nMC=200, params=['default', 4, 0, 1], gaussianize=False, standardize=True, method='Kirchner_f2py')¶ Return the cross-wavelet coherence of two time series.
- Args:
ys1, ys2 (array): the two time series ts1, ts2 (array): the time axis of the two time series tau (array): the evenly-spaced time points freqs (array): vector of frequency c (float): the decay constant, the default value 1/(8*np.pi**2) is good for most of the cases Neff (int): effective number of points nproc (int): the number of processes for multiprocessing nMC (int): the number of Monte-Carlo simulations detrend (str): ‘no’ - 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.
- params (list): The paramters for the Savitzky-Golay filters. The first parameter
corresponds to the window size (default it set to half of the data) while the second parameter correspond to the order of the filter (default is 4). The third parameter is the order of the derivative (the default is zero, which means only smoothing.)
gaussianize (bool): If True, gaussianizes the timeseries standardize (bool): If True, standardizes the timeseries method (str): ‘Foster’ - the original WWZ method;
‘Kirchner’ - the method Kirchner adapted from Foster; ‘Kirchner_f2py’ - the method Kirchner adapted from Foster with f2py
- Returns:
- res (dict): contains the cross wavelet coherence, cross-wavelet phase,
vector of frequency, evenly-spaced time points, AR1 sims, cone of influence
-
pyleoclim.Spectral.
plot_wwa
(wwa, freqs, tau, AR1_q=None, coi=None, levels=None, tick_range=None, yticks=None, yticks_label=None, ylim=None, xticks=None, xlabels=None, figsize=[20, 8], clr_map='OrRd', cbar_drawedges=False, cone_alpha=0.5, plot_signif=False, signif_style='contour', title=None, plot_cbar=True, plot_cone=False, ax=None, xlabel='Year CE', ylabel='Period (years)', cbar_orientation='vertical', cbar_pad=0.05, cbar_frac=0.15, cbar_labelsize=None)¶ Plot the wavelet amplitude
- Args:
wwa (array): the weighted wavelet amplitude. freqs (array): vector of frequency tau (array): the evenly-spaced time points, namely the time shift for wavelet analysis AR1_q (array): AR1 simulations coi (array): cone of influence levels (array): levels of values to plot tick_range (array): levels of ticks to show on the colorbar yticks (list): ticks on y-axis ylim (list): limitations for y-axis xticks (list): ticks on x-axis figsize (list): the size for the figure clr_map (str): the name of the colormap cbar_drawedges (bool): whether to draw edges on the colorbar or not cone_alpha (float): the alpha value for the area covered by cone of influence plot_signif (bool): plot 95% significant area or not signif_style (str): plot 95% significant area with contour or shade title (str): Title for the plot plot_cbar (bool): Plot the color scale bar plot_cone (bool): plot cone of influence ax: Return as axis instead of figure (useful to integrate plot into a subplot) xlabel (str): The x-axis label ylabel (str): The y-axis label cbar_pad (float): the pad for the colorbar cbar_frac (float): the frac for the colorbar cbar_labelsize (float): the font size of the colorbar label
- Returns:
fig (figure): the 2-D plot of wavelet analysis
-
pyleoclim.Spectral.
plot_coherence
(res_xwc, pt=0.5, levels=None, tick_range=None, basey=2, yticks=None, ylim=None, xticks=None, xlabels=None, figsize=[20, 8], clr_map='OrRd', skip_x=5, skip_y=5, scale=30, width=0.004, cbar_drawedges=False, cone_alpha=0.5, plot_signif=False, signif_style='contour', title=None, plot_cone=False, ax=None, xlabel='Year', ylabel='Period', cbar_orientation='vertical', cbar_pad=0.05, cbar_frac=0.15, cbar_labelsize=None)¶ Plot the wavelet coherence
- Args:
- res_xwc (dict): contains the cross wavelet coherence, cross-wavelet phase,
vector of frequency, evenly-spaced time points, AR1 sims, cone of influence. See xwc
pt (float): plot arrows above pt value levels (array): levels of values to plot tick_range (array): levels of ticks to show on the colorbar basey (int): log base for y. Default is 2. yticks (list): ticks on y-axis ylim (list): limitations for y-axis xticks (list): ticks on x-axis xlabels (list): List of labels for the x-axis ticks figsize (list): the size for the figure clr_map (str): the name of the colormap skip_x, skip_y (float): plot every x,y points scale (int): Scale factor for arrows width (float): Width of the arrows cbar_drawedges (bool): whether to draw edges on the colorbar or not cone_alpha (float): the alpha value for the area covered by cone of influence plot_signif (bool): plot 95% significant area signif_style (str): plot 95% significant area with contour or shade title (str): Add a title to the plot plot_cone (bool): plot cone of influence ax: Return as axis instead of figure (useful to integrate plot into a subplot) xlabel (str): The x-axis label ylabel (str): The y-axis label cbar_orientation (str): the orientation of the colorbar. Default is vertical cbar_pad (float): the pad for the colorbar cbar_frac (float): the frac for the colorbar cbar_labelsize (float): the font size of the colorbar label
- Returns:
fig (figure): the 2-D plot of wavelet analysis
-
pyleoclim.Spectral.
plot_wwadist
(wwa, ylim=None)¶ Plot the distribution of wwa with the 95% quantile line.
- Args:
wwa (array): the weighted wavelet amplitude. ylim (list): limitations for y-axis
- Returns:
fig (figure): the 2-D plot of wavelet analysis
-
pyleoclim.Spectral.
plot_psd
(psd, freqs, lmstyle='-', linewidth=None, color='#3b5b92', ar1_lmstyle='-', ar1_linewidth=None, period_ticks=None, period_tickslabel=None, psd_lim=None, period_lim=None, alpha=1, figsize=[20, 8], label='PSD', plot_ar1=False, psd_ar1_q95=None, title=None, legend=True, psd_ar1_color='#d9544d', ax=None, vertical=False, plot_gridlines=True, period_label='Period (years)', psd_label='Spectral Density', zorder=None)¶ Plot power spectral density
- Args:
psd (array): power spectral density freqs (array): vector of frequency period_ticks (list): ticks for period period_tickslabel (list): Labels for the period ticks psd_lim (list): limits for spectral density axis label (str): the label for the PSD plot_ar1 (bool): plot the ar1 curve psd_ar1_q95 (array): the 95% quantile of the AR1 PSD psd_ar1_color (str): the color for the 95% quantile of the AR1 PSD title (str): the title for the figure period_lim (list): limits for period axis figsize (list): the size for the figure ax (axis): Return as axis instead of figure (useful to integrate plot into a subplot) vertical (bool): plot in vertical layout or not legend (bool): plot legend lmstyle (str): the line style linewidth (float): the line width color (str): Color of the line ar1_lmstyle (str): line style for the AR1 ensemble ar1_linewidth (int): line width for AR1 ensemble period_label (str): the label for period psd_label (str): the label for psd zorder (int): the order of the layer period_tickslabel (str): Label for the period tick. alpha (float): set transparency label (str): Label for the figure plot_gridlines (bool): Plot gridlines period_label (str): Label for the period axis psd_label (str): label for the PSD axis
- Returns:
ax (figure): the 2-D plot of wavelet analysis
-
pyleoclim.Spectral.
plot_summary
(ys, ts, freqs=None, tau=None, c1=0.012665147955292222, c2=0.001, nMC=200, nproc=1, detrend=False, params=['default', 4, 0, 1], gaussianize=False, standardize=True, levels=None, method='Kirchner_f2py', anti_alias=False, period_ticks=None, ts_color=None, ts_style='-o', title=None, ts_ylabel=None, wwa_xlabel=None, wwa_ylabel=None, psd_lmstyle='-', psd_lim=None, font_scale=1.5, period_S_str='beta_I', period_S=[0.125, 0.5], period_L_str='beta_D', period_L=[0.005, 0.05])¶ Plot the time series with the wavelet analysis and psd
- Args:
ys (array): a time series ts (array): time axis of the time series freqs (array): vector of frequency tau (array): the evenly-spaced time points, namely the time shift for wavelet analysis c1 (float): the decay constant (wwz method) c2 (float): the decay constant (wwz_psd method) nMC(int): Number of Monte-Carlo simulations nproc (int): fake argument, just for convenience detrend (str): ‘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.
- params (list): The paramters for the Savitzky-Golay filters. The first parameter
corresponds to the window size (default it set to half of the data) while the second parameter correspond to the order of the filter (default is 4). The third parameter is the order of the derivative (the default is zero, which means only smoothing.)
gaussianize (bool): If True, gaussianizes the timeseries standardize (bool): If True, standardizes the timeseries levels (array): levels of values to plot method (str): method for the WWZ transform. Default is Kirchner_f2py anti_alias (bool): If True, uses anti-aliasing period_ticks (list): ticks for period ts_color (str): the color for the time series curve ts_style (str): Style for the line title (str): the title for the time series plot ts_ylabel (str): label for y-axis in the time series plot wwa_xlabel (str): label for x-axis in the wwa plot wwa_ylabel (str): label for y-axis in the wwa plot psd_lmstyle (str): the line style in the psd plot psd_lim (list): the limits for psd font_scale (float): Scaling factor for the font on the plot period_S, period_L (list): the ranges for beta estimation period_S_str, period_L_str (str): String for beta estimation
- Returns:
fig (figure): the summary plot
-
pyleoclim.Spectral.
calc_plot_psd
(ys, ts, ntau=501, dcon=0.001, standardize=False, anti_alias=False, plot_fig=True, method='Kirchner_f2py', nproc=8, period_ticks=[0.5, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1000], color=None, figsize=[10, 6], font_scale=2, lw=3, label='PSD', zorder=None, xlim=None, ylim=None, loc='upper right', bbox_to_anchor=None)¶ Calculate the PSD and plot the result
- Args:
ys (array): a time series ts (array): time axis of the time series natu (int): the length of tau, the evenly-spaced time points,
namely the time shift for wavelet analysis
dcon (float): the decay constant standardize(bool): perform standardization or not anti_alias(bool): perform anti-alising procedure or not plot_fig (bool): plot the result or not method (str): the WWZ method to use nproc (int): the number of threads period_ticks (list): List of period ticks color (str): set color figsize (list): Size of the figure font_scale(float): Scale of the font lw (float): For plotting purposes label (str): Labeld for the y-axis zorder (int): the order of the layer xlim (list): x-axis limits ylim (list): y-axis limits loc (str): location for the legend bbox_to_anchor (list): gives a great degree of control for manual
legend placement. For example, if you want your axes legend located at the figure’s top right-hand corner instead of the axes’ corner, simply specify the corner’s location, and the coordinate system of that location
- Returns:
fig (figure): the summary plot psd (array): the spectral density freqs (array): the frequency vector