wavenet

Wavelet network function for nonlinear ARX and Hammerstein-Wiener models

Description

A wavenet object implements a wavelet network function, and is a nonlinear mapping function for estimating nonlinear ARX and Nonlinear Hammerstein-Weiner models. The mapping function, which is also referred to as a nonlinearity, uses a combination of linear weights, an offset and a nonlinear function to compute its output. The nonlinear function contains wavelet unit functions that operate on a radial combination of inputs.

Mathematically, a wavenet network is a function that maps m inputs X(t) = [x(t₁),x₂(t),…,x_m(t)]^T to a scalar output y(t) using the following relationship:

$$y(t)=y_0+{({\rm X}(t)-\overline{X})}^{T}PL+W({\rm X}(t))+S({\rm X}(t))$$

Here:

• X(t) is an m-by-1 vector of inputs, or regressors, with mean $$\overline{{\rm X}}$$.

• y₀ is the output offset, a scalar.

• P is an m-by-p projection matrix, where m is the number of regressors and is p is the number of linear weights. m must be greater than or equal to p.

• L is a p-by-1 vector of weights.

• W(X) and S(X) together constitute the nonlinear function of the wavelet network. W(X) is a sum of dilated and translated wavelets while S(X) is a sum of dilated and translated scaling functions (also known as scalelets). The total number of wavelet d_w and scaling functions d_s is referred to as the number of units of the network.

For definitions of the wavelet function term W(X) and the scaling function term S(X), see More About.

Use wavenet as the value of the OutputFcn property of an idnlarx model or the InputNonlinearity and OutputLinearity properties of an idnlhw object. For example, specify wavenet when you estimate an idnlarx model with the following command.

sys = nlarx(data,regressors,wavenet)

When nlarx estimates the model, it essentially estimates the parameters of the wavenet function.

You can configure the wavenet function to disable components and fix parameters. To omit the linear component, set LinearFcn.Use to false. To omit the offset, set Offset.Use to false. To specify known values for the linear function and the offset, set their Value attributes directly and set the corresponding Free attributes to False. Use evaluate to compute the output of the function for a given vector of inputs.

Creation

Syntax

W = wavenet

W = wavenet(numUnits)

W = wavenet(numUnits,UseLinearFcn)

W = wavenet(numUnits,UseLinearFcn,UseOffset)

Description

W = wavenet creates a wavenet object W, for which the function computes the number of units automatically during model estimation.

W = wavenet(numUnits) specifies the number of units numUnits. This syntax includes an option that allows you to interactively assess the relationship between the number of units and unexplained variance.

W = wavenet(numUnits,UseLinearFcn) specifies whether the function uses a linear function as a subcomponent.

W = wavenet(numUnits,UseLinearFcn,UseOffset) specifies whether the function uses an offset term.

Input Arguments

numUnits — Number of units

'auto' (default) | 'interactive' | positive integer

Number of units, specified as the string or character vector that represents 'auto' or 'interactive', or as a positive integer. numUnits determines the number of wavelets or scaling functions, or, if both elements are present, the combined number of wavelets and scaling functions. Typically, the wavelet network contains either wavelets or scaling functions, but not both. Specify numUnits as one of the following values:

• 'auto' — The software determines the number of units automatically during model estimation.

• 'interactive' — During model estimation, the software displays an interactive bar plot that relates unexplained variance to the number of units. Click on a bar to view the achievable fit to the estimation data for the selected number of units. A blue bar indicates the optimal choice, based on the generalized cross-validation (GCV) criterion. A general rule for the selection of the number of units is to use the smallest number of units that capture most of the variance.

• Positive integer — The software uses the specified value directly.

This argument sets the W.NonlinearFcn.NumberOfUnits property.

UseLinearFcn — Option to use linear function

true (default) | false

Option to use the linear function subcomponent, specified as true or false. This argument sets the value of the W.LinearFcn.Use property.

UseOffset — Option to use offset term

true (default) | false

Option to use an offset term, specified as true or false. This argument sets the value of the W.Offset.Use property.

Properties

Input — Input signal information

signal property values

Input signal information for signals used for estimation, specified as vectors of m property-specific values, where m is the number of input signals. The Input properties for each input signal are as follows:

• Name — Names of the input signals, specified as a 1-by-m string or character array, where m is the number of inputs

• Mean — Mean of the input signals, specified as a numeric scalar

• Range — Ranges of the input signals, specified as a 2-by-m numeric array that contains the minimum and maximum values

Output — Output signal information

signal property values

Output signal information, specified as property-specific values. The Output properties are as follows:

• Name — Name of the output signal, specified as a string or a character array

• Mean — Mean of the output signal, specified as a numeric scalar

• Range — Range of the output signal, specified as a 2-by-1 numeric array that contains the minimum and maximum values

LinearFcn — Parameters of linear function

linear function property values (default)

Parameters of the linear function, specified as follows:

• Use — Option to use the linear function in the wavelet network, specified as a scalar logical. The default value is true. For an example of setting this option, see Exclude Linear Term from Wavelet Network Mapping Object.

• Value — Linear weights that compose L', specified as a 1-by-p vector.

• InputProjection — Input projection matrix P, specified as an m-by-p matrix, that transforms the input vector of length m into a vector of length p. For Hammerstein-Wiener models, InputProjection is equal to 1.

• Free — Option to update entries of Value during estimation, specified as a 1-by-p logical vector. The software honors the Free specification only if the starting value of Value is finite. The default value is true.

• Minimum — Minimum bound on Value, specified as a 1-p vector. If Minimum is specified with a finite value and the starting value of Value is finite, then the software enforces that minimum bound during model estimation.

• Maximum — Maximum bound on Value, specified as a 1-p vector. If Maximum is specified with a finite value and the starting value of Value is finite, then the software enforces that maximum bound during model estimation.

• SelectedInputIndex — Indices of wavenet inputs (see Input.Name) that are used as inputs to the linear function, specified as an 1-by-n_r integer vector, where n_r is the number of inputs. For nonlinear ARX models, the RegressorUsage property determines these indices. For Hammerstein-Wiener models, SelectedInputIndex is always 1.

Offset — Parameters of offset term

offset property values

Parameters of the offset term, specified as follows:

• Use — Option to use the offset in the wavelet network, specified as a scalar logical. The default value is true.

• Value — Offset value, specified as a scalar.

• Free — Option to update Value during estimation, specified as a scalar logical. The software honors the Free specification of false only if the value of Value is finite. The default value is true.

• Minimum — Minimum bound on Value, specified as a numeric scalar or –Inf. If Minimum is specified with a finite value and the value of Value is finite, then the software enforces that minimum bound during model estimation. The default value is -Inf.

• Maximum — Maximum bound on Value, specified as a numeric scalar or Inf. If Maximum is specified with a finite value and the starting value of Value is finite, then the software enforces that maximum bound during model estimation. The default value is Inf.

NonlinearFcn — Parameters of nonlinear function

nonlinear function property values

Parameters of the nonlinear function, specified as follows:

• NumberOfUnits — Number of units, specified as 'auto', 'interactive', or a positive integer. NumberOfUnits determines the number of wavelets or scaling functions, or, if both elements are present, the combined number of wavelets and scaling functions. Typically, the wavelet network contains either wavelets or scaling functions, but not both. The options for NumberOfUnits are as follows:

  • 'auto' — The software determines the number of units automatically during model estimation.

  • 'interactive' — During model estimation, the software displays an interactive bar plot that relates unexplained variance to the number of units. Click on a bar to view the achievable fit to the estimation data for the selected number of units. A blue bar indicates the optimal choice, based on the generalized cross-validation (GCV) criterion. A general rule for the selection of the number of units is to use the smallest number of units that capture most of the variance.

  • Positive integer — The software uses the specified value directly.

• Structure — Advanced options that control the structure of the wavelet and scaling functions, specified as in the following table.

  Property	Description	Default
  FinestCell	Minimum number of data points in the smallest cell, specified as 'auto' or a positive integer. A cell is the area covered by the part of a wavelet that is significantly nonzero. The default setting of 'auto' specifies that the software determines this value during estimation.	'auto'
  MinimumCells	Minimum number of cells in the partition, specified as a positive integer.	16
  MaximumCells	Maximum number of cells in the partition, specified as a positive integer.	16
  MaximumLevels	Maximum number of wavelet levels, specified as a positive integer.	10
  DilationStep	Dilation step size, specified as a positive integer.	2
  TranslationStep	Translation step size, specified as a positive integer.	1

• Parameters — Parameters of wavenet, specified as in the following table.

  Field Name	Description	Default
  InputProjection	Projection matrix Q, specified as an m-by-q matrix. Q transforms the detrended input vector $$(X-\overline{X})$$ of length m into a vector of length q. Typically, Q has the same dimensions as the linear projection matrix P. In this case, q is equal to p, which is the number of linear weights. For Hammerstein-Wiener models, InputProjection is equal to 1.	[]
  ScalingCoefficient	Scaling function coefficients si, specified as a ds-by-1 vector.	[]
  ScalingTranslation	Scaling translation matrix, specified as a ds-by-q matrix of scaling translation row vectors ei.	[]
  ScalingDilation	Scaling function dilation coefficients di, specified as an ds-by-1 vector.	[]
  WaveletCoefficient	Wavelet function coefficients wi, specified as a dw-by-1 vector.	[]
  WaveletTranslation	Wavelet translation matrix, ei, specified as a dw-by-q matrix of wavelet translation row vectors ci.	[]
  WaveletDilation	Wavelet dilation coefficients bi, specified as an dw-by-1 vector.	[]

• Free — Option to estimate parameters, specified as a logical scalar. If all the parameters have finite values, such as when the wavenet object corresponds to a previously estimated model, then setting Free to false causes the parameters of the nonlinear functions W(X) and S(X) to remain unchanged during estimation. The default value is true.

• SelectedInputIndex — Indices of wavenet inputs (see Input.Name) that are used as inputs to the nonlinear function, specified as an 1-by-n_r integer vector, where n_r is the number of inputs. For nonlinear ARX models, the RegressorUsage property determines these indices. For Hammerstein-Wiener models, SelectedInputIndex is always 1.

Examples

Create Wavelet Network Mapping Object

MO = wavenet;

View the wavenet object.

disp(MO)

Wavelet Network

 Nonlinear Function: Wavelet network with number of units chosen automatically.
 Linear Function: uninitialized
 Output Offset: uninitialized

           Input: [1×1 idpack.Channel]
          Output: [1×1 idpack.Channel]
       LinearFcn: [1×1 nlident.internal.UseProjectedLinearFcn]
    NonlinearFcn: [1×1 nlident.internal.WavenetFcn]
          Offset: [1×1 nlident.internal.ChooseableOffset]

Exclude Linear Term from Wavelet Network Mapping Object

Create the wavenet mapping object MO.

MO = wavenet;

Exclude the linear term from MO.

MO.LinearFcn.Use = false;

View the wavenet object.

disp(MO)

Wavelet Network

 Nonlinear Function: Wavelet network with number of units chosen automatically.
 Linear Function: not in use
 Output Offset: uninitialized

           Input: [1×1 idpack.Channel]
          Output: [1×1 idpack.Channel]
       LinearFcn: [1×1 nlident.internal.UseProjectedLinearFcn]
    NonlinearFcn: [1×1 nlident.internal.WavenetFcn]
          Offset: [1×1 nlident.internal.ChooseableOffset]

Estimate Nonlinear ARX Model with Specific Mapping Function

Load the estimation data.

load twotankdata y u;

Create an iddata object from the estimation data.

z = iddata(y,u,0.2);

Create a wavelet network mapping object with five units.

MO = wavenet(5);

Estimate the nonlinear ARX model.

sys = nlarx(z,[4 4 1],MO)

sys = 
Nonlinear ARX model with 1 output and 1 input
  Inputs: u1
  Outputs: y1

Regressors:
  Linear regressors in variables y1, u1
  List of all regressors

Output function: Wavelet Network with 5 units

Sample time: 0.2 seconds

Status:                                         
Estimated using NLARX on time domain data "z".  
Fit to estimation data: 96.8% (prediction focus)
FPE: 3.553e-05, MSE: 3.515e-05

Estimate MIMO Hammerstein-Wiener Model

Load the estimation data.

load motorizedcamera;

Create an iddata object.

z = iddata(y,u,0.02,'Name','Motorized Camera','TimeUnit','s');

z is an iddata object with six inputs and two outputs.

Specify the model orders and delays.

Orders = [ones(2,6),ones(2,6),ones(2,6)];

Specify the same nonlinearity estimator for each input channel.

InputNL = wavenet;

Specify different nonlinearity estimators for each output channel.

 OutputNL = [deadzone,wavenet];

Estimate the Hammerstein-Wiener model.

sys = nlhw(z,Orders,InputNL,OutputNL);

To see the shape of the estimated input and output nonlinearities, plot the nonlinearities.

plot(sys)

Click on the input and output nonlinearity blocks on the top of the plot to see the nonlinearities.

Apply wavenet Constraints when Estimating Nonlinear ARX Model

Load the estimation data.

load iddata7 z7;

Specify wavenet for the model output function. Configure the wavenet object to have a fixed offset value of 1 and to use five units in the nonlinear component.

w = wavenet;
w.Offset.Value = 1;
w.Offset.Free = false;
w.NonlinearFcn.NumberOfUnits = 5;

Specify a linear model regressor set using a lag array that produces four consecutive output regressors and five consecutive input regressors.

reg = linearRegressor({'y1','u1'},{1:4,0:4});

Estimate the nonlinear ARX model.

sys = nlarx(z7,reg,w);

Examine the postestimation properties of the output function.

disp(sys.OutputFcn)

Wavelet Network
Inputs: y1(t-1), y1(t-2), y1(t-3), y1(t-4), u1(t), u1(t-1), u1(t-2), u1(t-3), u1(t-4)
Output: y1

 Nonlinear Function: Wavelet network with 5 units.
 Linear Function: initialized to [-1.12 0.469 1.25 0.556 -0.81 -0.261 -0.074 0.711 1.15]
 Output Offset: fixed to 1

           Input: [1×1 idpack.Channel]
          Output: [1×1 idpack.Channel]
       LinearFcn: [1×1 nlident.internal.UseProjectedLinearFcn]
    NonlinearFcn: [1×1 nlident.internal.WavenetFcn]
          Offset: [1×1 nlident.internal.ChooseableOffset]

disp(sys.OutputFcn.Input)

  Channel with properties:

     Name: [1×9 string]
     Mean: [0.0795 0.0848 0.1082 0.1134 0.0253 0.0253 0.0202 0.0202 0.0202]
    Range: [2×9 double]

disp(sys.OutputFcn.NonlinearFcn)

  WavenetFcn with properties:

         NumberOfUnits: 5
             Structure: [1×1 nlident.internal.WavenetStructure]
            Parameters: [1×1 nlident.internal.WavenetFcnParameters]
                  Free: 1
    SelectedInputIndex: [1 2 3 4 5 6 7 8 9]

Apply wavenet Constraints when Estimating Hammerstein-Wiener Model

Load the estimation data.

load throttledata

Specify wavenet for the model output nonlinearity and set the arguments for NumUnits to 5 and UseLinearFcn and UseOffset to false.

w = wavenet(5,false,false);

An alternative method for removing the linear function and offset is to use dot notation after creating the nonlinearity.

w.LinearFcn.Use = false;
w.Offset.Use = false;

Estimate the model, using an order specification of [4 4 1].

sys = nlhw(ThrottleData,[4 4 1],[],w);

Compare the simulated model response with the estimation data.

compare(ThrottleData,sys);

More About

Wavelet Nonlinear Function W(X)

The wavelet nonlinear function is a sum of the dilated and translated wavelets, and is described by the following equation:

$$W(X)={\displaystyle \sum _{i=1}^{d_w}{w}_i}{f}_w(b_i{(X-\overline{X})}^{T}Q-c_i)$$

Here:

• Q is an m-by-q projection matrix, where m ≥ q

• w₁, w₂, …, w_dw are scalar coefficients called wavelet coefficients.

• b₁, b₂, …, b_dw are scalars called wavelet dilations that multiply the detrended input matrix $$(X-\overline{X})$$.

• c₁, c₂, …, c_dw are 1-by-q row vectors called wavelet translations.

• $$f_w(x)=e^{-x{x}^T/2}$$ is a radial function that depends only upon the squared magnitude of the vector x. x is a row vector that is composed of a linear combination of inputs with an offset c_i.

Scaling Nonlinear Function S(X)

The scaling nonlinear function is a sum of the dilated and translated scaling functions, and is described by the following equation:

$$S(X)={\displaystyle \sum _{i=1}^{d_s}{s}_i}{f}_s(b_i{(X-\overline{X})}^{T}Q-e_i)$$

Here:

• Q is an m-by-q projection matrix, where m ≥ q.

• s₁, s₂, …, s_ds are scalar coefficients called scaling coefficients.

• d₁, d₂, …, d_ds are scalars called scaling dilations that multiply the detrended input matrix $$(X-\overline{X})$$.

• e₁, e₂, …, e_ds are 1-by-q row vectors called scaling translations.

• $$f_s(x)=(\dim (x)-x{x}^T)e^{-x{x}^T/2}$$ is a radial function that depends only upon the squared magnitude of the vector x. x is a row vector that is composed of a linear combination of inputs with an offset e_i.

Algorithms

You can use wavenet in both nonlinear ARX and Hammerstein-Wiener models. The algorithms for estimating wavenet parameters depend on which model you are estimating.

• In a nonlinear ARX model, wavenet uses either a noniterative or an iterative technique for predicting the parameters, depending on option settings in nlarxOptions.

  • If the Focus option is set to 'prediction', then wavenet uses a fast noniterative technique to estimate parameters [1]. Successive refinements after the first estimation use an iterative algorithm.

  • If the Focus option is set to 'simulation', then wavenet uses an iterative technique to estimate parameters.

  • To always use either an iterative or a noniterative algorithm, specify the IterativeWavenet property of nlarxOptions as 'on' or 'off', respectively.

• In a Hammerstein-Wiener model, wavenet uses iterative minimization to determine the parameters.

Compatibility Considerations

Use of previous nonlinearity estimator properties is not recommended

Not recommended starting in R2021a

Starting in R2021a, the properties of the mapping objects, previously known as nonlinearity estimators, have been reorganized. These objects are wavenet (W), sigmoidnet (S), treepartition (T), customnet (C), and linear (L). The property changes do not apply to neuralnet. The use of the pre-R2021a properties in the following table is discouraged. However, the software still accepts commands that set these properties. There are no plans to exclude such commands at this time.

Pre-R2021a Property	R2021a Property	Applicable Mapping Objects
NumberOfUnits	NonlinearFcn.NumberOfUnits	W,S,T,C
LinearTerm	LinearFcn.Use, Offset.Use	W,S,C
Parameters	Split into three pieces: LinearFcn.Value Offset.Value NonlinearFcn.Parameters	W,S,T,C,L linear (L) excludes NonlinearFcn.Parameters.
Options	NonlinearFcn.Structure	W,T

References

[1] Qinghua Zhang. “Using Wavelet Network in Nonparametric Estimation.” IEEE Transactions on Neural Networks 8, no. 2 (March 1997): 227–36. https://doi.org/10.1109/72.557660.