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 Version History.

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)², 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 rth 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 kyth 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 Name	Description
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

Define Custom Regressors

Load estimation data.

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

Define Custom Regressors During Estimation

Load the estimation data.

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'});

Define Custom Regressors as Array of customreg Objects

Load the estimation data.

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

Use Vectorization Rules to Evaluate Regressor Expression

Load the estimation data.

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

R2021a: customreg is not recommended

Starting in R2021a, create polynomial regressors using polynomialRegressor. To create other custom regressor forms, use customRegressor. Add the new regressor to the idnlarx Regressors property by using the syntax by using the syntax model.Regressors(end+1) = new_regressor_object.

There are no plans to remove customreg at this time.