Documentation

isnlarx

Detect nonlinearity in estimation data

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.

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 the CSTR data set.

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.

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 the estimation data.

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 the estimation data.

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