idTreePartition

Tree-partitioned nonlinear function for nonlinear ARX models

Description

An idTreePartition object implements a tree-partitioned nonlinear function, and is a nonlinear mapping function for estimating nonlinear ARX 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 idTreePartition unit functions that operate on a radial combination of inputs.

Mathematically, idTreePartition is a nonlinear function $$y=F(x)$$ that maps m inputs X(t) = [x(t₁),x₂(t),…,x_m(t)]^T to a scalar output y(t). F is a piecewise-linear (affine) function of x:

$$F(x)=xL+[1,x]C_k+d$$

Here, x belongs to the partition P_k. L is a 1-by-m vector, C_k is a 1-by-m+1 vector, and P_k is a partition of the x-space.

For more information about the mapping function F(x) see Algorithms.

Use idTreePartition as the value of the OutputFcn property of an idnlarx model. For example, specify idTreePartition when you estimate an idnlarx model with the following command.

sys = nlarx(data,regressors,idTreePartition)

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

You can configure the idTreePartition function to fix parameters. To omit the linear component, set LinearFcn.Use to false. Use evaluate to compute the output of the function for a given vector of inputs.

Creation

Syntax

T = idTreePartition

T = idTreePartition(numUnits)

Description

T = idTreePartition creates a idTreePartition object t that is a binary tree nonlinear mapping object. The function computes the number of tree nodes J, represented by the property NumberOfUnits, automatically during estimation. The tree has the number of leaves equal to 2^(J+1)-1.

T = idTreePartition(numUnits) specifies the number of idTreePartition nodes numUnits.

Input Arguments

numUnits — Number of units

'auto' (default) | positive integer

Number of units, specified as 'auto' or a positive integer. numUnits determines the number of tree nodes.

This argument sets the T.NonlinearFcn.NumberOfUnits property.

Properties

Inputs — Input signal names

cell array

Input signal names for the inputs to the mapping object, specified as a 1-by-m cell array, where m is the number of input signals. This property is determined during estimation.

Outputs — Output signal name

cell array

Output signal name for the output of the mapping object, specified as a 1-by-1 cell array. This property is determined during estimation.

LinearFcn — Parameters of linear function

linear function property values (default)

Parameters of the linear function, specified as follows:

• Value — Value of L, specified as a 1-by-m vector.

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

The software computes the value of LinearFcn as X'*L.

Offset — Parameters of offset term

offset property values

Parameters of the offset term, specified as follows:

• 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.

NonlinearFcn — Parameters of nonlinear function

nonlinear function property values

Parameters of the nonlinear function, specified as follows:

• NumberOfUnits — Number of units, specified as 'auto' or a positive integer. NumberOfUnits determines the number of nodes N in the tree. When N is set to:

  • 'auto', the software selects N by pruning.

  • a positive integer before estimation, then the software sets N to the largest value of the form 2^(J+1)-1 less than this integer.

• Parameters — estimated parameter values.idTreePartition, specified as in the following table:

  Field Name	Description
  SampleLength	Length of the estimation data
  NoiseVariance	Estimated variance of the noise in the estimation data
  Tree	Structure that contains the tree parameters, as described in the following list: TreeLevelPntr: N-by-1 vector containing the levels j of each node. AncestorDescendantPntr: N-by-3 matrix, such that the entry (k,1) is the ancestor of node k, and entries (k,2) and (k,3) are the left and right descendants, respectively. LocalizingVectors: N-by-(m+1) matrix, such that the rth row is B_r. LocalParVector: N-by-(m+1) matrix, such that the kth row is C_k. LocalCovMatrix: N-by-((m+1)m/2) matrix such that the kth row is the covariance matrix of C_k. C_k is reshaped as a row vector.

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

• Structure — Advanced options that affect the initial model.

  Property	Description	Default
  FinestCell	Integer or character vector specifying the minimum number of data points in the smallest partition.	'auto'
  Threshold	Threshold parameter used by the adaptive pruning algorithm. Smaller threshold value corresponds to a shorter branch that is terminated by the active partition D_a. Higher threshold value results in a longer branch	1.0
  Stabilizer	Penalty parameter of the penalized least-squares algorithm used to compute local parameter vectors C_k. Higher stabilizer value improves stability, but may deteriorate the accuracy of the least-square estimate.	1e-6

Examples

Estimate Nonlinear ARX Model with idTreePartition as Output Function

Load the data

load iddata1 z1

Create an idTreePartition object with default settings.

T = idTreePartition

T = 
Tree Partition

 Nonlinear Function: Tree Partition with number of units chosen automatically
 Linear Function: uninitialized
 Output Offset: uninitialized

         NonlinearFcn: '<Tree structure>'
            LinearFcn: '<Linear function parameters>'
               Offset: '<Offset parameters>'
    EstimationOptions: '<Estimation options>'

Estimate a nonlinear ARX model using T.

sys = nlarx(z1,[2 2 1],T);

View the output function of sys.

disp(sys.OutputFcn)

Tree Partition
Inputs: y1(t-1), y1(t-2), u1(t-1), u1(t-2)
Output: y1(t)

 Nonlinear Function: Tree Partition with 31 units
 Linear Function: initialized to [1.19 -0.419 0.873 0.844]
 Output Offset: initialized to 5.96e-17

         NonlinearFcn: '<Tree structure>'
            LinearFcn: '<Linear function parameters>'
               Offset: '<Offset parameters>'
    EstimationOptions: '<Estimation options>'

T now has 31 nodes.

Specify idTreePartition Parameters

Load the data.

load iddata7 z7
ze = z7(1:300);

Create an idTreePartition object and use dot notation to set parameters.

T = idTreePartition;
T.Offset.Value = 0.2;
T.Offset.Free = false;
T.NonlinearFcn.NumberOfUnits = 30;

Specify model regressors.

Reg1 = linearRegressor({'y1','u1'},{1:4, 0:4});
Reg2 = polynomialRegressor({'y1','u1'},{1:2, 0:2},2);

Estimate a nonlinear ARX model.

sys = nlarx(ze, [Reg1;Reg2], T);

View postestimation OutputFcn properties.

sys.OutputFcn

ans = 
Tree Partition
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), y1(t-1)^2, y1(t-2)^2, u1(t)^2, u1(t-1)^2, u1(t-2)^2
Output: y1(t)

 Nonlinear Function: Tree Partition with 15 units
 Linear Function: initialized to [0.0725 0.895 -0.0727 -0.475 0.0725 -0.106 0.0304 1.02 1.43 0.000459 -0.00473 0 0 0]
 Output Offset: fixed to 0.2

         NonlinearFcn: '<Tree structure>'
            LinearFcn: '<Linear function parameters>'
               Offset: '<Offset parameters>'
    EstimationOptions: '<Estimation options>'

sys.OutputFcn.Input

ans = 
Function inputs

     Name: {'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)'  'y1(t-1)^2'  'y1(t-2)^2'  'u1(t)^2'  'u1(t-1)^2'  'u1(t-2)^2'}
     Mean: [-4.8010e-17 -3.6007e-17 -3.6007e-17 -1.2002e-17 9.0018e-17 -1.5003e-16 -1.6053e-16 -1.5903e-16 9.6019e-17 -1.4403e-15 -4.8010e-17 0 0 0]
    Range: [2x14 double]

disp(sys.OutputFcn.Offset)

Output Offset: fixed to 0.2
    Value: 0.2000
     Free: 0

sys.OutputFcn.NonlinearFcn

ans = 
Tree structure

    NumberOfUnits: 15
       Parameters: '<Tree Partition parameters>'
             Free: 1
           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)'  'y1(t-1)^2'  'y1(t-2)^2'  'u1(t)^2'  'u1(t-1)^2'  'u1(t-2)^2'}
          Outputs: {'y1(t):Nonlinear'}

Algorithms

The mapping F is defined by a dyadic partition P of the x-space, such that on each partition element P_k, F is a linear mapping. When x belongs to P_k, F(x) is given by:

$$F(x)=xL+[1,x]C_k+d$$

where L is 1-by-m vector and d is a scalar common for all elements of partition. C_k is a 1-by-(m+1) vector.

The mapping F and associated partition P of the x-space are computed as follows:

1. Given the value of J, a dyadic tree with J levels and N = 2^J–1 nodes is initialized.

2. Each node at level 1 < j < J has two descendants at level j + 1 and one parent at level j – 1.

   • The root node at level 1 has two descendants.

   • Nodes at level J are terminating leaves of the tree and have one parent.

3. One partition element is associated to each node k of the tree.

   • The vector of coefficients C_k is computed using the observations on the corresponding partition element P_k by the penalized least-squares algorithm.

   • When the node k is not a terminating leaf, the partition element P_k is cut into two to obtain the partition elements of descendant nodes. The cut is defined by the half-spaces (1,x)B_k > 0 or <=0 (move to left or right descendant), where B_k is chosen to improve the stability of least-square computation on the partitions at the descendant nodes.

4. When the value of the mapping F, defined by the idTreePartition object, is computed at x, an adaptive algorithm selects the active node k of the tree on the branch of partitions that contain x.

When the Focus option in nlarxOptions is 'prediction', idTreePartition uses a noniterative technique for estimating parameters. Iterative refinements are not possible for models containing this nonlinearity estimator.

You cannot use idTreePartition when Focus is 'simulation' because this nonlinear mapping object is not differentiable. Minimization of simulation error requires differentiable nonlinear functions.

Version History

Introduced in R2007a

R2022a: Previous idnlarx data normalization information moved from mapping object properties to idnlarx Normalization property

Information related to data normalization was moved from the idTreePartition mapping object level to the model level. The Normalization property of the idnlarx model contains the data centering and scaling information that the estimation process computes. In addition, the regressor-selection process for the mapping objects has also moved to the model level. The model now passes the actual regressor names rather than the selection indices to the mapping object, eliminating the need for an index property at the mapping object level.

The following table summarizes the mapping object subproperties that were eliminated. For more information, see the Normalization property of idnlarx.

Main Properties / Subproperties	Input	Output	LinearMdl	Offset	NonlinearMdl
Mean	X	X
Range	X	X
Minimum			X	X	X
Maximum			X	X	X
SelectedInputIndex			X		X

R2021b: Use of previous idnlarx and idnlhw mapping object names is not recommended.

Starting in R2021b, the mapping objects (also known as nonlinearities) used in the nonlinear components of the idnlarx and idnlhw objects have been renamed. The following table lists the name changes.

Pre-R2021b Name	R2021b Name
wavenet	idWaveletNetwork
sigmoidnet	idSigmoidNetwork
treepartition	idTreePartition
customnet	idCustomNetwork
saturation	idSaturation
deadzone	idDeadZone
pwlinear	idPiecewiseLinear
poly1d	idPolynomial1D
unitgain	idUnitGain
linear	idLinear
neuralnet	idFeedforwardNetwork

Scripts with the old names still run normally, although they will produce a warning. Consider using the new names for continuing compatibility with newly developed features and algorithms. There are no plans to exclude the use of these object names at this time.

R2021a: Use of previous nonlinearity estimator properties is not recommended

Starting in R2021a, the properties of the mapping objects, previously known as nonlinearity estimators, have been reorganized. These objects are idWaveletNetwork (W), idSigmoidNetwork (S), idTreePartition (T), idCustomNetwork (C), and idLinear (L). The property changes do not apply to idFeedforwardNetwork. 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