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(Name=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

icwtLayer initializes the weights internally to be the wavelet filters used in the CWT. Initializing the weights directly is not recommended.

layer = icwtLayer(Name=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.

Properties

CWT

SignalLength — Signal length in samples

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

"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

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

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

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

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

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

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 string scalar. For Layer array input, the trainnet (Deep Learning Toolbox) and dlnetwork (Deep Learning Toolbox) functions automatically assign names to layers with the name "".

The icwtLayer object stores this property as a character vector.

Data Types: char | string

NumInputs — Number of inputs

1 (default)

This property is read-only.

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

Data Types: double

InputNames — Input names

{'in'} (default)

This property is read-only.

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

Data Types: cell

NumOutputs — Number of outputs

1 (default)

This property is read-only.

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

Data Types: double

OutputNames — Output names

{'out'} (default)

This property is read-only.

Output names, returned 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, but the number of weights does 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. The number of weights also changes to reflect the new limits.

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

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