Learn more about System Identification Toolbox

treepartition - Class representing binary-tree nonlinearity estimator for nonlinear ARX models

Syntax

t=treepartition(Property1,Value1,...PropertyN,ValueN) t=treepartition('NumberOfUnits',N)

Description

treepartition is an object that stores the binary-tree nonlinear estimator for estimating nonlinear ARX models.

You can use the constructor to create the nonlinearity object, as follows:

t=treepartition(Property1,Value1,...PropertyN,ValueN) creates a binary tree nonlinearity estimator object specified by properties in treepartition Properties. The tree has the number of leaves equal to 2^(J+1)-1, where J is the number of nodes in the tree and set by the property NumberOfUnits. The default value of NumberOfUnits is computed automatically.

Note NumberOfUnits sets an upper limit on the actual number of tree nodes used by the estimator.

t=treepartition('NumberOfUnits',N) creates a binary tree nonlinearity estimator object with N terms in the binary tree expansion (the number of nodes in the tree). When you estimate a model containing t, the value of the NumberOfUnits property, N, in t is automatically changed to show the actual number of leaves used—which is the largest integer of the form 2^n-1 and less than or equal to N.

Use evaluate(t,x) to compute the value of the function defined by the treepartition object t at x. At this stage, an adaptive pruning algorithm is used to select an active partition D_a(= D_a(x)) on the branch of tree partitions that contain x.

Remarks

Use treepartition to define a nonlinear function , where F is a piecewise-linear (affine) function of x, y is scalar, and x is a 1-by-m vector. F is a local linear mapping, where x-space partitioning is determined by a binary tree.

The binary-tree network function is based on the following function expansion:

x belongs to the active partition . is a partition of x-space. L is 1-by-m vector.

C_k is a 1-by-(m+1) vector.

d is a scalar.

The active partition is computed as an intersection of half-spaces by a binary tree, as follows:

Tree with N nodes and J levels is initialized.
Node at level J is a terminating leaf and a node at level j<J has two descendants at level j+1. The number of leaves in the tree is N = 2^(J+1)-1, which is determined by the NumberOfUnits property of the treepartition object.
Partition at node r is based on [1,x]*B_r > 0 or <= 0 (move to left or right descendant), where B_r is chosen to improve the stability of least-square computation on the partitions at the descendant nodes.
Compute at each node r the coefficients C_r of best linear approximation of unknown regression function on D_r using penalized least-squares algorithm.

treepartition Properties

You can include property-value pairs in the constructor to specify the object.

After creating the object, you can use get or dot notation to access the object property values. For example:

% List all property values
get(t)
% Get value of NumberOfUnits property
t.NumberOfUnits

You can also use the set function to set the value of particular properties. For example:

set(t, 'NumberOfUnits', 5)

The first argument to set must be the name of a MATLAB variable.

Property Name Description

Property Name	Description
`NumberOfUnits`	Integer specifies the number of nodes in the tree. Default=`'auto'` selects the number of nodes from the data using the pruning algorithm. When you estimate a model containing a `treepartition` nonlinearity, the value of `NumberOfUnits` is automatically changed to show the actual number of leaves used—which is the largest integer of the form `2^n-1` and less than or equal to `N` (the integer value of units you specify). For example: treepartition('NumberOfUnits',5)
`Parameters`	Structure containing the following fields: `RegressorMean`: 1-by-`m` vector containing the means of `x` in estimation data, `r`. `RegressorMinMax`: `m`-by-2 matrix containing the maximum and minimum estimation-data regressor values. `OutputOffset`: scalar `d`. `LinearCoef`: `m`-by-1 vector L. `SampleLength`: Length of estimation data. `NoiseVariance`: Estimated variance of the noise in estimation data. `NonlinearParameters`: A structure containing the following tree parameters: `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 `r`th row is `B_r`. `LocalParVector`: `N`-by-`(m+1)` matrix, such that the `k`th row is `C_k`. `LocalCovMatrix`: `N`-by-`((m+1)m/2)` matrix such that the `k`th row is the covariance matrix of `C_k`. `C_k` is reshaped as a row vector.
`Options`	Structure containing the following fields that affect the initial model: `FinestCell`: Integer or string specifying the minimum number of data points in the smallest partition. Default: `'auto'`, which computes the value from the data. `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. Default: `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. Default: `1e-6`.

NumberOfUnits

Integer specifies the number of nodes in the tree.
Default='auto' selects the number of nodes from the data using the pruning algorithm.

When you estimate a model containing a treepartition nonlinearity, the value of NumberOfUnits is automatically changed to show the actual number of leaves used—which is the largest integer of the form 2^n-1 and less than or equal to N (the integer value of units you specify).

For example:

treepartition('NumberOfUnits',5)

Parameters

Structure containing the following fields:

RegressorMean: 1-by-m vector containing the means of x in estimation data, r.
RegressorMinMax: m-by-2 matrix containing the maximum and minimum estimation-data regressor values.
OutputOffset: scalar d.
LinearCoef: m-by-1 vector L.
SampleLength: Length of estimation data.
NoiseVariance: Estimated variance of the noise in estimation data.
NonlinearParameters: A structure containing the following tree parameters:
- 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.

Options

Structure containing the following fields that affect the initial model:

FinestCell: Integer or string specifying the minimum number of data points in the smallest partition.
Default: 'auto', which computes the value from the data.
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.
Default: 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.
Default: 1e-6.

Algorithm

When the idnlarx property Focus is 'Prediction', treepartition uses a noniterative technique for estimating parameters. Iterative refinements are not possible for models containing this nonlinearity estimator.

You cannot use treepartition when Focus is 'Simulation' because this nonlinearity estimators is not differentiable. Minimization of simulation error requires differentiable nonlinear functions.

Examples

Use treepartition to specify the nonlinear estimator in nonlinear ARX models. For example:

m=nlarx(Data,Orders,treepartition('num',5));

The following commands provide an example of using advanced treepartition options:

% Define the treepartition object
t=treepartition('num',100);
% Set the Threshold, which is a field
% in the Options structure
t.Options.Threshold=2;
% Estimate the nonlinear ARX model
m=nlarx(Data,Orders,t);