Wavelet Transform¶

Matrix-based computation of discrete wavelet transform: 1. Construct the wavelet filter

class mrpod.wavelet_transform.CompositeFilter(g=None, wavelet='D(8)')¶

Generate composite filter Composite filter generated from a given wavelet for a specific decomposition level and all the scales involved.

Parameters:

g : 1d array, optional

Scaling (lowpass) filter for calculating the wavelet filter.

wavelet : str, optional

Name of the scaling filter (g). Default is ‘D(8)’. Built-in options are: ‘Haar’, ‘D(4)’, ‘D(8)’, ‘D(10)’, ‘D(12)’, ‘LA(8)’, ‘LA(12)’, ‘LA(16)’

‘D(8)’: Daubechies standard wavelet with 8 elements.
‘LA(8)’: Least-asymmetric variant of the Daubechies wavelet with 8 elements.

Other wavelets can be found in the following sources:

Wavelet Methods for Time Series Analysis by Percival and Walden.
Import from the pywt package using pywt.Wavelet(). Note that only half of the wavelet length is indicated in the name of the wavelets. E.g., the equivalent of ‘D(8)’ and ‘LA(8)’ in pywt are ‘db4’ and ‘sym4’.

Notes

The generated filters need to be normalized by \(2^{j/2}\) for maximum overlap wavelet transforms. This is taken into account in WaveletTransform.

filter_cascade(J)¶

Populate the collection of filters corresponding to all the j and n in a cascading scheme based on the specified target decomposition level J.

Parameters:	J : int Target decomposition level (or the maximum decomposition level). It should be larger than 1.

max_J(N)¶

Maximum decomposition level for the data series with the given wavelet filter. Although there is technically no upper limit for MODWT, it is still recommended to apply the same criterion as in the case of DWT.

Parameters:	N : int Length of the data series
Returns:	max_dec : int (Recommended) Maximum decomposition level for the data series with the given wavelet filter.

save_filterbank(full_path_write)¶

Save the computed filterbank to the specified local directory.

Parameters:	full_path_write : obj Full path to the file, recommended to use “./filterbank_[filtertype]_[j].pkl” to name the file.

sqd_gain_fcn(j, n, fs=None, max_overlap=False)¶

Squared gain function of a given wavelet filter at subscale n and decomposition level j.

Parameters:	j : int Decomposition level j n : int Index of the scale from a certain decomposition level j, \(n=0,1 \ldots, 2^{j-1}-1\). fs : None, 1d array, optional Frequencies to be used for caclulating the transfer function [0, 1/2). max_overlap : False, bool, optional If True, the output represent the squared gain from MODWT.
Returns:	gain : 1d array Squared gain for the specified filter fs : 1d array Standard frequency range

u_n(n)¶

Filter corresponds to the scale n of a level j, i.e. a selection of g or h.

Parameters:	n : int Index of the scale from a certain decomposition level j, \(n=0,1 \ldots, 2^{j-1}-1\).
Returns:	u_n : 1d array Filter coefficients (either g or h).

class mrpod.wavelet_transform.WaveletTransform(X, j=None, mode='max-overlap', filterbank=None, full_path_filterbank=None)¶

Basic class for discrete wavelet (packet) transform.

Input either data or correlation matrix.

Parameters:

X : ndarray: Input data. Two shapes are admissible: - NxM with N being the sample size and M the total amount of physical coordinates (for 1d wavelet transform) - NxN with N being the sample size (for 2d wavelet transform)
j : int: Target decomposition level. A value is expected if ‘standard’ mode is used.
mode : ‘max-overlap’, str. optional: Two modes of discrete wavelet transform to choose from: - ‘max-overlap’, perform maximum overlap DWT - ‘standard’, perform DWT.
filterbank : None, dict, optional: Precalculated filterbank via CompositeFilter(). It is also possible to input custom filters in the following format: {Node: Coefficients}. Node has to follow the naming convention ‘[j][0]’.
full_path_filterbank : None, obj, optional: Path to the filterbank pickle file created using save_filterbank() in CompositeFilter().

detail_bundle_1d(js, scales)¶

Reconstruct the input data with MODWT at specified j levels and with desired scales, along the axis=0 dimension of the data (i.e., N in an NxM data).

Parameters:	js : 1d array of int The correponding decomposition levels. Different j levels are admissible. scales: 1d array of int All the scales included in the reconstruction. Discrete scales are admissible.
Returns:	B_details : ndarray Reconstructed detail bundle of input data with the dimension of NxM.

Notes

js and scales need to have the same length.

detail_bundle_2d(js, scales)¶

Reconstruct the input data (2d) with MODWPT at specified j and with desired scales.

Parameters:	js : 1d arrray of int The correponding decomposition levels. Different j levels are admissible. scales: 1d array of int All the scales included in the reconstruction. Discrete scales are admissible.
Returns:	K_mat : ndarray Reconstructed input data with the dimension of NxN. T_mat: ndarray Transform matrix used to perform the transform.

filter_matrix(j, n)¶

Convert the composite filter u_j into its matrix form based on the sample size of N.

Parameters:	j : int The decomposition level. n : int The scale in level j. index_W : int Indices of the matrix form of the wavelet filter.
Returns:	u_j_mat : ndarray Composite filter u_j in its matrix form

index_W¶: Matrix conversion indices for data series and wavelet coefficient.

power_spectrum_1d(j, scales)¶

Calculate the approximated power spectrum of the input data based on wavelet_coeff_1d.

Parameters:	j : int The decomposition level. scales: list, 1d array of int All the scales included in the decomposition.
Returns:	power_spectrum : 1d array Power spectrum at specific scales of j. It has a size of len(scales).

power_spectrum_2d(j, scales)¶

Calculate the power spectrum of the input data based on wavelet_coeff_2d.

Parameters:	j : int The decomposition level. scales: list, 1d array of int All the scales included in the decomposition.
Returns:	power_spectrum : 1d array Power spectrum at specific scales of j. It has a size of len(scales).

wavelet_coeff_1d(j, scales)¶

Decompose the input data with MODWPT at specified j and with desired scales, along the axis=0 dimension of the data (i.e., N in an NxM data). It is possible to combine multiple (discrete) scales to achieve desired filtering effect.

Parameters:	j : int The decomposition level. scales: list, 1d array of int All the scales included in the decomposition
Returns:	W_j : ndarray Wavelet coefficients from decomposing input data. It has a dimension of len(scales)xNxM

Notes

Not recommended to set a large number of scales if M is very large
Better to start with a single scale

wavelet_coeff_2d(j, scales)¶

Decompose the input data with MODWT at specified j and with desired scales, along both axes of the data dimension. Only data with a shape of NxN is admissible due to the precomputed Designed for handling cross-correlation matrices.

Parameters:	j : int The decomposition level. scales : list, 1d array of int All the scales included in the decomposition.
Returns:	W_j : ndarray Wavelet coefficients from decomposing input data. It has a dimension of len(scales)xNxN.

mrpod.wavelet_transform.find_scale_index(level, x='0', y='1')¶

Gray code order is used here to generate indices for the scales of each decomposition level in a wavelet packet transform. Either ‘a’ and ‘d’ (approximation and detail) or ‘0’ and ‘1’ are used. E.g., for a level=1 decomposition, the possible combination will be ‘ad’ and ‘da’. For level=2, it will be ‘aa’, ‘ad’, ‘da’, ‘dd’. The indices are also ordered by their corresponding frequency bandpasses.

Parameters:	level : int Dcomposition level for WPT. x : ‘0’, str, optional First index in the gray code. ‘a’ is also generally used. y : ‘1’, str, optional Second index in the gray code. ‘d’ is also generally used.
Returns:	graycode_order : list The list of indices ordered by their corresponding frequencies.

mrpod.wavelet_transform.scale_to_frq(f_sample, j)¶

Convert scales at a given j to their corresponding center frequencies.

Parameters:	f_sample : float Sampling rate of the data. j : int The decomposition level.
Returns:	frq : 1d array Center frequencies of all the scales at a given level j

mrpod.wavelet_transform.time_shift(w_j, L, j, scale)¶

Time shift the wavelet coefficient so that it matches the features in the original signal temporally. Only works if the half length of the wavelet is even and if the wavelet is of the LA type (symlet).

Parameters:	w_j : 1d array Wavelet coefficient. L : int Length of the wavelet used to calculate the wavelet coefficient. j : int Decomposition level. scale : int The specific scale (n) the wavelet coefficient corresponds to.
Returns:	w_j : 1d array Wavelet coefficient corrected for its corresponding time shift

mrpod.wavelet_transform.transfer_fcn(coeff_filter, freq_domain)¶

Transfer function of a given wavelet filter.

Parameters:	coeff_filter : 1d array Coefficients of the filter freq_domain : 1d array Frequencies to be used for calculating the transfer function
Returns:	T_fcn : 1d array Transfer function of the given filter