Documentation

# 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. The object defines a nonlinear function $y=F\left(x\right)$, where F is a piecewise-linear (affine) function of x, y is scalar, and x is a 1-by-`m` vector. Compute the value of F using `evaluate(t,x)`, where t is the `treepartition` object at x.

## Construction

`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 and 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`.

## 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 NameDescription
`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.

• `Tree`: 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 character vector 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`.

## 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);```

## 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)=d+xL+\left(1,x\right){C}_{k},$`

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 `treepartition` object, is computed at x, an adaptive algorithm selects the active node k of the tree on the branch of partitions which contain x.

When the `Focus` option in `nlarxOptions` 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.