Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English version of the page.

# isnlarx

Detect nonlinearity in estimation data

## Syntax

``isnlarx(Data,Orders)``
``isnlarx(Data,Orders,Ky)``
``isnlarx(___,Name,Value)``
``NLHyp = isnlarx(___)``
``````[NLHyp,NLValue,NLRegs,NoiseSigma,DetectRatio] = isnlarx(___)``````

## Description

example

````isnlarx(Data,Orders)` detects nonlinearity in `Data` by testing whether a nonlinear ARX model with the indicated `Orders` produces a better estimate of `Data` than a linear ARX model. The nonlinear model uses a default `treepartition` nonlinearity estimator.The result of the test is printed to the Command Window and indicates whether a nonlinearity is detected. Use the printed detection ratio to assess the reliability of the nonlinearity detection test:Larger values (`>2`) indicate that a significant nonlinearity was detected.Smaller values (`<0.5`) indicate that any error unexplained by the linear model is mostly noise. That is, no significant nonlinearity was detected.Values close to `1` indicate that the nonlinearity detection test is not reliable and that a weak nonlinearity may be present.```

example

````isnlarx(Data,Orders,Ky)` restricts the nonlinearity test to output channel `Ky` for multi-output data.```

example

````isnlarx(___,Name,Value)` specifies additional nonlinear ARX model options using one or more `Name,Value` pair arguments.```

example

````NLHyp = isnlarx(___)` returns the result of the nonlinearity test and suppresses the command window output.```

example

``````[NLHyp,NLValue,NLRegs,NoiseSigma,DetectRatio] = isnlarx(___)``` additionally returns the test quantities behind the evaluation.```

## Examples

collapse all

Load the signal transmission data set.

`load(fullfile(matlabroot,'toolbox','ident','iddemos','data','frictiondata'))`

Construct an `iddata` object from the estimation data.

`z = iddata(f1,v,1);`

Specify the model orders and delays.

`orders = [1 1 0];`

Run the test to detect nonlinearity.

`isnlarx(z,orders);`
``` Nonlinearity is detected in data set z. Detection ratio: 525.05 Estimated discrepancy of the linear model found: 0.0064966 Estimated noise standard deviation: 0.00080938 ```

The large detection ratio indicates that the test was robust and a significant nonlinearity was detected. Additionally, the estimated discrepancy of the linear model that was found, that is the data explained by the nonlinearity, is significantly greater than the noise error, which can indicate a significant nonlinearity.

`load(fullfile(matlabroot,'toolbox','ident','iddemos','data','cstrdata'))`

Construct an `iddata` object from the estimation data using a sample time of 0.1 seconds.

`z = iddata(y1,u1,0.1);`

Specify the model orders and delays.

`orders = [3*ones(2,2),ones(2,3),2*ones(2,3)];`

Run the test to detect nonlinearity on the second output channel.

`isnlarx(z,orders,2);`
``` ISNLARX results for dataset z Nonlinearity is not detected in channel (2). However, the test may be on the edge of detecting the nonlinearity. Detection ratio: 0.36446 Searching for best nonlinear regressors may provide more reliable results. - ```

A detection ratio less than `1` indicates that no nonlinearity was detected. However, since this value is near 0.5, there may be a weak nonlinearity that was not detected by the test.

Load the signal transmission data set.

`load(fullfile(matlabroot,'toolbox','ident','iddemos','data','signaltransmissiondata'))`

Construct an `iddata` object from the estimation data using a sample time of 0.1 seconds.

`z = iddata(vout,vin,0.1);`

Specify the model orders and delays.

`orders = [3 0 2];`

Display the model regressors for an `idnlarx` model with the given orders.

`getreg(idnlarx(orders));`
```Regressors: y1(t-1) y1(t-2) y1(t-3) ```

Detect nonlinearities in the data, and search for the best nonlinear regressor combination.

`isnlarx(z,orders,'NonlinearRegressors','search');`
``` Nonlinearity is detected in data set z. Detection ratio: 1.4691 Estimated discrepancy of the linear model found: 0.74371 Estimated noise standard deviation: 0.74935 Corresponding NonlinearRegressors parameter: [1 2 3] ```

The regressor search found that using the first two regressors produces the best nonlinear estimation of the given data.

A detection ratio greater than `1` but less than `2` means that a nonlinearity was detected, but the test was not robust. This result may indicate that the detected nonlinearity is not significant. Additionally, the data explained by the nonlinearity is smaller than the noise error, which can be an indication of a weak nonlinearity.

`load(fullfile(matlabroot,'toolbox','ident','iddemos','data','cstrdata'))`

Construct an `iddata` object using the estimation data.

`z = iddata(y1,u1,0.1);`

Specify the model orders and delays.

`orders = [3*ones(2,2),ones(2,3),2*ones(2,3)];`

Detect nonlinearities in the data, and determine the test quantities behind the evaluation.

`NLHyp = isnlarx(z,orders);`

`load(fullfile(matlabroot,'toolbox','ident','iddemos','data','narendralidata'))`

Construct an `iddata` object using the estimation data.

`z = iddata(u,y1,1);`

Specify the model orders and delays.

`orders = [1 1 2];`

Detect nonlinearities in the data, and determine the test quantities behind the evaluation.

`[NLHyp,NLValue,NLRegs,NoiseSigma,DetectRatio] = isnlarx(z,orders);`

## Input Arguments

collapse all

Time-domain estimation data, specified as an `iddata` object. `Data` can have one or more output channels and zero or more input channels. Data must be uniformly sampled and cannot contain missing (`NaN`) samples.

Model orders and delays for defining the regressor configuration, specified as a 1-by-3 vector, `[na nb nk]`.

For a model with ny output channels and nu input channels:

• `na` is an ny-by-ny matrix, where `na(i,j)` specifies the number of regressors from the jth output used to predict the ith output.

• `nb` is an ny-by-nu matrix, where `nb(i,j)` specifies the number of regressors from the jth input used to predict the ith output.

• `nk` is an ny-by-nu matrix, where `nk(i,j)` specifies the lag in the jth input used to predict the ith output.

```na = [1 2; 2 3] nb = [1 2 3; 2 3 1]; nk = [2 0 3; 1 0 5];```

The estimation data for this system has three inputs (`u1`, `u2`, `u3`) and two outputs (`y1`, `y2`). Consider the regressors used to predict output, `y2(t)`:

• Since `na(2,:)` is `[2 3]`, the contributing regressors from the outputs are:

• `y1(t-1)` and `y1(t-2)`

• `y2(t-1)`, `y2(t-2)`, and `y2(t-3)`

• Since `nb(2,:)` is ```[2 3 1]``` and `nk(2,:)` is `[1 0 5]`, the contributing regressors from the inputs are:

• `u1(t-1)` and `u1(t-2)`

• `u2(t)`, `u2(t-1)`, and `u2(t-2)`

• `u3(t-5)`

### Note

The minimum lag for regressors based on output variables is always `1`, while the minimum lag for regressors based on input variables is dictated by `nk`. Use `getreg` to view the complete set of regressors used by the nonlinear ARX model.

Output channel number in estimation data, specified as a positive integer in the range [1,ny], where ny is the number of output channels.

### Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside quotes. You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

Example: `'NonlinearRegressors','output'` specifies that only the regressors containing output variables are used as inputs to the nonlinear block of the model.

Independent variable name, specified as the comma-separated pair consisting of `'TimeVariable'` and a character vector. For example, `'t'`.

Regressors constructed from combinations of inputs and outputs, specified as the comma-separated pair consisting of `'CustomRegressors'` and one of the following for single-output systems:

• Cell array of character vectors. For example:

• `{'y1(t-3)^3','y2(t-1)*u1(t-3)','sin(u3(t-2))'}`

Each character vector must represent a valid formula for a regressor contributing towards the prediction of the model output. The formula must be written using the input and output names and the time variable name as variables.

• Array of custom regressor objects, created using `customreg` or `polyreg`.

For a model with ny outputs, specify an ny-by-1 cell array of `customreg` object arrays or character arrays.

These regressors are in addition to the standard regressors based on `Orders`.

Example: `'CustomRegressors',{'y1(t-3)^3','y2(t-1)*u1(t-3)'}`

Example: `'CustomRegressors',{'sin(u3(t-2))'}`

Subset of regressors that enter as inputs to the nonlinear block of the model, specified as the comma-separated pair consisting of `'NonlinearRegressors'` and one of the following values:

• `'all'` — All regressors

• `'output'` — Regressors containing output variables

• `'input'` — Regressors containing input variables

• `'standard'` — Standard regressors

• `'custom'` — Custom regressors

• `'search'` — The estimation algorithm performs a search for the best regressor subset. This is useful when you want to reduce a large number of regressors entering the nonlinear function block of the nonlinearity estimator. This option must be applied to all output models simultaneously.

• `[]` — No regressors. This creates a linear-in-regressor model.

• Vector of regressor indices. To determine the number and order of regressors, use `getreg`.

For a model with multiple outputs, specify a cell array of ny elements, where ny is the number of output channels. For each output, specify one of the preceding options. Alternatively, to apply the same regressor subset to all model outputs, specify `[]` or any of the character vector options alone, for example `'standard'`.

Example: `'NonlinearRegressors','search'` performs a best regressor search for the only output of a single output model, or all of the outputs of a multiple output model.

Example: `'NonlinearReg','input'` applies only input regressors to the inputs of the nonlinear function.

Example: `'NonlinearRegressors',{'input','output'}` applies input regressors to the first output, and output regressors to the second output of a model with two outputs.

## Output Arguments

collapse all

Result of the nonlinearity test, returned as a logical vector with length equal to the number of output channels. The elements of `NLHyp` are `1` if nonlinearities were detected for the corresponding output. A value of `0` indicates that nonlinearities were not detected.

Estimated standard deviation of the data explained by the nonlinearity, returned as a vector of nonnegative scalars with length equal to the number of output channels. The elements of `NLValue` are `0` if nonlinearities are not detected for the corresponding output.

Regressors that should enter nonlinearly in the model, returned as a vector of indices for single output models. For multi-output models, `NLRegs` is returned as a cell array, with elements corresponding to each output channel. `NLRegs` is empty, `[]`, if nonlinearities are not detected.

See the `'NonlinearRegressors'` `Name,Value` argument for more information.

Estimated standard deviation of the unexplained error, returned as a vector of nonnegative scalars with length equal to the number of output channels. The elements of `NoiseSigma` are `0` if nonlinearities are not detected for the corresponding output.

Ratio of the test statistic and the detection threshold, returned as a vector with length equal to the number of output channels. Use the elements of `DetectRatio` to assess the reliability of the nonlinearity detection test for the corresponding output:

• Larger values (`>2`) indicate that a significant nonlinearity was detected.

• Smaller values (`<0.5`) indicate that any error unexplained by the linear model is mostly noise. That is, no significant nonlinearity was detected.

• Values close to `1` indicate that the nonlinearity detection test is not reliable and that a weak nonlinearity may be present.

## Algorithms

`isnlarx` estimates a nonlinear ARX model using the given data and a `treepartition` nonlinearity estimator.

The estimation data can be described as Y(t) = L(t) + Fn(t) + E(t), where:

• L(t) is the portion of the data explained by the linear function of the nonlinear ARX model.

• Fn(t) is the portion of the data explained by the nonlinear function of the nonlinear ARX model. The output argument `NLValue` is an estimate of the standard deviation of Fn(t). If the nonlinear function explains a significant portion of the data beyond the data explained by the linear function, a nonlinearity is detected.

• E(t) is the remaining error that is unexplained by the nonlinear ARX model and is typically white noise. The output argument `NoiseSigma` is an estimate of the standard deviation of E(t).