polynomialRegressor

Specify polynomial regressor for nonlinear ARX model

Description

Polynomial regressors are polynomials that are composed of delayed input and output variables. For example, y(t–1)² and y(t–1) u(t–1) are both polynomial regressors with orders of 2 and variable delays of one sample. A polynomialRegressor object encapsulates a set of polynomial regressors. Use polynomialRegressor objects when you create nonlinear ARX models using idnlarx or nlarx. You can specify polynomialRegressor objects along with linearRegressor and customRegressor objects and combine them into a single combined regressor set.

Creation

Syntax

pReg = polynomialRegressor(Variables,Lags)

pReg = polynomialRegressor(Variables,Lags,Order)

pReg = polynomialRegressor(Variables,Lags,Order,UseAbsolute)

pReg = polynomialRegressor(Variables,Lags,Order,UseAbsolute,AllowVariableMix)

pReg = polynomialRegressor(Variables,Lags,Order,UseAbsolute,AllowVariableMix,AllowLagMix)

Description

pReg = polynomialRegressor(Variables,Lags) creates a polynomialRegressor object of order 2 that contains output and input names in Variables and the corresponding lags in Lags. For example, if Variables contains 'y' and lags contains the corresponding lag vector [2 4], then the regressors that use 'y' are y(t–2)² and y(t–4)².

pReg = polynomialRegressor(Variables,Lags,Order) creates a polynomialRegressor object of order Order .

pReg = polynomialRegressor(Variables,Lags,Order,UseAbsolute) specifies in UseAbsolute whether to use the absolute values of the variables to create the regressors.

pReg = polynomialRegressor(Variables,Lags,Order,UseAbsolute,AllowVariableMix) specifies in AllowVariableMix whether to allow multiple variables in the regressor formulas. For example, if Variables is equal to {'y','u'}, Lags is equal to {1,1}, and Order is equal to 2, then a value of true for AllowVariableMix results in the inclusion of the mixed-variable regressor y(t–1)u(t–1), along with the single-variable regressors y(t–1)² and u(t–1)².

pReg = polynomialRegressor(Variables,Lags,Order,UseAbsolute,AllowVariableMix,AllowLagMix) specifies in AllowLagMix whether to allow different lags in the regressor formulas. For example, if Variables is equal to {'y','u'}, Lags is equal to {2,[0 3]}, Order is equal to 2, and AllowVariableMix is equal to false, then a value of true for AllowLagMix results in the inclusion of the mixed-lag regressor u(t)u(t–3), along with the unique-lag regressors y(t–2)², u(t)², and u(t–3)². Note that if you set AllowVariableMix to true, then the regressor set will also include y(t–2)u(t) and y(t–2)u(t–3).

Properties

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. For an example of using this property, see Estimate Nonlinear ARX Model with Polynomial Regressors.

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. For instance, suppose that you want the following regressors:

• Output variable y₁: y₁(t–1)² and y₁(t–2)²

• Input variable u₁: u₁(t–3)²

To obtain these lags, set Lags to {[1 2],3}.

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

For an example of using this property, see Estimate Nonlinear ARX Model with Polynomial Regressors.

Example: {1 1}

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

UseAbsolute — Absolute value indicator

false (default) | logical vector

Absolute value indicator that determines whether to use the absolute value of a regressor variable instead of the signed value, specified as a logical vector with a length equal to the number of variables.

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

Example: [true,false]

AllowVariableMix — Mixed variables indicator

false (default) | logical vector

Mixed variables indicator that determines whether to use multiple variables in regressor formulas such as y(t–1)u(t–1), specified as a logical vector with a length equal to the number of variables.

For an example of setting this property, see Use Multiple Variables in Polynomial Regressor Term.

Example: [true,false]

AllowLagMix — Mixed lag indicator

false (default) | logical vector

Mixed lag indicator that determines whether to use different lags in regressor formulas such as u(t)u(t–3), specified as a logical vector with a length equal to the number of variables.

To set this property for an existing nonlinear ARX model sys, use dot notation, as shown in the following command.

For an example of setting this property, see Use Mixed Lags in Polynomial Regressor Term.

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

Estimate Nonlinear ARX Model with Polynomial Regressors

Load the data and create an iddata object z with a sample time of 0.1 seconds.

load twotankdata y u
z = iddata(y,u,'Ts',0.1);

Specify polynomial regressors that have the forms ${\mathit{u}\left(\mathit{t}-2\right)}^2$, ${\mathit{u}\left(\mathit{t}-4\right)}^2$, and ${\mathit{y}\left(\mathit{t}-1\right)}^2$.

Use the properties of z to specify the variable names.

Variables = [z.OutputName;z.InputName];

Specify the lags.

Lags = {1,[2 4]};

Create the regressor. The default order is 2.

pReg = polynomialRegressor(Variables,Lags)

pReg = 
Order 2 regressors in variables y1, u1
               Order: 2
           Variables: {'y1'  'u1'}
                Lags: {[1]  [2 4]}
         UseAbsolute: [0 0]
    AllowVariableMix: 0
         AllowLagMix: 0
        TimeVariable: 't'

  Regressors described by this set

Use pReg to estimate the nonlinear ARX model.

sys = nlarx(z,pReg)

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

Regressors:
  Order 2 regressors in variables y1, u1
  List of all regressors

Output function: Wavelet Network with 66 units

Sample time: 0.1 seconds

Status:                                          
Estimated using NLARX on time domain data "z".   
Fit to estimation data: 95.97% (prediction focus)
FPE: 5.843e-05, MSE: 5.569e-05

View the regressors.

getreg(sys)

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

Specify Order for Polynomial Regressor

Specify the third-order polynomial regressor ${{\mathit{u}}_1\left(\mathit{t}-2\right)}^3$.

Variables = 'u1';
Lags = 2;
Order = 3;
pReg = polynomialRegressor(Variables,Lags,Order)

pReg = 
Order 3 regressors in variables u1
               Order: 3
           Variables: {'u1'}
                Lags: {[2]}
         UseAbsolute: 0
    AllowVariableMix: 0
         AllowLagMix: 0
        TimeVariable: 't'

  Regressors described by this set

Use Absolute Value in Polynomial Regressor Set

Create a second-order polynomial regressor set that uses lags of 3, 10, and 100 in variable y1 and lags of 0 and 4 in variable u1.

vars = {'y1','u1'};
lags = {[3 10 100],[0,4]};

Specify that the y1 regressor use the absolute value of y1.

UseAbs = [true,false];

Create the polynomial regressor.

reg = polynomialRegressor(vars,lags,2,UseAbs)

reg = 
Order 2 regressors in variables y1, u1
               Order: 2
           Variables: {'y1'  'u1'}
                Lags: {[3 10 100]  [0 4]}
         UseAbsolute: [1 0]
    AllowVariableMix: 0
         AllowLagMix: 0
        TimeVariable: 't'

  Regressors described by this set

Use Multiple Variables in Polynomial Regressor Term

Create a polynomial regressor set that includes the terms ${{\mathit{y}}_1(\mathit{t}-1)}^2$, ${{\mathit{u}}_1(\mathit{t}-1)}^2$, and ${\mathit{y}}_1\left(\mathit{t}-1\right){\mathit{u}}_1\left(\mathit{t}-1\right)$.

Specify the variables and lags.

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

Specify that mixed-variable regressors be created.

mixvar = true;

Create a second-order polynomial regressor using mixvar. Set the fourth position, which represents the UseAbsolute property, to false.

reg = polynomialRegressor(vars,lags,2,false,mixvar)

reg = 
Order 2 regressors in variables y1, u1
               Order: 2
           Variables: {'y1'  'u1'}
                Lags: {[1]  [1]}
         UseAbsolute: [0 0]
    AllowVariableMix: 1
         AllowLagMix: 0
        TimeVariable: 't'

  Regressors described by this set

As an alternative, you can create the regressor specification first using the variables and lags and set the AllowVariableMix property afterward using dot notation.

reg1 = polynomialRegressor(vars,lags);
reg1.AllowVariablemix = true

reg1 = 
Order 2 regressors in variables y1, u1
               Order: 2
           Variables: {'y1'  'u1'}
                Lags: {[1]  [1]}
         UseAbsolute: [0 0]
    AllowVariableMix: 1
         AllowLagMix: 0
        TimeVariable: 't'

  Regressors described by this set

Use reg1 in a nonlinear ARX model.

load twotankdata y u;
z = iddata(y,u,'Ts',0.1);
sys = nlarx(z,reg1);

View the regressors.

getreg(sys)

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

The regressors include mixed-variable terms.

Use Mixed Lags in Polynomial Regressor Term

Specify a polynomial regressor set that includes a term of the form $\mathit{u}\left(\mathit{t}\right)$$\mathit{u}\left(\mathit{t}-3\right)$.

Specify the variable names and the lags.

vars = {'y1','u1'};
lags = {2,[0 3]};

Initialize a second-order polynomial regressor.

reg = polynomialRegressor(vars,lags);

Specify that the regressor use mixed lags.

reg.AllowLagMix = true;

Use the regressor set in a nonlinear ARX model.

load twotankdata y u;
z = iddata(y,u,'Ts',0.1);
sys = nlarx(z,reg);

View the regressors.

getreg(sys)

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

The regressors include the mixed-lag term.

Estimate Nonlinear ARX Model with Polynomial and Linear Regressors

Load the data and create an iddata object z.

load twotankdata y u
z = iddata(y,u,'Ts',0.1);

Specify polynomial regressors that have the forms ${\mathit{u}\left(\mathit{t}-2\right)}^2$ and ${\mathit{u}\left(\mathit{t}-4\right)}^2$. Also specify a linear regressor of the form $\mathit{y}\left(\mathit{t}-1\right)$.

Specify the input lag.

uLags = {[2 4]};

Specify the polynomial regressors. The default regressor order is 2.

pReg = polynomialRegressor(z.InputName,uLags);

Specify the output lag and specify the linear regressor.

lLags = 1;
lReg = linearRegressor(z.OutputName,lLags);

Estimate a nonlinear ARX model.

reg = [pReg;lReg]

reg=2×1 object
[2 1] array of polynomialRegressor, linearRegressor objects.
------------------------------------
1. Order 2 regressors in variables u1
               Order: 2
           Variables: {'u1'}
                Lags: {[2 4]}
         UseAbsolute: 0
    AllowVariableMix: 0
         AllowLagMix: 0
        TimeVariable: 't'

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

  Regressors described by this set

sys = nlarx(z,reg)

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

Regressors:
  1. Linear regressors in variables y1
  2. Order 2 regressors in variables u1
  List of all regressors

Output function: Wavelet Network with 21 units

Sample time: 0.1 seconds

Status:                                          
Estimated using NLARX on time domain data "z".   
Fit to estimation data: 96.56% (prediction focus)
FPE: 4.133e-05, MSE: 4.059e-05

View the regressors.

getreg(sys)

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

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 object
[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 unit

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

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