customRegressor

Specify custom regressor for nonlinear ARX model

Since R2021a

Description

A custom regressor represents a single user-provided formula that operates on delayed input and output variables. For example, y(t–1)e^u(t–1) is a custom regressor that you can construct using the formula @(x,y)x.*exp(y). A customRegressor object encapsulates a set of custom regressors. Use customRegressor objects when you create nonlinear ARX models using idnlarx or nlarx. You can specify customRegressor objects along with linearRegressor, polynomialRegressor, and periodicRegressor objects and combine them into a single combined regressor set.

Creation

Syntax

cReg = customRegressor(Variables,Lags,Fcn)

cReg = customRegressor(Variables,Lags,Fcn,Vectorized)

Description

cReg = customRegressor(Variables,Lags,Fcn) creates a customRegressor object, with the output and input names in Variables, the corresponding lags in Lags, and the function handle in Fcn. Fcn sets the VariablesToRegressorFcn property. For example, if Variables contains 'y', lags contains the corresponding lag vector [2 4], and the custom function is @(x)sin(x), then the regressors that use 'y' are sin(y(t–2)) and sin(y(t–4)).

cReg = customRegressor(Variables,Lags,Fcn,Vectorized) specifies whether Fcn can process a vector of inputs to return a vector of output values, based on the value of Vectorized.

Properties

VariablesToRegressorFcn — Custom Function

function handle

Custom function that transforms a set of delayed variables into a numeric scalar output, specified as a function handle.

Example: @(x)sin(x)

Example: @(x,y)x.*exp(y)

Variables — Output and input variable names

cell array of strings | iddata object properties

Output and input variable names, specified as a cell array of strings or a cell array that references the OutputName and InputName properties of an iddata object. Each entry must be a string with no special characters other than white space.

Example: {'y1','u1'}

Example: [z.OutputName; z.InputName]

Lags — Lags in each variable

cell array of non-negative integers

Lags in each variable, specified as a 1-by-n_v cell array of non-negative integer row vectors, where n_v is the total number of regressor variables. Each row vector contains n_r integers that specify the n_r regressor lags for the corresponding variable. When n_r>1 for at least one of the variables, then the software generates a regressor for every lag combination. For instance, suppose that you want to create the formula r(t) = sin(y₁(t–a))cos(u₁(t–b)), where lag a can be 1 or 2 and lag b can be 0 or 3. Specify Lags as {[1 2],[0 3]}, which corresponds to the variables {'y1','u1'}. This specification creates the following set of regressors:

• 'sin(y1(t-1))*cos(u1(t))'

• 'sin(y1(t-1))*cos(u1(t-3))'

• 'sin(y1(t-2))*cos(u1(t))'

• 'sin(y1(t-2))*cos(u1(t-3))'

If a lag corresponds to an output variable of an idnlarx model, the minimum lag must be greater than or equal to 1.

Example: {1 1}

Example: {[1 2],[1,3,4]}

Vectorized — Vectorization indicator

true (default) | false

Vectorization indicator that determines whether VariablesToRegressorFcn is vectorized , specified as true or false.

For an example of setting this property, see Use Absolute Value in Polynomial Regressor Set.

Example: [true,false]

TimeVariable — Name of time variable

't' (default) | character array | string

Name of the time variable, specified as a valid MATLAB^® variable name that is distinct from values in Variables.

Example: 'ClockTime'

Examples

Create Custom Regressor

Create a custom regressor that represents the formula $\mathit{x}{\mathit{e}}^{\mathit{y}}$.

Specify the input variables as 'u1' and 'y1' and corresponding lags of 1 and 3 delays.

vars = {'y1','u1'};
lags = {1 3};

Specify the custom function.

fcn = @(x,y)x.*exp(y);

Create the regressor.

cReg = customRegressor(vars,lags,fcn)

cReg = 
Custom regressor: y1(t-1).*exp(u1(t-3))
    VariablesToRegressorFcn: @(x,y)x.*exp(y)
                  Variables: {'y1'  'u1'}
                       Lags: {[1]  [3]}
                 Vectorized: 1
               TimeVariable: 't'

  Regressors described by this set

Create Custom Regressors in Multiple Variables

Create a set of custom regressors in three variables, all based on the formula $\mathit{xy}+\sin \left(\mathit{z}\right)$.

Specify the variable names and the lags.

vars = {'a','b','c'};
lags = {[1 5],[0 8],7};

Specify the custom function.

fcn = @(x,y,z)x.*y+sin(z);

Create the custom regressor set.

cReg = customRegressor(vars,lags,fcn)

cReg = 
Custom regressor: @(x,y,z)x.*y+sin(z)
    VariablesToRegressorFcn: @(x,y,z)x.*y+sin(z)
                  Variables: {'a'  'b'  'c'}
                       Lags: {[1 5]  [0 8]  [7]}
                 Vectorized: 1
               TimeVariable: 't'

  Regressors described by this set

cReg specifies regressors for all possible lag combinations.

Specify Linear, Polynomial, and Custom Regressors

Load the estimation data z1, which has one input and one output, and obtain the output and input names.

load iddata1 z1;
names = [z1.OutputName z1.InputName]

names = 1×2 cell
    {'y1'}    {'u1'}

Specify L as the set of linear regressors that represents ${\mathit{y}}_1\left(\mathit{t}-1\right)$, ${\mathit{u}}_1\left(\mathit{t}-2\right)$, and ${\mathit{u}}_1\left(\mathit{t}-5\right)$.

L = linearRegressor(names,{1,[2 5]});

Specify P as the polynomial regressor ${{\mathit{y}}_1\left(\mathit{t}-1\right)}^2$.

P = polynomialRegressor(names(1),1,2);

Specify C as the custom regressor ${\mathit{y}}_1\left(\mathit{t}-2\right)$${\mathit{u}}_1\left(\mathit{t}-3\right)$. Use an anonymous function handle to define this function.

C = customRegressor(names,{2 3},@(x,y)x.*y)

C = 
Custom regressor: y1(t-2).*u1(t-3)
    VariablesToRegressorFcn: @(x,y)x.*y
                  Variables: {'y1'  'u1'}
                       Lags: {[2]  [3]}
                 Vectorized: 1
               TimeVariable: 't'

  Regressors described by this set

Combine the regressors in the column vector R.

R = [L;P;C]

R = 
[3 1] array of linearRegressor, polynomialRegressor, customRegressor objects.
------------------------------------
1. Linear regressors in variables y1, u1
       Variables: {'y1'  'u1'}
            Lags: {[1]  [2 5]}
     UseAbsolute: [0 0]
    TimeVariable: 't'

------------------------------------
2. Order 2 regressors in variables y1
               Order: 2
           Variables: {'y1'}
                Lags: {[1]}
         UseAbsolute: 0
    AllowVariableMix: 0
         AllowLagMix: 0
        TimeVariable: 't'

------------------------------------
3. Custom regressor: y1(t-2).*u1(t-3)
    VariablesToRegressorFcn: @(x,y)x.*y
                  Variables: {'y1'  'u1'}
                       Lags: {[2]  [3]}
                 Vectorized: 1
               TimeVariable: 't'

 
Regressors described by this set

Estimate a nonlinear ARX model with R.

sys = nlarx(z1,R)

sys =

Nonlinear ARX model with 1 output and 1 input
  Inputs: u1
  Outputs: y1

Regressors:
  1. Linear regressors in variables y1, u1
  2. Order 2 regressors in variables y1
  3. Custom regressor: y1(t-2).*u1(t-3)
  List of all regressors

Output function: Wavelet network with 1 units
Sample time: 0.1 seconds

Status:                                          
Estimated using NLARX on time domain data "z1".  
Fit to estimation data: 59.73% (prediction focus)
FPE: 3.356, MSE: 3.147                           

Model Properties

View the full regressor set.

getreg(sys)

ans = 5×1 cell
    {'y1(t-1)'         }
    {'u1(t-2)'         }
    {'u1(t-5)'         }
    {'y1(t-1)^2'       }
    {'y1(t-2).*u1(t-3)'}

Version History

Introduced in R2021a