Creating Model Structures at the Command Line :: Choosing Your System Identification Strategy (System Identification Toolbox™)

Learn more about System Identification Toolbox

Creating Model Structures at the Command Line

On this page…
About System Identification Toolbox Model Objects When to Construct a Model Structure Independently of Estimation Commands for Constructing Model Structures Model Properties See Also

On this page…

About System Identification Toolbox Model Objects

When to Construct a Model Structure Independently of Estimation

Commands for Constructing Model Structures

About System Identification Toolbox Model Objects

Objects are based on model classes. Each class is a blueprint that defines the following information about your model:

How the object stores data
Which operations you can perform on the object

This toolbox includes nine classes for representing models. For example, idpoly represents linear input-output polynomial models, and idss represents linear state-space models. For a complete list of available model objects, see Commands for Constructing Model Structures.

Model properties define how a model object stores information. Model objects store information about a model, including the mathematical form of a model, names of input and output channels, units, names and values of estimated parameters, parameter uncertainties, algorithm specifications, and estimation information. For example, the idpoly model class has a property called InputName for storing one or more input channel names. Different model objects have different properties.

The allowed operations on an object are called methods. In the System Identification Toolbox product, some methods have the same name but apply to multiple model objects. For example, the method bode creates a bode plot for all linear model objects. However, other methods are unique to a specific model object. For example, the estimation method n4sid is unique to the state-space model object idss.

Every class has a special method for creating objects of that class, called the constructor. Using a constructor creates an instance of the corresponding class or instantiates the object. The constructor name is the same as the class name. For example, idpoly is both the name of the class representing linear black-box polynomial models and the name of the constructor for instantiating the model object.

For a tutorial about estimating models at the command line, see Tutorial – Identifying Linear Models Using the Command Line in System Identification Toolbox Getting Started Guide.

When to Construct a Model Structure Independently of Estimation

You use model constructors to create a model object at the command line by specifying all required model properties explicitly.

You must construct the model object independently of estimation when you want to:

Simulate a model
Analyze a model
Specify an initial guess for specific model parameter values before estimation

In most cases, you can use the estimation commands to both construct and estimate the model—without having to construct the model object independently. For example, the estimation command pem lets you specify both the model structure with unknown parameters and the estimation algorithm. For information about how to both construct and estimate models with a single command, see Commands for Model Estimation.

In case of grey-box models, you must always construct the model object first and then estimate the parameters of the ordinary differential or difference equation. For more information, see ODE Parameter Estimation (Grey-Box Modeling).

Commands for Constructing Model Structures

The following table summarizes the model constructors available in the System Identification Toolbox product for representing various types of models.

After model estimation, you can recognize the corresponding model objects in the MATLAB^® Workspace browser by their class names. The name of the constructor matches the name of the object it creates.

For information about how to both construct and estimate models with a single command, see Commands for Model Estimation.

Summary of Model Constructors

Model Constructor	Resulting Model Class	Single or Multiple Outputs?
`idarx`	Parametric multiple-output ARX models. Also represents nonparametric transient-response models.	Single- or multiple-output models.
`idfrd`	Nonparametric frequency-response model.	Single- or multiple-output models.
`idproc`	Continuous-time, low-order transfer functions (process models).	Single-output models only.
`idpoly`	Linear input-output polynomial models: ARX ARMAX Output-Error Box-Jenkins	Single-output models only.
`idss`	Linear state-space models.	Single- or multiple-output models.
`idgrey`	Linear ordinary differential or difference equations (grey-box models). You write an M-file that translates user parameters to state-space matrices.	Single- and multiple-output models.
`idnlgrey`	Nonlinear ordinary differential or difference equation (grey-box models). You write an M-file or MEX-file to represent the set of first-order differential or difference equations.	Supports single- and multiple-output models.
`idnlarx`	Nonlinear ARX models, which define the predicted output as a nonlinear function of past inputs and outputs.	Single- or multiple-output models.
`idnlhw`	Nonlinear Hammerstein-Wiener models, which include a linear dynamic system with nonlinear static transformations of inputs and outputs.	Single- or multiple-output models. Does not support time series.

For more information about when to use these commands, see When to Construct a Model Structure Independently of Estimation.

Model Properties

Categories of Model Properties

The way a model object stores information is defined by the properties of the corresponding model class.

Each model object has properties for storing information that are relevant only to that specific model type. However, the idarx, idgrey, idpoly, idproc, and idss model objects are based on the idmodel superclass and inherit all idmodel properties.

Similarly, the nonlinear models idnlarx, idnlhw, and idnlgrey are based on the idnlmodel superclass and inherit all idnlmodel properties.

In general, all nonlinear model objects have properties that belong to the following categories:

Names of input and output channels, such as InputName and OutputName
Sampling interval of the model, such as Ts
Units for time or frequency
Model order and mathematical structure (for example, ODE or nonlinearities)
Properties that store estimation results and model uncertainty
User comments, such as Notes and Userdata
Estimation algorithm information
- Algorithm
  Structure includes fields that specify the estimation method. Algorithm includes another structure, called Advanced, which provides additional flexibility for setting the search algorithm. Different fields apply to different estimation techniques.
  For linear parametric models, Algorithm specifies the frequency weighing of the estimation using the Focus property.
- EstimationInfo
  Structure includes read-only fields that describe the estimation data set, quantitative model quality measures, search termination conditions, how the initial states are handled, and any warnings encountered during the estimation.

For information about getting help on object properties, see Getting Help on Model Properties at the Command Line.

Specifying Model Properties for Estimation

If you are estimating a new model, you can specify model properties directly in the estimator syntax. For a complete list of model estimation commands, see Commands for Model Estimation.

When using the commands that let you both construct and estimate a model, you can specify all top-level model properties in the estimator syntax. Top-level properties are those listed when you type get(object_name). You can also specify the top-level fields of the Algorithm structure directly in the estimator using property-value pairs—such as focus in the previous example—without having to define the structure fields first.

The following commands load the sample data, z8, construct an ARMAX model, and estimate the model parameters. The arguments of the armax estimator specify model properties as property-value pairs.

load iddata8
m_armax=armax(z8,'na',4,...
                 'nb',[3 2 3],...
                 'nc',4,...
                 'nk',[0 0 0],...
                 'focus', 'simulation',...
                 'covariance', 'none',...
                 'tolerance',1e-5,...
                 'maxiter',50);

focus, covariance, tolerance, and maxiter are fields in the Algorithm model property and specify aspects of the estimation algorithm.

For linear models, you can use a shortcut to specify the second-level Algorithm properties, such as Advanced. With this syntax, you can reference the structure fields by name without specifying the structure to which these fields belong.

However, when estimating nonlinear black-box models, you must set the specific fields of the Advanced Algorithm structure and the nonlinearity estimators before estimation. For example, suppose you want to set the value of the wavenet object property Options, which is a structure. The following commands set the Options values before estimation and include the modified wavenet object in the estimator:

% Define wavenet object with defaul properties
W = wavenet;
% Specify variable to represent Options field
O = W.Options;
% Modify values of specific Options fields
O.MaxLevels = 5 ;
O.DilationStep = 2;
% Estimate model using new Options settings
M = nlarx(data,[2 2 1],wavenet('options',O))

where O specifies the values of the Options structure fields and M is the estimated model. For more information about these and other commands, see the corresponding reference page.

Viewing Model Properties and Estimated Parameters

To view all the properties and values of any model object, use the get command. For example, type the following at the prompt to load sample data, compute an ARX model, and list the model properties:

load iddata8
m_arx=arx(z8,[4 3 2 3 0 0 0]);
get(m_arx)

To access a specific property, use dot notation. For example, to view the A matrix containing the estimated parameters in the previous model, type the following command:

m_arx.a
ans =
    1.0000   -0.8441   -0.1539    0.2278    0.1239

Similarly, to access the uncertainties in these parameter estimates, type the following command:

m_arx.da
ans =
    0    0.0357    0.0502    0.0438    0.0294

Property names are not case sensitive. You do not need to type the entire property name if the first few letters uniquely identify the property.

To change property values for an existing model object, use the set command or dot notation. For example, to change the input delays for all three input channels to [1 1 1], type the following at the prompt:

set(m_arx,'nk',[1 1 1])

or equivalently

m_arx.nk = [1 1 1]

Some model properties, such as Algorithm, are structures. To access the fields in this structure, use the following syntax:

model.algorithm.PropertyName

where PropertyName represents any of the Algorithm fields. For example, to change the maximum number of iterations using the MaxIter property, type the following command:

m_arx.algorithm.MaxIter=50

To verify the new property value, type the following:

m_arx.algorithm.MaxIter

Note PropertyName refers to fields in a structure and is case sensitive. You must type the entire property name. Use the Tab key when typing property names to get completion suggestions.

Getting Help on Model Properties at the Command Line

If you need to learn more about model properties while working at the command line, you can use the idprops command to list the properties and values for each object.

Some model objects are based on the superclasses idmodel and idnlmodel and inherit the properties of these superclasses. For such model objects, you must independently look up the properties for both the model object and for its superclass.

The following table summarizes the commands for getting help on object properties.

Help Commands for Model Properties

Model Class	Help Commands
`idarx`	`idprops idarx` Also inherits properties from `idmodel`.
`idfrd`	`idprops idfrd`
`idnlmodel`	`idprops idnlmodel`
`idmodel`	`idprops idmodel` `idprops idmodel Algorithm` `idprops idmodel EstimationInfo` Also see the `Algorithm` and `EstimationInfo` reference page.
`idproc`	`idprops idproc` Also inherits properties from `idmodel`.
`idpoly`	`idprops idpoly` Also inherits properties from `idmodel`.
`idss`	`idprops idss` Also inherits properties from `idmodel`.
`idgrey`	`idprops idgrey` Also inherits properties from `idmodel`.
`idnlgrey`	`idprops idnlgrey` `idprops idnlgrey Algorithm` `idprops idnlgrey EstimationInfo` Also inherits properties from `idnlmodel`.
`idnlarx`	`idprops idnlarx` `idprops idnlarx Algorithm` `idprops idnlarx EstimationInfo` Also inherits properties from `idnlmodel`.
`idnlhw`	`idprops idnlhw` `idprops idnlhw Algorithm` `idprops idnlhw EstimationInfo` Also inherits properties from `idnlmodel`.