idnlarx - Nonlinear black-box ARX model

A structure that specifies the estimation algorithm options, as described in idnlarx Algorithm Properties.

Custom expression in terms of standard regressors.
Assignable values:

• Cell array of strings. For example:
  {'y1(t-3)^3','y2(t-1)*u1(t-3)','sin(u3(t-2))'}.

• Object array of customreg objects. Create these objects using commands such as customreg and polyreg. For more information, see the corresponding reference pages.

A read-only structure that stores estimation settings and results, as described in idnlarx EstimationInfo Properties.

Specifies 'Prediction' or 'Simulation'.
Assignable values:

• 'Prediction' (default)—The estimation algorithm minimizes , where is the 1–step ahead predicted output. This algorithm does not necessarily minimize the simulation error.

• 'Simulation'—The estimation algorithm minimizes the simulation error and optimizes the results of compare(data,model,Inf). That is, when computing , y in the regressors in F are replaced by values simulated from the input only. 'Simulation' requires that the model include only differentiable nonlinearities.

Note   If your model includes the treepartition or neuralnet nonlinearity, the algorithm always uses 'prediction', regardless of the Focus value. If your model includes the wavenet nonlinearity, the first estimation of this model uses 'prediction'.

Specifies which standard or custom regressors enter the nonlinear block. For multiple-output models, use cell array of n_y elements (n_y = number of model outputs). For each output, assignable values are:

• 'all'—All regressors enter the nonlinear block.

• 'search'—Specifies that the estimation algorithm searches for the best regressor combination. This is useful when you want to reduce a large number of regressors entering the nonlinear function block or the nonlinearity estimator.

• 'input' — Input regressors only.

• 'output' — Output regressors only.

• 'standard' — Standard regressors only.

• 'custom' — Custom regressors only.

• '[]' — No regressors enter the nonlinear block.

• A vector of indices: Specifies the indices of the regressors that should be used in the nonlinear estimator. To determine the order of regressors, use getreg.

Nonlinearity estimator object. Assignable values include wavenet (default), sigmoidnet, treepartition, customnet, neuralnet, and linear. If the model contains only one regressor, you can also use saturation, deadzone, pwlinear, or poly1d.

For ny outputs, Nonlinearity is an ny-by-1 array. For example, [sigmoidnet;wavenet] for a two-output model. When you specify a scalar object, this nonlinearity applies to all outputs.

Nonlinear ARX model orders and input delays, where na is the number of output terms, nb is the number of input terms, and nk is the delay from input to output in terms of the number of samples.

For ny outputs and nu inputs, na is an ny-by-ny matrix whose i-jth entry gives the number of delayed jth outputs used to compute the ith output. nb and nk are ny-by-nu matrices.

A structure that specifies additional estimation algorithm options, as described in idnlarx Advanced Algorithm Properties.

The search method of lsqnonlin supports the Trace criterion only.

Use for multiple-output models only. Criterion can have the following values:

• 'Det': Minimize det(E'*E), where E represents the prediction error. This is the optimal choice in a statistical sense and leads to the maximum likelihood estimates in case nothing is known about the variance of the noise. It uses the inverse of the estimated noise variance as the weighting function. This is the default criterion used for all models, except idnlgrey which uses 'Trace' by default.

• 'Trace': Minimize the trace of the weighted prediction error matrix trace(E'*E*W), where E is the matrix of prediction errors, with one column for each output, and W is a positive semi-definite symmetric matrix of size equal to the number of outputs. By default, W is an identity matrix of size equal to the number of model outputs (so the minimization criterion becomes trace(E'*E), or the traditional least-squares criterion). You can specify the relative weighting of prediction errors for each output using the Weighting field of the Algorithm property. If the model contains neuralnet or treepartition as one of its nonlinearity estimators, weighting is not applied because estimations are independent for each output.

Both the Det and Trace criteria are derived from a general requirement of minimizing a weighted sum of least squares of prediction errors. Det can be interpreted as estimating the covariance matrix of the noise source and using the inverse of that matrix as the weighting. You should specify the weighting when using the Trace criterion.

If you want to achieve better accuracy for a particular channel in MIMO models, use Trace with weighting that favors that channel. Otherwise, use Det. If you use Det, check cond(model.NoiseVariance) after estimation. If the matrix is ill-conditioned, try using the Trace criterion. You can also use compare on validation data to check whether the relative error for different channels corresponds to your needs or expectations. Use the Trace criterion if you need to modify the relative errors, and check model.NoiseVariance to determine what weighting modifications to specify.

(For wavenet nonlinear estimator only)
Toggles performing iterative or noniterative estimation.
Default: 'auto'.
Assignable values:

• 'auto' — First estimation is noniterative and subsequent estimation are iterative.

• 'On' — Perform iterative estimation only.

• 'Off' — Perform noniterative estimation only.

Robustification criterion that limits the influence of large residuals, specified as a positive real value. Residual values that are larger than 'LimitError' times the estimated residual standard deviation have a linear cost instead of the usual quadratic cost.
Default: 0 (no robustification).

Maximum number of iterations for the estimation algorithm, specified as a positive integer.
Default: 20.

The number of elements (size) of the largest matrix to be formed by the algorithm. Computational loops are used for larger matrices. Use this value for memory/speed trade-off.MaxSize can be any positive integer.
Default: 250000.

Note   The original data matrix of u and y must be smaller than MaxSize.

Method used by the iterative search algorithm.
Assignable values:

• 'Auto' — Automatically chooses from the following methods.

• 'gn' — Subspace Gauss-Newton method.

• 'gna' — Adaptive Gauss-Newton method.

• 'grad' — A gradient method.

• 'lm' — Levenberg-Marquardt method.

• 'lsqnonlin' — Nonlinear least-squares method (requires the Optimization Toolbox product). This method only handles the 'Trace' criterion.

Specifies to terminate the iterative search when the expected improvement of the parameter values is less than Tolerance, specified as a positive real value in %.
Default: 0.01.

Toggles displaying or hiding estimation progress information in theMATLAB Command Window.
Default: 'Off'.
Assignable values:

• 'Off' — Hide estimation information.

• 'On' — Display estimation information.

(For multiple-output models only)

Specifies the relative importance of outputs in MIMO models (or reliability of corresponding data) as a positive semi-definite matrix W. Use when Criterion = 'Trace' for weighted trace minimization. By default, Weighting is an identity matrix of size equal to the number of outputs.

When the search direction is computed, the algorithm discards the singular values of the Jacobian that are smaller than GnPinvConst*max(size(J))*norm(J)*eps. Singular values that are closer to 0 are included when GnPinvConst is decreased.
Default: 1e4.
Assign a positive, real value.

(For Levenberg-Marquardt search algorithm) The starting level of regularization when using the Levenberg-Marquardt search method (Algorithm.SearchMethod='lm').
Default: 0.001.
Assign a positive real value.

(For Levenberg-Marquardt search algorithm) Try this next level of regularization to get a lower value of the criterion function. The level of regularization is LMStep times the previous level. At the start of a new iteration, the level of regularization is computed as 1/LMStep times the value from the previous iteration.
Default: 10.
Assign a real value >1.

Maximum number of bisections performed by the line search algorithm along the search direction (number of rotations of search vector for 'lm'). Used by 'gn', 'lm', 'gna' and 'grad' search methods (Algorithm.SearchMethod property)
Default: 10.
Assign a positive integer value.

The iterations are stopped if the number of calls to the model file exceeds this value.
Default: Inf.
Assign a positive integer value.

The smallest parameter update allowed per iteration.
Default: 1e-16.
Assign a positive, real value.

The iterations are stopped if the relative improvement of the criterion function is less than RelImprovement.
Default: 0.
Assign a positive real value.

Note   Does not apply to Algorithm.SearchMethod='lsqnonlin'

(For line search algorithm) The suggested parameter update is reduced by the factor 'StepReduction' after each try until either 'MaxBisections' tries are completed or a lower value of the criterion function is obtained.
Default: 2.
Assign a positive, real value >1.

Note   Does not apply to Algorithm.SearchMethod='lsqnonlin'

Shows whether the model parameters were estimated.

Shows the estimation method.

Value of the loss function, equal to det(E'*E/N), where E is the residual error matrix (one column for each output) and N is the total number of samples.

Value of Akaike's Final Prediction Error (see fpe).

Name of the data from which the model is estimated.

Length of the estimation data.

Sampling interval of the estimation data.

'Time' means time domain data. 'Frequency' is not supported.

Intersample behavior of the input estimation data used for interpolation:

• 'zoh' means zero-order-hold, or piecewise constant.

• 'foh' means first-order-hold, or piecewise linear.

Duration of the estimation.

The value of randn('state') at the last randomization of the initial parameter vector.

Number of iterations performed by the estimation algorithm.

Norm of the Gauss-Newton in the last iteration. Empty when 'lsqnonlin' is the search method.

Criterion improvement in the last iteration, shown in %. Empty when 'lsqnonlin' is the search method.

Any warnings encountered during parameter estimation.

Reason for terminating parameter estimation iterations.