Main Content

modwtLayer

Maximal overlap discrete wavelet transform (MODWT) layer

    Description

    A MODWT layer computes the MODWT and MODWT multiresolution analysis (MRA) of the input. Use of this layer requires Deep Learning Toolbox™.

    Creation

    Description

    layer = modwtLayer creates a MODWT layer. By default, the layer computes the MODWTMRA to level 5 using the Daubechies least-asymmetric wavelet with four vanishing moments ('sym4') .

    The input to modwtLayer must be a dlarray (Deep Learning Toolbox) object in "CBT" format. The size of the time dimension of the tensor input must be greater than or equal to 2Level, where Level is the transform level of the MODWT. modwtLayer formats the output as "SCBT". For more information, see Layer Output Format.

    Note

    The object initializes the weights internally for use as wavelet filters in the MODWT. It is not recommended to initialize the weights directly.

    example

    layer = modwtLayer(Name=Value) creates a MODWT layer with properties specified by name-value arguments. For example, layer = modwtLayer(Wavelet="haar") creates a MODWT layer that uses the Haar wavelet. You can specify the wavelet and the level of decomposition, among others.

    Properties

    expand all

    MODWT

    This property is read-only.

    Name of an orthogonal wavelet used in the MODWT, specified as a character vector or a string scalar.

    Orthogonal wavelets are designated as type 1 wavelets in the wavelet manager. Valid built-in orthogonal wavelet families begin with 'haar', 'dbN', 'fkN', 'coifN', 'blN', 'hanSR.LP', 'symN', 'vaid', or 'beyl'. Use waveinfo with the wavelet family short name to see supported values for any numeric suffixes and how to interpret those values. For example, waveinfo("han").

    For a wavelet specified by wname, the associated lowpass and highpass filters Lo and Hi, respectively, are [~,~,Lo,Hi] = wfilters(wname).

    Data Types: char | string

    This property is read-only.

    Initial wavelet filter pair, specified as a pair of even-length real-valued vectors. The lengths of the vectors must be equal. LowpassFilter and HighpassFilter must correspond to the lowpass and highpass filters, respectively, associated with an orthogonal wavelet. You can use isorthwfb to determine orthogonality.

    [~,~,Lo,Hi] = wfilters("db2");
    [tf,checks] = isorthwfb(Lo,Hi);
    If unspecified, both filters default to [] and modwtLayer uses Wavelet to determine the filters used in MODWT.

    You cannot specify both a wavelet name and a wavelet filter pair.

    Example: layer = modwtLayer('LowpassFilter',Lo,'HighpassFilter',Hi)

    Data Types: single | double

    This property is read-only.

    Transform level to compute the MODWT, specified as a positive integer less than or equal to floor(log2(N)), where N is the size of the layer input in the time dimension.

    Data Types: single | double

    This property is read-only.

    Boundary condition to use in the computation of the MODWT, specified as one of these:

    • "periodic" — The signal is extended periodically along the time dimension. The number of wavelet coefficients equals the size of the signal in the time dimension.

    • "reflection" — The signal is reflected symmetrically along the time dimension at the terminal end before computing the MODWT. The number of wavelet coefficients returned is twice the length of the input signal.

    This property is read-only.

    Selected levels for modwtLayer to output, specified as a vector of positive integers less than or equal to Level.

    Data Types: single | double

    This property is read-only.

    Include lowpass coefficients, specified as a numeric or logical 1 (true) or 0 (false). If specified as true, the MODWT layer includes the Levelth level lowpass (scaling) coefficients in the MODWT, or Levelth level smooth in the MODWTMRA.

    Data Types: logical

    This property is read-only.

    Aggregate selected levels, specified as a numeric or logical 1 (true) or 0 (false). If specified as true, the MODWT layer aggregates the selected levels and lowpass level (if IncludeLowpass is true) of each input channel by summation. If AggregateLevels is true, the size of the output in the spatial dimension is 1. For more information, Compare modwtLayer Output with modwt and modwtmra Outputs.

    Data Types: logical

    This property is read-only.

    Algorithm modwtLayer uses to compute the output, specified as one of these:

    • "MODWTMRA" — Compute the maximal overlap discrete wavelet transform based multiresolution analysis.

    • "MODWT" — Compute the wavelet coefficients of the maximal overlap discrete wavelet transform.

    For more information, see Comparing MODWT and MODWTMRA.

    Layer

    Multiplier for weight learning rate, specified as a nonnegative scalar. If not specified, this property defaults to zero, resulting in weights that do not update with training. You can also set this property using the setLearnRateFactor (Deep Learning Toolbox) function.

    The learnable parameter 'Weights' in modwtLayer is a two-row matrix of the current filter pair. The first row is the lowpass filter and the second row is the highpass filter. By default, the weights are the lowpass and highpass filters associated with the default wavelet and do not update.

    Data Types: single | double

    Layer name, specified as a character vector or a string scalar. For Layer array input, the trainNetwork, assembleNetwork, layerGraph, and dlnetwork functions automatically assign names to layers with the name ''.

    Data Types: char | string

    This property is read-only.

    Number of inputs of the layer. This layer accepts a single input only.

    Data Types: double

    This property is read-only.

    Input names of the layer. This layer accepts a single input only.

    Data Types: cell

    This property is read-only.

    Number of outputs of the layer. This layer has a single output only.

    Data Types: double

    This property is read-only.

    Output names of the layer. This layer has a single output only.

    Data Types: cell

    Examples

    collapse all

    Create a MODWT layer to compute the multiresolution analysis for the input signal. Use a coiflet wavelet with order 5. Set the transform level to 8. Only keep the details at levels 3, 5, and 7, and the approximation.

    layer = modwtLayer(Wavelet="coif5",Level=8, ...
        SelectedLevels=[3,5,7],Name="MODWT");

    Create a dlnetwork object containing a sequence input layer, a MODWT layer, and an LSTM layer. For a level-8 decomposition, set the minimum sequence length to 2^8 samples. To work with an LSTM layer, a flatten layer is also needed before the LSTM layer to collapse the spatial dimension into the channel dimension.

    mLength=2^8;
    sqLayer = sequenceInputLayer(1,Name="input",MinLength=mLength);
    layers = [sqLayer
        layer
        flattenLayer
        lstmLayer(10,Name="LSTM")
        ];
    dlnet = dlnetwork(layers);

    Run a batch of 10 random single-channel signals through the dlnetwork object. Inspect the size and dimensions of the output. The flatten layer has collapsed the spatial dimension.

    dataout = dlnet.forward(dlarray(randn(1,10,2000,'single'),'CBT'));
    size(dataout)
    ans = 1×3
    
              10          10        2000
    
    
    dims(dataout)
    ans = 
    'CBT'
    

    Load the Espiga3 electroencephalogram (EEG) dataset. The data consists of 23 channels of EEG sampled at 200 Hz. There are 995 samples in each channel. Save the multisignal as a dlarray, specifying the dimensions in order. dlarray permutes the array dimensions to the "CBT" shape expected by a deep learning network.

    load Espiga3
    [N,nch] = size(Espiga3);
    x = dlarray(Espiga3,"TCB");

    Use modwt and modwtmra to obtain the MODWT and MRA of the multisignal down to level 6. By default, modwt and modwtmra use the sym4 wavelet.

    lev = 6;
    wt = modwt(Espiga3,lev);
    mra = modwtmra(wt);

    Compare with modwt

    Create a MODWT layer that can be used with the data. Set the transform level to 6. Specify the layer to use MODWT to compute the output. By default, the layer uses the sym4 wavelet.

    mlayer = modwtLayer(Level=lev,Algorithm="MODWT");

    Create a two-layer dlnetwork object containing a sequence input layer and the MODWT layer you just created. Treat each channel as a feature. For a level-6 decomposition, set the minimum sequence length to 2^6.

    mLength = mlayer.Level;
    sqInput = sequenceInputLayer(nch,MinLength=2^mLength);
    layers = [sqInput
        mlayer];
    dlnet = dlnetwork(layers);

    Run the EEG data through the forward method of the network.

    dataout = forward(dlnet,x);

    The modwt and modwtmra functions return the MODWT and MRA of a multichannel signal as a 3-D array. The first, second, and third dimensions of the array correspond to the wavelet decomposition level, signal length, and channel, respectively. Convert the network output to a numeric array. Permute the dimensions of the network output to match the function output. Compare the network output with the modwt output.

    q = extractdata(dataout);
    q = permute(q,[1 4 2 3]);
    max(abs(q(:)-wt(:)))
    ans = 8.4402e-05
    

    Choose a MODWT result from modwtLayer. Compare with the corresponding channel in the EEG data. Plot each level of the modwtLayer output. Different levels contain information about the signal in different frequency ranges. The levels are not time aligned with the original signal because the layer uses the MODWT algorithm.

    channel = 10;
    t = 100:400;
    subplot(lev+2,1,1)
    plot(t,Espiga3(t,channel))
    ylabel("Original EEG")
    for k=2:lev+1
        subplot(lev+2,1,k)
        plot(t,q(k-1,t,channel))
        ylabel(["Level ",k-1," of MODWT"])
    end
    subplot(lev+2,1,lev+2)
    plot(t,q(lev+1,t,channel))
    ylabel(["Scaling","Coefficients","of MODWT"])
    set(gcf,Position=[0 0 500 700])

    Figure contains 8 axes objects. Axes object 1 contains an object of type line. Axes object 2 contains an object of type line. Axes object 3 contains an object of type line. Axes object 4 contains an object of type line. Axes object 5 contains an object of type line. Axes object 6 contains an object of type line. Axes object 7 contains an object of type line. Axes object 8 contains an object of type line.

    Compare with modwtmra

    Create a second network similar to the first network, except this time specify that modwtLayer use the MODWTMRA algorithm and aggregate the fourth, fifth, and sixth levels. Do not include the lowpass level in the aggregation.

    sLevels = [4 5 6];
    mlayer = modwtLayer(Level=lev, ...
        SelectedLevels=sLevels, ...
        IncludeLowpass=0, ...
        AggregateLevels=1);
    layers = [sqInput
        mlayer];
    dlnet2 = dlnetwork(layers);

    Run the EEG data through the forward method of the network. Convert the network output to a numeric array. Permute the dimensions as done previously.

    dataout = forward(dlnet2,x);
    q = extractdata(dataout);
    q = permute(q,[1 4 3 2]);

    Aggregate the fourth, fifth, and sixth levels of the MRA. Compare with the network output.

    mraAggregate = sum(mra(sLevels,:,:));
    max(abs(q(:)-mraAggregate(:)))
    ans = 2.1036e-04
    

    Inspect a MODWTMRA result from the layer. Compare with the corresponding channel in the EEG data. By choosing only the fourth, fifth, and six levels, and not including the lowpass component, the layer removes several high and low frequency components from the signal. The transformed signal is smoother than the original signal and the low frequency components are removed so that the offset is closer to 0. The output is time aligned with the original signal because the layer uses the default MODWTMRA algorithm. Depending on your goal, preserving time alignment can be useful.

    channel = 10;
    t = 100:400;
    figure
    hold on
    plot(t, Espiga3(t,channel))
    plot(t,q(1,t,1,channel))
    hold off
    legend(["Original EEG", "Layer Output"], ...
        Location="northwest")

    Figure contains an axes object. The axes object contains 2 objects of type line. These objects represent Original EEG, Layer Output.

    This example demonstrates the differences between the MODWT and MODWTMRA. The MODWT partitions a signal's energy across detail coefficients and scaling coefficients. The MODWTMRA projects a signal onto wavelet subspaces and a scaling subspace.

    Choose the sym6 wavelet. Load and plot an electrocardiogram (ECG) signal. The sampling frequency for the ECG signal is 180 hertz. The data are taken from Percival and Walden (2000), p.125 (data originally provided by William Constantine and Per Reinhall, University of Washington).

    load wecg
    t = (0:numel(wecg)-1)/180;
    wv = 'sym6';
    plot(t,wecg)
    grid on
    title(['Signal Length = ',num2str(numel(wecg))])
    xlabel('Time (s)')
    ylabel('Amplitude')

    Figure contains an axes object. The axes object with title Signal Length = 2048 contains an object of type line.

    Take the MODWT of the signal.

    wtecg = modwt(wecg,wv);

    The input data are samples of a function f(x) evaluated at N time points. The function can be expressed as a linear combination of the scaling function ϕ(x) and wavelet ψ(x)at varying scales and translations: f(x)=k=0N-1ck2-J0/2ϕ(2-J0x-k)+j=1J0fj(x), where fj(x)=k=0N-1dj,k2-j/2ψ(2-jx-k) and J0 is the number of levels of wavelet decomposition. The first sum is the coarse scale approximation of the signal, and the fj(x) are the details at successive scales. MODWT returns the N coefficients {ck}and the (J0×N) detail coefficients {dj,k} of the expansion. Each row in wtecg contains the coefficients at a different scale.

    When taking the MODWT of a signal of length N, there are floor(log2(N)) levels of decomposition by default. Detail coefficients are produced at each level. Scaling coefficients are returned only for the final level. In this example, N=2048, J0=floor(log2(2048))=11, and the number of rows in wtecg is J0+1=11+1=12.

    The MODWT partitions the energy across the various scales and scaling coefficients: ||X||2=j=1J0||Wj||2+||VJ0||2, where X is the input data, Wj are the detail coefficients at scale j, and VJ0 are the final-level scaling coefficients.

    Compute the energy at each scale, and evaluate their sum.

    energy_by_scales = sum(wtecg.^2,2);
    Levels = {'D1';'D2';'D3';'D4';'D5';'D6';...
        'D7';'D8';'D9';'D10';'D11';'A11'};
    energy_table = table(Levels,energy_by_scales);
    disp(energy_table)
        Levels     energy_by_scales
        _______    ________________
    
        {'D1' }         14.063     
        {'D2' }         20.612     
        {'D3' }         37.716     
        {'D4' }         25.123     
        {'D5' }         17.437     
        {'D6' }         8.9852     
        {'D7' }         1.2906     
        {'D8' }         4.7278     
        {'D9' }         12.205     
        {'D10'}         76.428     
        {'D11'}         76.268     
        {'A11'}         3.4192     
    
    energy_total = varfun(@sum,energy_table(:,2))
    energy_total=table
        sum_energy_by_scales
        ____________________
    
               298.28       
    
    

    Confirm the MODWT is energy-preserving by computing the energy of the signal and comparing it with the sum of the energies over all scales.

    energy_ecg = sum(wecg.^2);
    max(abs(energy_total.sum_energy_by_scales-energy_ecg))
    ans = 7.4402e-10
    

    Take the MODWTMRA of the signal.

    mraecg = modwtmra(wtecg,wv);

    MODWTMRA returns the projections of the function f(x) onto the various wavelet subspaces and final scaling space. That is, MODWTMRA returns k=0N-1ck2-J0/2ϕ(2-J0x-k) and the J0-many {fj(x)}evaluated at N time points. Each row in mraecg is a projection of f(x) onto a different subspace. This means the original signal can be recovered by adding all the projections. This is not true in the case of the MODWT. Adding the coefficients in wtecg will not recover the original signal.

    Choose a time point, add the projections of f(x) evaluated at that time point, and compare with the original signal.

    time_point = 1000;
    abs(sum(mraecg(:,time_point))-wecg(time_point))
    ans = 3.0846e-13
    

    Confirm that, unlike MODWT, MODWTMRA is not an energy-preserving transform.

    energy_ecg = sum(wecg.^2);
    energy_mra_scales = sum(mraecg.^2,2);
    energy_mra = sum(energy_mra_scales);
    max(abs(energy_mra-energy_ecg))
    ans = 115.7053
    

    The MODWTMRA is a zero-phase filtering of the signal. Features will be time-aligned. Show this by plotting the original signal and one of its projections. To better illustrate the alignment, zoom in.

    plot(t,wecg,'b')
    hold on
    plot(t,mraecg(4,:),'-')
    hold off
    grid on
    xlim([4 8])
    legend('Signal','Projection','Location','northwest')
    xlabel('Time (s)')
    ylabel('Amplitude')

    Figure contains an axes object. The axes object contains 2 objects of type line. These objects represent Signal, Projection.

    Make a similar plot using the MODWT coefficients at the same scale. Features will not be time-aligned. The MODWT is not a zero-phase filtering of the input.

    plot(t,wecg,'b')
    hold on
    plot(t,wtecg(4,:),'-')
    hold off
    grid on
    xlim([4 8])
    legend('Signal','Coefficients','Location','northwest')
    xlabel('Time (s)')
    ylabel('Amplitude')

    Figure contains an axes object. The axes object contains 2 objects of type line. These objects represent Signal, Coefficients.

    More About

    expand all

    Version History

    Introduced in R2022b

    See Also

    Apps

    Functions

    Objects