customreg

(Not recommended) Custom regressor for nonlinear ARX models

The `customreg` command is not recommended. For polynomial regressors, use `polynomialRegressor` instead. For other custom regressors, use `customRegressor`. For more information, see Compatibility Considerations.

Syntax

```C=customreg(Function,Variables) C=customreg(Function,Variables,Delays,Vectorized) ```

Description

`customreg` class represents arbitrary functions of past inputs and outputs, such as products, powers, and other MATLAB® expressions of input and output variables.

You can specify custom regressors in addition to or instead of standard regressors for greater flexibility in modeling your data using nonlinear ARX models. For example, you can define regressors like tan(u(t-1)), u(t-1)2, and u(t-1)*y(t-3).

For simpler regressor expressions, specify custom regressors directly in the app or in the `nlarx` estimation command. For more complex expressions, create a `customreg` object for each custom regressor and specify these objects as inputs to the estimation. Regardless of how you specify custom regressors, the toolbox represents these regressors as `customreg` objects. Use `getreg` to list the expressions of all standard and custom regressors in your model.

A special case of custom regressors involves polynomial combinations of past inputs and outputs. For example, it is common to capture nonlinearities in the system using polynomial expressions like y(t−1)2, u(t−1)2, y(t−2)2, y(t−1)*y(t−2), y(t−1)*u(t−1), y(t− 2)*u(t−1). At the command line, use the `polyreg` command to generate polynomial-type regressors automatically by computing all combinations of input and output variables up to a specified degree. `polyreg` produces `customreg` objects that you specify as inputs to the estimation.

The nonlinear ARX model (`idnlarx` object) stores all custom regressors as the `CustomRegressors` property. You can list all custom regressors using `m.CustomRegressors`, where `m` is a nonlinear ARX model. For MIMO models, to retrieve the `r`th custom regressor for output `ky`, use `m.CustomRegressors{ky}(r)`.

Use the `Vectorized` property to specify whether to compute custom regressors using vectorized form during estimation. If you know that your regressor formulas can be vectorized, set `Vectorized` to `1` to achieve better performance. To better understand vectorization, consider the custom regressor function handle `z=@(x,y)x^2*y`. `x` and `y` are vectors and each variable is evaluated over a time grid. Therefore, `z` must be evaluated for each `(xi,yi)` pair, and the results are concatenated to produce a `z` vector:

```for k = 1:length(x) z(k) = x(k)^2*y(k) end```

The above expression is a nonvectorized computation and tends to be slow. Specifying a `Vectorized` computation uses MATLAB vectorization rules to evaluate the regressor expression using matrices instead of the `FOR`-loop and results in faster computation:

```% ".*" indicates element-wise operation z=(x.^2).*y ```

Construction

`C=customreg(Function,Variables)` specifies a custom regressor for a nonlinear ARX model. `C` is a `customreg` object that stores custom regressor. `Function` is a function of input and output variables. `Variables` represent the names of model inputs and outputs in the function `Function`. Each input and output name must coincide with the `InputName` and `OutputName` properties of the corresponding `idnlarx` object. The size of `Variables` must match the number of `Function` inputs. For multiple-output models with `p` outputs, the custom regressor is a `p`-by-1 cell array or an array of `customreg` object, where the `ky`th entry defines the custom regressor for output `ky`. You must add these regressors to the `model` by assigning the `CustomRegressors` `model` property or by using `addreg`.

`C=customreg(Function,Variables,Delays,Vectorized)` create a custom regressor that includes the delays corresponding to inputs or outputs in `Arguments`. `Delays` is a vector of positive integers that represent the delays of `Variables` variables (default is 1 for each vector element). The size of `Delays` must match the size of `Variables`. `Vectorized` value of `1` uses MATLAB vectorization rules to evaluate the regressor expression `Function`. By default, `Vectorized` value is `0` (false).

Properties

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

```% List all property values get(C) % Get value of Arguments property C.Arguments```

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

`set(C,'Vectorized',1)`
Property NameDescription
`Function`

Function handle or character vector representing a function of standards regressors.

For example:

`cr = @(x,y) x*y`
`Variables`

Cell array of character vectors that represent the names of model input and output variables in the function `Function`. Each input and output name must coincide with the `InputName` and `OutputName` properties of the `idnlarx` object—the model for which you define custom regressors. The size of `Variables` must match the number of `Function` inputs.

For example, `Variables` correspond to `{'y1','u1'}` in:

`C = customreg(cr,{'y1','u1'},[2 3])`
` Delays`

Vector of positive integers representing the delays of `Variables`. The size of `Delays` must match the size of `Arguments`.

Default: `1` for each vector element.

For example, `Delays` are ```[2 3]``` in:

`C = customreg(cr,{'y1','u1'},[2 3])`
` Vectorized`

Assignable values:

• `0` (default)—`Function` is not computed in vectorized form.

• `1``Function` is computed in vectorized form when called with vector arguments.

Examples

collapse all

`load iddata1`

Specify the regressors as a cell array of character vectors.

`C = {'u1(t-1)*sin(y1(t-3))','u1(t-2)^3'};`

u1 and y1 are input and output data, respectively.

Estimate a nonlinear ARX model using the custom regressors.

`m = nlarx(z1,[2 2 1],'idLinear','CustomRegressors',C);`

`load iddata1`

Estimate a nonlinear ARX model with custom regressors.

```m = nlarx(z1,[2 2 1],'idLinear','CustomRegressors',... {'u1(t-1)*sin(y1(t-3))','u1(t-2)^3'});```

`load iddata1`

Construct a nonlinear ARX model.

`m = idnlarx([2 2 1]);`

Define the custom regressors.

```cr1 = @(x,y) x*sin(y); cr2 = @(x) x^3; C = [customreg(cr1,{'u','y'},[1 3]),customreg(cr2,{'u'},2)];```

Add custom regressors to the model.

`m2 = addreg(m,C);`

`load iddata1`

Specify the regressors.

```C = customreg(@(x,y) x.*sin(y),{'u' 'y'},[1 3]); set(C,'Vectorized',1);```

Estimate a nonlinear ARX model with custom regressors.

`m = nlarx(z1,[2 2 1],idSigmoidNetwork,'CustomReg',C);`

Version History

Introduced in R2007a

expand all