predictOptions

Option set for predict

Syntax

opt = predictOptions

opt = predictOptions(Name,Value)

Description

opt = predictOptions creates the default option set for predict. Use dot notation to modify this option set. Any options that you do not modify retain their default values.

opt = predictOptions(Name,Value) creates an option set with options specified by one or more Name,Value pair arguments.

Examples

Specify Output Offset for Predicting Model Response

Create a default option set for model prediction.

opt = predictOptions;

Specify the output offsets for a two-output model as 2 and 5, respectively.

opt.OutputOffset = [2;5];

The software subtracts the offset value OutputOffset(i) from the i th output signal before using the output to predict the model response. The software then adds back these offsets to the predicted response to give the final response.

Specify Zero Initial Conditions for Model Prediction

Create an option set for predict using zero initial conditions.

opt = predictOptions('InitialCondition','z');

Use Historical Data to Specify Initial Conditions for Model Prediction

Load a two-input, one-output dataset.

load iddata7 z7

Identify a fifth-order state-space model using the data.

sys = n4sid(z7,5);

Split the dataset into two parts.

zA = z7(1:15);
zB = z7(16:end);

Suppose that you want to compute the 10-step-ahead prediction of the response of the identified system for data zB. For initial conditions, use the signal values in zA as the historical record. That is, the input and output values for the time immediately preceding data in zB.

IO = struct('Input',zA.InputData,'Output',zA.OutputData);
opt = predictOptions('InitialCondition',IO);

Generate the 10-step-ahead prediction for data zB using the specified initial conditions.

[yp,x0,Predictor] = predict(sys,zB,10,opt);

yp is the predicted model response, x0 are the initial states corresponding to the predictor model Predictor. You can simulate Predictor using x0 as initial conditions to reproduce yp.OutputData.

To understand how the past data is mapped to the initial states of the model, see Understand Use of Historical Data for Model Prediction.

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: predictOptions('InitialCondition','z') specifies zero initial conditions for the measured input-output data.

InitialCondition — Handling of initial conditions

'e' (default) | 'z' | 'd' | column vector | matrix | initialCondition object | object array | structure | idpar object x0Obj

Handling of initial conditions, specified as the comma-separated pair consisting of 'InitialCondition' and one of the following values:

• 'z' — Zero initial conditions.

• 'e' — Estimate initial conditions such that the prediction error for observed output is minimized.

  For nonlinear grey-box models, only those initial states i that are designated as free in the model (sys.InitialStates(i).Fixed = false) are estimated. To estimate all the states of the model, first specify all the Nx states of the idnlgrey model sys as free.

  for i = 1:Nx
  sys.InitialStates(i).Fixed = false;
  end 

  Similarly, to fix all the initial states to values specified in sys.InitialStates, first specify all the states as fixed in the sys.InitialStates property of the nonlinear grey-box model.

• 'd' — Similar to 'e', but absorbs nonzero delays into the model coefficients. The delays are first converted to explicit model states, and the initial values of those states are also estimated and returned.

  Use this option for linear models only.

• Vector or Matrix — Initial guess for state values, specified as a numerical column vector of length equal to the number of states. For multi-experiment data, specify a matrix with Ne columns, where Ne is the number of experiments. Otherwise, use a column vector to specify the same initial conditions for all experiments. Use this option for state-space (idss and idgrey) and nonlinear models (idnlarx, idnlhw, and idnlgrey) only.

• initialCondition object — initialCondition object that represents a model of the free response of the system to initial conditions. For multiexperiment data, specify a 1-by-N_e array of objects, where N_e is the number of experiments.

  Use this option for linear models only.

• Structure with the following fields, which contain the historical input and output values for a time interval immediately before the start time of the data used in the prediction:

  Field	Description
  Input	Input history, specified as a matrix with Nu columns, where Nu is the number of input channels. For time series models, use []. The number of rows must be greater than or equal to the model order.
  Output	Output history, specified as a matrix with Ny columns, where Ny is the number of output channels. The number of rows must be greater than or equal to the model order.

  For an example, see Use Historical Data to Specify Initial Conditions for Model Prediction.

  For multi-experiment data, configure the initial conditions separately for each experiment by specifying InitialCondition as a structure array with Ne elements. To specify the same initial conditions for all experiments, use a single structure.

  The software uses data2state to map the historical data to states. If your model is not idss, idgrey, idnlgrey, or idnlarx, the software first converts the model to its state-space representation and then maps the data to states. If conversion of your model to idss is not possible, the estimated states are returned empty.

• x0obj — Specification object created using idpar. Use this object for discrete-time state-space (idss and idgrey) and nonlinear grey-box (idnlgrey) models only. Use x0obj to impose constraints on the initial states by fixing their value or specifying minimum or maximum bounds.

InputOffset — Input signal offset

[] (default) | column vector | matrix

Input signal offset for time-domain data, specified as the comma-separated pair consisting of 'InputOffset' and one of the following values:

• [] — No input offsets.

• A column vector of length Nu, where Nu is the number of inputs. The software subtracts the offset value InputOffset(i) from the ith input signal before using the input to predict the model response.

• Nu-by-Ne matrix — For multi-experiment data, specify InputOffset as an Nu-by-Ne matrix, where Ne is the number of experiments. The software subtracts the offset value InputOffset(i,j) from the ith input signal of the jth experiment before prediction.

  If you specify a column vector of length Nu, then the offset value InputOffset(i) is subtracted from the ith input signal of all the experiments.

OutputOffset — Output signal offset

[] (default) | column vector | matrix

Output signal offset for time-domain data, specified as the comma-separated pair consisting of 'OutputOffset' and one of the following values:

• [] — No output offsets.

• A column vector of length Ny, where Ny is the number of outputs. The software subtracts the offset value OutputOffset(i) from the ith output signal before using the output to predict the model response. After prediction, the software adds the offsets to the predicted response to give the final predicted response.

• Ny-by-Ne matrix — For multi-experiment data, specify OutputOffset as an Ny-by-Ne matrix, where Ne is the number of experiments. The software subtracts the offset value OutputOffset(i,j) from the ith output signal of the jth experiment before prediction.

  If you specify a column vector of length Ny, then the offset value OutputOffset(i) is subtracted from the ith output signal of all the experiments.

  After prediction, the software adds the removed offsets to the predicted response to give the final predicted response.

OutputWeight — Weight of output for initial condition estimation

[] (default) | 'noise' | matrix

Weight of output for initial condition estimation, specified as the comma-separated pair consisting of 'OutputWeight' and one of the following values:

• [] — No weighting is used by the software for initial condition estimation. This option is the same as using eye(Ny) for the output weight, where Ny is the number of outputs.

• 'noise' — The software uses the inverse of the NoiseVariance property of the model as the weight.

• A positive, semidefinite matrix of dimension Ny-by-Ny, where Ny is the number of outputs.

OutputWeight is relevant only for multi-output models.

InputInterSample — Input interpolation method

'auto' (default) | string | character array

Input interpolation method, specified as:

• 'auto', 'foh', 'zoh', or 'bl' for continuous-time linear models

• 'auto', 'foh', or 'zoh' for continuous-time nonlinear grey-box models

• 'auto', 'foh', 'zoh', 'cubic', 'makima', 'pchip', or 'spline' for continuous-time neural state-space models

InputInterSample applies only to continuous-time models. If InputInterSample is 'auto', the software automatically picks the same input interpolation method as that used for model estimation.

For information on the interpolation methods, see nssTrainingADAM and compareOptions.

Output Arguments

opt — Option set for predict

predictOptions option set

Option set for predict, returned as a predictOptions option set.

Version History

Introduced in R2012a