# arxRegul

Determine regularization constants for ARX model estimation

## Syntax

``````[lambda,R] = arxRegul(tt,orders)``````
``[lambda,R] = arxRegul(u,y,orders)``
``[lambda,R] = arxRegul(data,orders)``
``````[lambda,R] = arxRegul(___,Name,Value)``````
``````[lambda,R] = arxRegul(___,options)``````

## Description

### Calculate Regularization Constants

``````[lambda,R] = arxRegul(tt,orders)``` returns the regularization constants used for ARX model estimation, using the data contained in the variables of timetable `tt`. Use the regularization constants in `arxOptions` to configure the regularization options for ARX model estimation.The software uses the first Nu variables as inputs and the next Ny variables as outputs, where Nu and Ny are determined from the dimensions of `nb` and `na` in the `orders` argument, respectively.To select specific input and output channels from `tt`, use name-value syntax to set `'InputName'` and `'OutputName'` to the corresponding timetable variable names.```
````[lambda,R] = arxRegul(u,y,orders)` uses the time-domain input and output signals in the comma-separated matrices `u`,`y`. The software assumes that the data sample time is 1 second.```

example

````[lambda,R] = arxRegul(data,orders)` uses the time-domain or frequency-domain data in the data object `data`. Use this syntax especially when you want to estimate a model using frequency-domain or frequency-response data, or when you want to take advantage of the additional information, such as data sample time or experiment labeling, that data objects provide.```

example

``````[lambda,R] = arxRegul(___,Name,Value)``` specifies model structure attributes, such as noise integrator and input delay, using one or more name-value arguments. You can use this syntax with any of the previous input-argument combinations.```

example

``````[lambda,R] = arxRegul(___,options)``` specifies regularization options such as regularization kernel and I/O offsets.```

## Examples

collapse all

```load iddata1 z1; orders = [10 10 1]; [Lambda,R] = arxRegul(z1,orders);```

The ARX model is estimated using the default regularization kernel `TC`.

Use the `Lambda` and `R` values for ARX model estimation.

```opt = arxOptions; opt.Regularization.Lambda = Lambda; opt.Regularization.R = R; model = arx(z1,orders,opt);```

Specify `'DC'` as the regularization kernel and obtain a regularized ARX model of order [|10 10 1|].

```load iddata1 z1; orders = [10 10 1]; option = arxRegulOptions('RegularizationKernel','DC'); [Lambda,R] = arxRegul(z1,orders,option);```

Use the `Lambda` and `R` values for ARX model estimation.

```arxOpt = arxOptions; arxOpt.Regularization.Lambda = Lambda; arxOpt.Regularization.R = R; model = arx(z1,orders,arxOpt);```

Specify to include a noise source integrator in the noise component of the model.

```load iddata1 z1; orders = [10 10 1]; [Lambda,R] = arxRegul(z1,orders,'IntegrateNoise',true);```

Specify the regularization kernel and include a noise source integrator in the noise component of the model.

```load iddata1 z1; orders = [10 10 1]; opt = arxRegulOptions('RegularizationKernel','DC'); [Lambda,R] = arxRegul(z1,orders,opt,'IntegrateNoise',true);```

## Input Arguments

collapse all

Estimation data, specified as a `timetable` that uses a regularly spaced time vector. `tt` contains variables representing input and output channels. For multiexperiment data, `tt` is a cell array of timetables of length `Ne`, where `Ne` is the number of experiments

The software determines the number of input and output channels to use for estimation from the dimensions of the specified polynomial orders. The input/output channel selection depends on whether the `'InputName'` and `'OutputName'` name-value arguments are specified.

• If `'InputName'` and `'OutputName'` are not specified, then the software uses the first Nu variables of `tt` as inputs and the next Ny variables of `tt` as outputs.

• If `'InputName'` and `'OutputName'` are specified, then the software uses the specified variables. The number of specified input and output names must be consistent with Nu and Ny.

• For functions that can estimate a time series model, where there are no inputs, `'InputName'` does not need to be specified.

Estimation data, specified for SISO systems as a comma-separated pair of Ns-by-1 real-valued matrices that contain uniformly sampled input and output time-domain signal values. Here, Ns is the number of samples.

For MIMO systems, specify `u`,`y` as an input/output matrix pair with the following dimensions:

• `u`Ns-by-Nu, where Nu is the number of inputs.

• `y`Ns-by-Ny, where Ny is the number of outputs.

For multiexperiment data, specify `u`,`y` as a pair of 1-by-Ne cell arrays, where Ne is the number of experiments. The sample times of all the experiments must match.

For time series data, which contains only outputs and no inputs, specify `y` only.

#### Limitations

Estimation data, specified as an `iddata` object.

ARX model orders `[na nb nc]`, specified as a matrix of nonnegative integers. See the `arx` reference page for more information on model orders.

Regularization options, specified as an options set you create using `arxRegulOptions`.

### Name-Value Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

Example: `[Lambda, R] = arxRegul(z1,orders,option,'InputDelay',10);`

Input channel names for timetable data, specified as a string, a character vector, or an array or cell array of strings or character vectors. By default, the software interprets all but the last variable in `tt` as input channels. When you want to select a subset of the timetable variables as input channels use `'InputName'` to identify them. For example, ```sys = arxRegul(tt,__,'InputName',["u1" "u2"])``` selects the variables `u1` and `u2` as the input channels for the estimation.

Output channel names for timetable data, specified as a string, a character vector, or an array or cell array of strings or character vectors. By default, the software interprets the last variable in `tt` as the sole output channel. When you want to select a subset of the timetable variables as output channels, use `'OutputName'` to identify them. For example, ```sys = arxRegul(tt,__,'OutputName',["y1" "y3"])``` selects the variables `y1` and `y3` as the output channels for the estimation.

Input delay, specified as a positive, nonzero numeric value representing the number of samples.

Example: `[Lambda, R] = arxRegul(z1,orders,'InputDelay',10);`

Data Types: `double`

Noise source integrator, specified as a logical. Specifies whether the noise source `e(t)` should contain an integrator. The default is `false`, indicating the noise integrator is off. To turn it on, change the value to `true`.

Example: `[Lambda, R] = arxRegul(z1,orders,'IntegrateNoise',true);`

Data Types: `logical`

## Output Arguments

collapse all

Constant that determines the bias versus variance trade-off, returned as a positive scalar.

Weighting matrix, returned as a vector of nonnegative numbers or a positive definite matrix.

## Algorithms

Without regularization, the ARX model parameters vector θ is estimated by solving the normal equation

$\left({J}^{T}J\right)\theta ={J}^{T}y$

where J is the regressor matrix and y is the measured output. Therefore,

$\theta ={\left({J}^{T}J\right)}^{-1}{J}^{T}y$

Using regularization adds the regularization term

$\theta ={\left({J}^{T}J+\lambda R\right)}^{-1}{J}^{T}y$

where λ and R are the regularization constants. For more information on the regularization constants, see `arxOptions`.

 T. Chen, H. Ohlsson, and L. Ljung. “On the Estimation of Transfer Functions, Regularizations and Gaussian Processes - Revisited”, Automatica, Volume 48, August 2012.