icwtLayer

Inverse continuous wavelet transform layer

Since R2024b

Description

An ICWT layer computes the inverse continuous wavelet transform of the input. You must have Deep Learning Toolbox™ to use this layer.

Creation

Syntax

layer = icwtLayer

layer = icwtLayer(PropertyName=Value)

Description

layer = icwtLayer creates an inverse continuous wavelet transform (ICWT) layer.

The input to icwtLayer must be a real-valued dlarray (Deep Learning Toolbox) object in the "CBT" or "SCBT" format. The size of the channel ("C") dimension must be even, because icwtLayer assumes the real and imaginary parts of the input are concatenated along the channel dimension.

The output of icwtLayer is real-valued and in "CBT" format.

Note

When you initialize the learnable parameters of icwtLayer, the layer weights are set to the wavelet filters used in the CWT. It is not recommended to initialize the weights directly.

layer = icwtLayer(PropertyName=Value) creates an ICWT layer with properties specified by one or more name-value arguments. For example, layer = icwtLayer(SignalLengh=2048,VoicesPerOctave=14) creates a layer for a signal of length 2048 in the time dimension that uses 14 voices per octave in the ICWT. You can specify multiple name-value arguments.

Note

You cannot use this syntax to set the Weights property.

Properties

CWT

SignalLength — Signal length in samples

Read-only: 1024 (default) | positive integer

This property is read-only.

Signal length in samples, specified as a positive integer greater than or equal to 4. All sequence inputs to icwtLayer are padded to have size SignalLength along the time dimension.

You can set this property when you create the icwtLayer object. After you create the object, this property is read-only.

Data Types: single | double

Wavelet — Analysis wavelet

Read-only: "Morse" (default) | "amor" | "bump"

This property is read-only.

Analysis wavelet used in the ICWT, specified as "Morse", "amor", or "bump", representing the analytic Morse, Morlet (Gabor), and bump wavelet, respectively. The default wavelet is the analytic Morse (3,60) wavelet.

You can set this property when you create the icwtLayer object. After you create the object, this property is read-only.

Threshold — Weight threshold

Read-only: 1e–8 (default) | positive real scalar

This property is read-only.

Weight threshold, specified as a positive real scalar. icwtLayer uses the threshold value to determine the significant values for each of the CWT filters in the wavelet filter bank prior to any weight modification through learning. icwtLayer sets values below the specified threshold to zero and excludes them from learning. The ICWT filters are normalized so that the peak value is 2 for each filter.

• Smaller values of Threshold result in more values being retained from the CWT filters and therefore less weight reduction.

• Larger values of Threshold result in more weight reduction and more divergence between the deep learning ICWT and transforms computed with the full filter bank.

• A threshold less than realmin, the smallest positive normalized floating-point number in double precision, is clipped to realmin for computing significant filter values.

Setting Threshold to a value which results in no values being retained for any individual filter results in an error.

You can set this property when you create the icwtLayer object. After you create the object, this property is read-only.

Data Types: single | double

IncludeLowpass — Include lowpass filter

Read-only: false or 0 (default) | true or 1

This property is read-only.

Include lowpass filter, specified as a numeric or logical 1 (true) or 0 (false). Specify true to include the lowpass (scaling) filter in the ICWT.

You can set this property when you create the icwtLayer object. After you create the object, this property is read-only.

Data Types: logical

VoicesPerOctave — Number of voices per octave

Read-only: 10 (default) | integer between 1 and 48

This property is read-only.

Number of voices per octave used in inverting the CWT, specified as an integer between 1 and 48. The CWT scales are discretized using the specified number of voices per octave. The energy spread of the wavelet in frequency and time automatically determines the minimum and maximum scales.

You can use cwtfreqbounds to determine the frequency limits of the wavelet filter bank. The frequency limits depend on parameters such as the energy spread of the wavelet, number of voices per octave, and signal length.

You can set this property when you create the icwtLayer object. After you create the object, this property is read-only.

Data Types: single | double

FrequencyLimits — Frequency limits

Read-only: two-element scalar vector

This property is read-only.

Frequency limits used in inverting the CWT, specified as a two-element vector with positive strictly increasing entries. The frequency limits are interpreted as normalized frequencies, cycles/sample.

• The first element specifies the lowest peak passband frequency and must be greater than or equal to the product of the wavelet peak frequency in normalized frequency and two time standard deviations divided by SignalLength.

• The second element specifies the highest peak passband frequency and must be less than or equal to the Nyquist frequency.

The base-2 logarithm of the ratio of the upper frequency limit freqMax to the lower frequency limit freqMin must be greater than or equal to 1/VoicesPerOctave:

log2(freqMax/freqMin) ≥ 1/VoicesPerOctave.

To obtain normalized frequencies, divide your desired frequency limits in hertz by the sample rate in hertz. For example, if the sample rate is 1000 Hz and your desired frequency limits are [100,400] Hz, divide each element by 1000 to obtain the normalized frequencies: [100/1000,400/1000].

Frequency limits apply only to wavelet filters. If you additionally specify IncludeLowpass as true, icwtLayer also includes the lowpass (scaling) filter.

You can set this property when you create the icwtLayer object. After you create the object, this property is read-only.

Note

If you use Deep Network Designer (Deep Learning Toolbox) to create or edit a deep learning network, and change the Wavelet property of an icwtLayer, the app does not change the frequency limits of the layer.

Data Types: single | double

TimeBandwidth — Time-bandwidth product for Morse wavelet

Read-only: 60 (default) | positive scalar

This property is read-only.

Time-bandwidth product for the Morse wavelet, specified as a positive scalar greater than or equal to 3 and less than or equal to 120. The symmetry (gamma) of the Morse wavelet is fixed at 3. This property is only valid when Wavelet is "Morse". The layer ignores the time-bandwidth product for the "amor" and "bump" wavelets. For Morse wavelets, the larger the time-bandwidth product, the more spread out the wavelet is in time and narrower the wavelet is in frequency.

In the notation of Morse Wavelets, TimeBandwidth is P².

You can set this property when you create the icwtLayer object. After you create the object, this property is read-only.

Data Types: single | double

Layer

Weights — Layer weights

[] (default) | numeric array | dlarray object

Layer weights, specified as [], a numeric array, or a dlarray object.

The layer weights are learnable parameters. You can use initialize (Deep Learning Toolbox) to initialize the learnable parameters of a dlnetwork (Deep Learning Toolbox) that includes icwtLayer objects. When you initialize the layers, initialize sets Weights to the CWT filter bank associated with the specified Wavelet. For more information, see Initialize Inverse Continuous Wavelet Transform Layer. (since R2025a)

It is not recommended to initialize the weights directly.

Data Types: single | double

WeightLearnRateFactor — Multiplier for weight learning rate

0 (default) | nonnegative scalar

Multiplier for weight learning rate, specified as a nonnegative scalar. The weights are the reduced CWT filter values represented as a 1-by-1-by-Nr tensor. See cwtfilters2array for details. By default, the weights do not update with training.

Data Types: single | double

Name — Layer name

'' (default) | character vector | string scalar

Layer name, specified as a character vector or a string scalar. For Layer array input, the trainnet (Deep Learning Toolbox) and dlnetwork (Deep Learning Toolbox) functions automatically assign names to unnamed layers.

The icwtLayer object stores this property as a character vector.

Data Types: char | string

NumInputs — Number of inputs

Read-only: 1 (default)

This property is read-only.

Number of inputs to the layer, stored as 1. This layer accepts a single input only.

Data Types: double

InputNames — Input names

Read-only: {'in'} (default)

This property is read-only.

Input names, stored as {'in'}. This layer accepts a single input only.

Data Types: cell

NumOutputs — Number of outputs

Read-only: 1 (default)

This property is read-only.

Number of outputs from the layer, stored as 1. This layer has a single output only.

Data Types: double

OutputNames — Output names

Read-only: {'out'} (default)

This property is read-only.

Output names, stored as {'out'}. This layer has a single output only.

Data Types: cell

Object Functions

filterbank

Full-weight CWT filter bank for deep learning

Examples

Restoring cwtLayer Input Using icwtLayer

Load a signal.

load wecg
x = wecg;
sigLen = length(x);

Create a cwtLayer appropriate for the signal. To concatenate the real and imaginary parts of the layer output along the channel dimension, set the transform mode to "realimag". Also include the lowpass filter in the layer.

cwtl = cwtLayer(SignalLength=sigLen,IncludeLowpass=true, ...
    TransformMode="realimag");

Create an icwtLayer that includes the lowpass filter for the same signal length.

icwtl = icwtLayer(SignalLength=sigLen,IncludeLowpass=true);

Create a trivial network with the two layers that can accept the signal as input.

sqlayer = sequenceInputLayer(1,MinLength=sigLen);
layers = [
    sqlayer
    cwtl
    icwtl
    ];
dlnet = dlnetwork(layers);

Analyze the network. cwtLayer and icwtLayer initialize the weights to be the wavelet filters used in the CWT.

analyzeNetwork(dlnet)

In the CWT and ICWT layers, the size of the weights is 1-by-1-by-17,930. Create a CWT filter bank appropriate for the signal. Specify periodic boundary extension. Then use the cwtfilters2array function to obtain the reduced-weight CWT filter tensor. Include the lowpass pass. Confirm the size of the tensor is equal to the size of the weights.

fb = cwtfilterbank(SignalLength=sigLen,Boundary="periodic");
psifvec = cwtfilters2array(fb,IncludeLowpass=true);
whos psifvec

  Name         Size                  Bytes  Class     Attributes

  psifvec      1x1x17930            143440  double              

Run the signal through the predict method of the network. Compute the half mean squared error loss between the network prediction and the original signal.

xrec = predict(dlnet,x);
loss = mse(xrec,single(x));
t = tiledlayout(2,1);
nexttile
plot(x)
title("Original")
axis tight
nexttile
plot(xrec)
title("Restored")
axis tight
title(t,"MSE: "+loss)

Reset icwtLayer Frequency Limits to Default Values in Deep Network Designer

Reset the frequency limits to default values after changing the wavelet of an icwtLayer in Deep Network Designer.

Suppose you are editing a deep learning network using Deep Network Designer. The network has an icwtLayer that uses the Morse wavelet and has frequency limits set at [0.1,0.3].

Set the Wavelet value to amor. The frequency limits do not change.

To change the frequency limits to default values appropriate for the amor wavelet, first do one of the following:

• Delete the frequency limits 0.1,0.3.

• Set the FrequencyLimits value to [].

Then click the mouse outside the FrequencyLimits edit field to move the focus. The app automatically populates FrequencyLimits with default values for the amor wavelet.

Tip: If you change the frequency limits, and later want to restore the default values, follow the same steps.

Initialize Inverse Continuous Wavelet Transform Layer

Since R2025a

Initialize inverse continuous wavelet transform (ICWT) layer weights to wavelet, update deep learning neural network, and reset learnable parameters.

Define an array of seven layers: a sequence input layer, a CWT layer, a 2-D convolutional layer, a batch normalization layer, a rectified linear unit (ReLU) layer, a fully connected layer, and an ICWT layer. There are two features in the sequence input. Set the minimum signal length in the sequence input layer to 250 samples. Use a signal length of 250 samples and a bump wavelet for the CWT and ICWT layers.

sL = 250;
wName = "bump";
layers = [
   sequenceInputLayer(2,MinLength=250)
   cwtLayer(SignalLength=sL,Wavelet=wName,Name="cwt")
   convolution2dLayer(4,15,Padding="same")
   batchNormalizationLayer
   reluLayer
   fullyConnectedLayer(148)
   icwtLayer(SignalLength=sL,Wavelet=wName,Name="icwt")];

Create a deep learning neural network from the layer array. By default, the dlnetwork function initializes the network at creation. For reproducibility, use the default random number generator.

rng("default")
net = dlnetwork(layers);

Display the table of learnable parameters. The network weights and bias are nonempty dlarray objects.

tInit1 = net.Learnables

tInit1=8×3 table
       Layer       Parameter           Value        
    ___________    _________    ____________________

    "cwt"          "Weights"    {  1×1×367  dlarray}
    "conv"         "Weights"    {  4×4×2×15 dlarray}
    "conv"         "Bias"       {  1×1×15   dlarray}
    "batchnorm"    "Offset"     {  1×15     dlarray}
    "batchnorm"    "Scale"      {  1×15     dlarray}
    "fc"           "Weights"    {148×555    dlarray}
    "fc"           "Bias"       {148×1      dlarray}
    "icwt"         "Weights"    {  1×1×367  dlarray}

Extract the filter bank from the ICWT layer.

psif1 = filterbank(net.Layers(7));

Compare the initialized weights of the ICWT layer from the list of learnable parameters with the reduced-weight CWT filter tensor of the corresponding CWT filter bank. The icwtLayer weights are single precision and initialized to the specified wavelet.

fb = cwtfilterbank(SignalLength=sL,Wavelet=wName,Boundary="periodic");
psifvec = cwtfilters2array(fb);
psifLayer = tInit1.Value{8};
isequal(single(psifvec),psifLayer)

ans = logical
   1

Set the learnable parameters to empty arrays.

net = dlupdate(@(x)[],net);
net.Learnables

ans=8×3 table
       Layer       Parameter       Value    
    ___________    _________    ____________

    "cwt"          "Weights"    {0×0 double}
    "conv"         "Weights"    {0×0 double}
    "conv"         "Bias"       {0×0 double}
    "batchnorm"    "Offset"     {0×0 double}
    "batchnorm"    "Scale"      {0×0 double}
    "fc"           "Weights"    {0×0 double}
    "fc"           "Bias"       {0×0 double}
    "icwt"         "Weights"    {0×0 double}

Reinitialize the network and extract the filter bank from the ICWT layer. Display the network and the learnable parameters. The network weights and bias are nonempty dlarray objects.

net = initialize(net);
psif2 = filterbank(net.Layers(7));
tInit2 = net.Learnables

tInit2=8×3 table
       Layer       Parameter           Value        
    ___________    _________    ____________________

    "cwt"          "Weights"    {  1×1×367  dlarray}
    "conv"         "Weights"    {  4×4×2×15 dlarray}
    "conv"         "Bias"       {  1×1×15   dlarray}
    "batchnorm"    "Offset"     {  1×15     dlarray}
    "batchnorm"    "Scale"      {  1×15     dlarray}
    "fc"           "Weights"    {148×555    dlarray}
    "fc"           "Bias"       {148×1      dlarray}
    "icwt"         "Weights"    {  1×1×367  dlarray}

Compare the weights from the ICWT and 2-D convolutional layers along the two initialization calls. The ICWT layer sets the weights using the specified wavelet, while the convolutional layer weights consists of a new set of random values.

tiledlayout flow
f = 0:1/sL:1-1/sL;
nexttile
plot(f,psif1')
xlim([0 1/2])
hold on
plot(f,psif2',"--")
hold off
title("ICWT Weights (Wavelet Filters)")
nexttile
plot(tInit1.Value{2}(:))
hold on
plot(tInit2.Value{2}(:),"--")
hold off
title("2-D Convolutional Weights")
legend(["First" "Second"] + " Initialization", ...
    Location="eastoutside")

Tips

• For the best reconstruction when the filters in icwtLayer and cwtLayer are not learnable (which is the default setting):

  • Ensure consistency in the filter bank used for the CWT and ICWT by using the same parameters in icwtLayer and cwtLayer.

  • Include the scaling coefficients by setting IncludeLowpass to true in icwtLayer and cwtLayer.

Version History

Introduced in R2024b

R2025a: Initialize layer weights through dlnetwork initialization

Starting in R2025a, you can use initialize (Deep Learning Toolbox) to initialize learnable parameters for deep learning neural networks that include icwtLayer objects.

R2025a: New Weights default value

Starting in R2025a, the default value of the Weights property is []. Prior to R2025a, icwtLayer set the default value to the wavelet filters used in the CWT.