# 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\left(x\right)$ that maps m inputs X(t) = [x(t1),x2(t),…,xm(t)]T to a scalar output y(t). F is a piecewise-linear (affine) function of x:

$F\left(x\right)=xL+\left[1,x\right]{C}_{k}+d$

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

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

### Description

example

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

expand all

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

expand all

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.

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

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.

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.

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 NameDescription
SampleLength Length of the estimation data
NoiseVarianceEstimated 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.

PropertyDescriptionDefault
FinestCell

Integer or character vector specifying the minimum number of data points in the smallest partition.

'auto'
ThresholdThreshold 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 branch1.0
StabilizerPenalty 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

collapse all

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

Inputs: {1x0 cell}
Outputs: {1x0 cell}
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

Inputs: {'y1(t-1)'  'y1(t-2)'  'u1(t-1)'  'u1(t-2)'}
Outputs: {'y1(t)'}
NonlinearFcn: '<Tree structure>'
LinearFcn: '<Linear function parameters>'
Offset: '<Offset parameters>'
EstimationOptions: '<Estimation options>'

T now has 31 nodes.

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

Inputs: {1x14 cell}
Outputs: {'y1(t)'}
NonlinearFcn: 'Tree structure'
LinearFcn: 'Linear function parameters'
Offset: 'Offset parameters'
EstimationOptions: 'Estimation options'

sys.OutputFcn.Input
ans =
Function inputs

Name: {1x14 cell}
Mean: [-4.8010e-17 -3.6007e-17 -3.6007e-17 -1.2002e-17 9.0018e-17 ... ]
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: {1x14 cell}
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 Pk, F is a linear mapping. When x belongs to Pk, F(x) is given by:

$F\left(x\right)=xL+\left[1,x\right]{C}_{k}+d$

where L is 1-by-m vector and d is a scalar common for all elements of partition. Ck 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 = 2J–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 Ck is computed using the observations on the corresponding partition element Pk by the penalized least-squares algorithm.

• When the node k is not a terminating leaf, the partition element Pk is cut into two to obtain the partition elements of descendant nodes. The cut is defined by the half-spaces (1,x)Bk > 0 or <=0 (move to left or right descendant), where Bk 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

expand all