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

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.

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

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

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

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

Examples

Detect Nonlinearity in Estimation Data

Load the friction data set.

load frictiondata

Construct an iddata object from the estimation data. Here, f1 is the output data and v is the input 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.

Detect Nonlinearity in Estimation Data Output Channel

Load the CSTR data set.

load cstrdata

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

z = iddata(y1,u1,0.1,Tstart=0);

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.

Search for Best Regressors When Detecting Nonlinearity

Load the signal transmission data set.

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

ans = 3×1 cell
    {'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.74571
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.

Return Nonlinearity Detection Result

Load the estimation data.

load cstrdata

Construct an iddata object using the estimation data.

z = iddata(y1,u1,0.1);

Specify the model orders and delays.

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

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

NLHyp = isnlarx(z,orders)

NLHyp = 1×2

     0     1

Return Nonlinearity Detection Test Quantities

Load the estimation data.

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

NLHyp = 
1

NLValue = 
0.2114

NLRegs = 1×2

     1     2

NoiseSigma = 
0.0323

DetectRatio = 
43.7574

Input Arguments

data — Time-domain estimation data

iddata object | numeric matrix

Time-domain estimation data, specified as an iddata object or a numeric matrix.

• If data is an iddata object, then data can have one or more output channels and zero or more input channels.

• If data is a numeric matrix, then the number of columns of data must match the sum of the number of inputs (n_u) and the number of outputs ( n_y).

data must be uniformly sampled and cannot contain missing (NaN) samples.

orders — ARX model orders

nlarx orders [na nb nk]

ARX model order matrix [na nb nk]. na denotes the number of delayed outputs, nb denotes the number of delayed inputs, and nk denotes the minimum input delay. The minimum output delay is fixed to 1. For more information on how to construct the orders matrix, see arx.

When you specify orders, the software converts the order information into linear regressor form in the idnlarx Regressors property. For an example, see Create Nonlinear ARX Model Using ARX Model Orders

Ky — Output channel number in estimation data

positive integer in the range [0,n_y]

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

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: 'NonlinearRegressors','output' specifies that only the regressors containing output variables are used as inputs to the nonlinear block of the model.

TimeVariable — Independent variable name

't' (default) | character vector

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

CustomRegressors — Regressors constructed from combinations of inputs and outputs

{} (default) | cell array of character vectors | array of customreg objects

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 n_y outputs, specify an n_y-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))'}

NonlinearRegressors — Subset of regressors that enter as inputs to the nonlinear block of the model

'all' (default) | 'output' | 'input' | 'standard' | 'custom' | 'search' | vector of positive integers | [] | cell array

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 n_y elements, where n_y 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

NLHyp — Result of the nonlinearity test

0 | 1 | logical vector

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.

NLValue — Estimated standard deviation of the data explained by the nonlinearity

vector of nonnegative scalars

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.

NLRegs — Regressors that should enter nonlinearly in the model

vector of indices | [] | cell array

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.

NoiseSigma — Estimated standard deviation of the unexplained error

vector of nonnegative scalars

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.

DetectRatio — Ratio of the test statistic and the detection threshold

vector

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 idTreePartition nonlinearity estimator.

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

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

• F_n(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 F_n(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).

Version History

Introduced in R2007a