System Identification Toolbox™

customreg - Class representing custom regressor for nonlinear ARX models

Syntax

C=customreg(Function,Arguments) C=customreg(Function,Arguments,Delays,Vectorized)

Arguments

Function: Function handle or string representing a function of input and output variables.
Arguments: Cell array of strings that represent the names of model inputs and outputs used in the function Function. Each input and output name must coincide with the strings in the InputName and OutputName properties of the corresponding idnlarx object. The size of Arguments must match the number of Function inputs.
Delays: Vector of positive integers representing the delays of Arguments variables. The size of Delays must match the size of Arguments. Default: 1 for each vector element.
Vectorized: Flag that indicates whether Function is in a format that supports vectorized computations when applied to vector arguments. Can have values 1 (true) and 0 (false). Default: 0.

Description

C=customreg(Function,Arguments) creates an object that stores custom regressors for nonlinear ARX models. Custom regressor is defined using the function of input and output variables, Function.

C=customreg(Function,Arguments,Delays,Vectorized) create a custom regressor that includes the delays corresponding to inputs or outputs in Arguments.

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 kyth entry defines the custom regressor for output ky.

Remarks

Use the customreg object to define a custom regressor entering the nonlinearity estimator of the nonlinear ARX models (idnlarx object). The custom regressor function is usually a nonlinear function of inputs and outputs.

To list custom regressors of a multiple-output model, type the following command:

model.custom

To retrieve rth custom regressor for output ky, type the following command:

model.custom{ky}(r)

For more information about regressors, type help regressors.

For more information on creating custom regressors that are polynomial combinations of delayed inputs and outputs, type help polyreg.

Use the Vectorized property to specify whether to compute custom regressors using vectorized form. If you know that your regressor formulas can be vectorized, set Vectorized to 1 after creating the customreg object to achieve better performance. To better understand vectorization, consider that custom regressors are defined by a formula, such as 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, as follows:

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, as follows:

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

customreg 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(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', 0)

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

Property Name	Description
`Function`	Function handle or string representing a function of standards regressors. For example: cr = @(x,y) x*y
`Arguments`	Cell array of strings that represent the names of model inputs and outputs used in the function `Function`. Each input and output name must coincide with the strings in the `InputName` and `OutputName` properties of the `idnlarx` object with the custom regressor. The size of `Arguments` must match the number of `Function` inputs. For example, `Arguments` correspond to `{'y1','u1'}` in the following syntax: C = customreg(cr,{'y1','u1'},[2 3])
`Delays`	Vector of positive integers representing the delays of `Arguments` variables. The size of `Delays` must match the size of `Arguments`. Default: `1` for each vector element. For example, `Delays` correspond to `[2 3]` in the following syntax: C = customreg(cr,{'y1','u1'},[2 3])
`Vectorized`	Can have the following values: `1`—`Function` is computed in vectorized form when called with vector arguments. `0`—`Function` is not computed in vectorized form when called with vector arguments.

Examples

Consider a system that has input u and output y. Suppose that the following transformations are useful for predicting future outputs, based on physical insight into the relationship between measured variables:

u(t-1)sin(y(t-3))
u(t-2)^3

You can define custom regressors in two ways:

Cell array of strings. For example:
```
C={'u(t-1)*sin(y(t-3))','u(t-2)^3'}
```

Object array of customreg objects. For example:

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

After you define the custom regressors, estimate the nonlinear ARX model using the following syntax:

m = nlarx(Data,Orders,linear,'CustomRegressors',C)

In this case, u and y are Data channel names, and the nonlinearity estimator linear specifies that the prediction is a linear function of standard and custom regressors, where the custom regressor might be nonlinear. You can introduce additional nonlinearities using nonlinearity estimators. For a complete list of available nonlinearities, type idprops idnlestimators.

The following command is equivalent to the previous code snippet and incorporates custom regressor definitions directly in the estimator command:

m = nlarx(Data,Orders,'linear',...
          'CustomRegressors',...
         {'u1(t-1)*sin(y1(t-3))','u1(t-2)^3'});