iddata

Input-output data and its properties for system identification in the time or frequency domain

Description

Use the iddata object to encapsulate input and output measurement data for the system you want to identify. System identification functions use these measurements to estimate a model. Model validation functions use the input measurements to provide the input for simulations, and the output measurements to compare how well the estimated model response fits the original data.

iddata objects can contain a single set of measurements or multiple sets. Each set of data corresponds to an experiment. The objects have the following characteristics, which are encoded in the object properties:

• Data can be in the frequency domain or the time domain. You can convert objects from one domain to the other.

• In the time domain, the data can be uniformly or nonuniformly sampled. To use the iddata object for estimation, however, the data must be uniformly sampled, and the input and output data for each experiment must be recorded at the same time instants.

• You can specify data properties, such as the sample time, start time, time points, frequency sample points, and intersample behavior.

• You can provide labels and comments to differentiate and annotate data components, experiments, and the object as a whole.

To access the object properties, use dot notation. For example, suppose that you create an iddata object with the command sys = iddata(ym,um,Tsamp), where ym is measured output data, um is measured input data, and Tsamp is the sample time. iddata stores these variables in the properties InputData, OutputData, and Ts, respectively. You can view or modify the data using sys.InputData, sys.OutputData, and sys.Ts. For an example of using dot notation to view and modify properties, see View and Modify Properties.

Creation

Syntax

data = iddata(y,u,Ts)

data = iddata(y,[],Ts)

data = iddata(tt)

data = iddata(y,u,Ts,'Frequency',W)

data = iddata(___,Name,Value)

Description

Use Time-Domain Data

data = iddata(y,u,Ts) creates an iddata object containing a time-domain output signal y and input signal u. Ts specifies the sample time of the experimental data.

You can use iddata to create a multiexperiment iddata object by specifying y and u as cell arrays. Alternatively, you can create single-experiment iddata objects and use merge (iddata) to combine the objects into one multiexperiment iddata object. For more information on multiexperiment iddata objects, see Create Multiexperiment Data at the Command Line.

data = iddata(y,[],Ts) creates an iddata object for time-series data. The object contains a time-domain output signal y and an empty input signal []. Ts specifies the sample time of the experimental data.

data = iddata(tt) creates an iddata object from the timetable tt.

The software extracts the variable names and sample time from tt.

By default, the software interprets the last variable in tt as the single output channel, and all other variables are input channels. To change this interpretation, set the 'InputName' and 'OutputName' properties using name-value arguments.

Use Frequency-Domain Data

data = iddata(y,u,Ts,'Frequency',W) creates an iddata object containing frequency-domain data. W sets the iddata property Frequency to a vector of frequencies. Typically, y and u are the discrete Fourier transform of time-domain signals.

Configure Additional Properties

data = iddata(___,Name,Value) sets additional properties using name-value arguments. Specify Name,Value after any of the input argument combinations in the previous syntaxes.

Input Arguments

y — Output signal from system

column vector | matrix | cell array | []

Output signal from a system, specified as one of the following:

• An N-by-1 vector for a single output system, where N is the number of observations

• An N-by-Ny matrix for a multiple-output system, where Ny is the number of output channels

• An N_e element cell array for a multiexperiment data set, where N_e is the number of experiments and each cell contains the output signals for one experiment

• [] for a system that has no output signal, such as when only the input signal is recorded

y must be in the same domain as the input data u. If the data is in the time domain, y and u must be recorded at the same time instants.

If you use the iddata object for estimation, y and u must be uniformly sampled. If the nonuniformity is small, you may be able to convert your data into a uniformly sampled set with enough integrity that the converted data supports estimation. For more information on techniques you can try, see interp1 and Missing Data in MATLAB.

y sets the OutputData property of the iddata object.

u — Input signal to system

column vector | matrix | cell array | []

Input signal to a system, specified as one of the following:

• An N-by-1 vector for a single input system, where N is the number of observations

• An N-by-N_u matrix for a multiple-input system, where N_u is the number of input channels

• An N_e element cell array for a multiexperiment data set, where N_e is the number of experiments and each cell contains the input signals for one experiment

• [] for a system that has no input signal, such as a time series

u must be in the same domain as output data y. If the data is in the time domain, y and u must be recorded at the same time instants.

If you use the iddata object for estimation, y and u must be uniformly sampled. If the nonuniformity is small, you may be able to convert your data into a uniformly sampled set with enough integrity that the converted data supports estimation. For more information on techniques you can try, see interp1 and Missing Data in MATLAB.

u sets the InputData property of the iddata object.

tt — Timetable of input and output signals

timetable | cell array of timetables

Timetable of input and output signals, specified as a timetable that uses a regularly spaced time vector.

For multiexperiment data, specify tt as an Ne-by-1 cell array, where Ne is the number of experiments.

To identify which variables are input signals and which are output signals, or extract a subset of the variables for conversion, set the 'InputName' and 'OutputName' properties using name-value arguments.

Ts — Sample time

1 (default) | scalar | 0 | []

Sample time in the units specified by the property TimeUnit, specified as one of the following:

• A scalar when y and u are uniformly sampled.

• 0 for continuous-time data in the frequency domain.

• [] when y and u are not uniformly sampled and you specify the time values in the property SamplingInstants. For nonuniform sampling, y and u must be in the time domain.

Ts sets the Ts property of the iddata object.

Properties

Domain — Data time or frequency domain

'Time' (default) | 'Frequency'

Data time or frequency domain, specified as either:

• 'Time' — Data is in the time domain

• 'Frequency' — Data is in the frequency domain

ExperimentName — Name of each data set

{'Exp1';'Exp2';…} (default) | cell array

Name of each data set contained in the iddata object, specified as an N_e-by-1 cell array of character vectors, where N_e is the number of experiments. Each cell contains the name of the corresponding experiment. For instance, {'MyMeas1';'MyMeas2';'MyMeas3'} contains experiment names for a three-experiment iddata object.

Frequency — Frequency values

column vector | cell array

Frequency values for frequency-domain data, specified as either:

• An N-by-1 vector, where N is the number of frequency values in a single experiment

• A 1-by-N_e cell array, where N_e is the number of experiments and each cell contains the frequency vector for the corresponding experiment. The frequency vectors must all be in the same units.

FrequencyUnit — Frequency units for frequency-domain data

'rad/TimeUnit' (default) | 'cycles/TimeUnit' | 'rad/s' | 'Hz' | 'kHz' | 'MHz' | 'GHz' | 'rpm'

Frequency units for frequency-domain data, specified as a scalar. This property applies to all elements in the data set.

Changing this property does not scale or convert the data. Modifying the property changes only the interpretation of the existing data.

InputData — Input signal values

vector | matrix | cell array of matrices

Input signal values to the system, specified as one of the following:

• For a single experiment, an N-by-N_u matrix, where N is the number of data samples and N_u is the number of input channels

• For multiple experiments, a cell array containing N_e single-experiment matrices, where N_e is the number of experiments

When accessing InputData from the command line, you can use the shorthand form u. For example, u1 = data.InputData is equivalent to u1 = data.u.

InputName — Input channel names

{'u1';'u2';…} (default) | cell array of character vectors

Input channel names, specified as an N_u-by-1 cell array, where N_u is the number of input channels.

InputUnit — Input channel units

cell array

Input channel units, specified as an N_u-by-1 cell array, where N_u is the number of input channels. Each cell contains the units of the corresponding input channel.

Example: {'rad';'rad/s'}

InterSample — Intersample behavior

'zoh' (default) | 'foh' | 'bl' | cell array of character vectors

Intersample behavior for transformations between discrete time and continuous time, specified as a character vector or as a cell array of character vectors. For each experiment, the possible values for each input channel are:

• zoh — Zero-order hold maintains a piecewise-constant input signal between samples.

• foh — First-order hold maintains a piecewise-linear input signal between samples.

• bl — Band-limited behavior specifies that the continuous-time input signal has zero power above the Nyquist frequency.

For a single experiment with a single input channel, InterSample contains one of the values in the previous list. For multiple experiments, InterSample is an N_u-by-N_e cell array, where N_u is the number of input channels and N_e is the number of experiments. Each cell contains the behavior value associated with the experiment and input channel that the cell represents.

Name — Name of data set

' ' (default) | character vector

Name of the data set, specified as a character vector.

Example: 'dryer data'

Notes — Comments about data set

' ' (default) | character vector | cell array

Comments about the data set, specified as a character vector or, for multiexperiment data sets, an N_e-by-1 cell array of character vectors, where N_e is the number of experiments.

Example: {'data from experiment 1';data from experiment 2'}

OutputData — Output signal values

vector | matrix

Output signal values from the system, specified as one of the following:

• For a single experiment, an N-by-N_y matrix, where N is the number of data samples and N_y is the number of output channels

• For multiple experiments, a cell array containing N_e single-experiment matrices, where N_e is the number of experiments

When accessing OutputData from the command line, you can use the shorthand form y. For example, y1 = data.InputData is equivalent to y1 = data.y.

OutputName — Output channel names

{'y1';'y2';…} (default) | cell array of character vectors

Output channel names, specified as an N_y-by-1 cell array, where N_y is the number of output channels.

OutputUnit — Output channel units

cell array

Output channel units, specified as an N_y-by-1 cell array, where N_u is the number of output channels. Each cell contains the units of the corresponding input channel.

Example: {'rad';'rad/s'}

Period — Period of input signal

Inf (default) | double | vector | cell array | cell array of character vectors

Period of the input signal, specified as a double for each experiment. The value is either Inf for nonperiodic input signals or the period in the units specified by the property TimeUnit for periodic input signals.

• For a single experiment with a single input channel, Period contains a single value.

• For a multiple-input system, Period is an N_u-by-1 vector, where N_u is the number of input channels and the kth entry contains the period of the kth input.

• For multiple-experiment data, Period is a 1-by-N_e cell array, where N_e is the number of experiments and each cell contains a scalar or vector of periods for the corresponding experiment.

SamplingInstants — Time values for time-domain data

vector | cell array

Time values for time-domain data in units specified by TimeUnit, specified as:

• An N-by-1 vector, where N is the number of data points

• A 1-by-N_e cell array, where N_e is the number of experiments and each cell contains the sampling instants for the corresponding experiment.

The values in SamplingInstants can be uniform or nonuniform. If you specify the Ts property, the software computes uniform time values in SamplingInstants from Ts and Tstart. If you have nonuniform sample points, specify the time values in SamplingInstants. The software then sets the Ts property to empty. Estimation functions do not support nonuniform sampling.

TimeUnit — Units for time variable and sample time Ts

'seconds' (default) | 'nanoseconds' | 'microseconds' | 'milliseconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'years'

Units for the time variable and the sample time, specified as a scalar. This property applies to all experiments in the data set.

Changing this property does not resample or convert the data. Modifying the property changes only the interpretation of the existing data.

Ts — Sample time

1 (default) | positive scalar | 0 | [] | cell array

Sample time in units specified by TimeUnit, specified as a scalar or a cell array. For each experiment, the value is one of the following:

• A scalar, when y and u are uniformly sampled

• 0 for continuous-time data in the frequency domain

• [] when y and u are non uniformly sampled and in the time domain, because the SamplingInstants property sets the time values for such data.

For a single experiment, Ts is a scalar. For multiexperiment data, Ts is a 1-by-N_e cell array, where N_e is the number of experiments and each cell contains the sample time for the corresponding experiment.

For frequency-domain data, the software uses Ts to interpret the data.

• If Ts is 0, the software interprets inputs and outputs as continuous-time Fourier transforms (CTFTs) of the corresponding signals.

• If Ts is a scalar, the software interprets inputs and outputs as discrete-time Fourier transforms (DTFTs) of the corresponding signals with Ts as sample time.

Tstart — Start time for time-domain data

scalar | cell array

Start time for time-domain data, specified as:

• A scalar for a single experiment

• A 1-by-N_e cell array for multiple experiments, where N_e is the number of experiments and each cell contains the start time for the corresponding experiment

The default value of Tstart is Ts for uniformly sampled data and [] for non-uniformly sampled data.

UserData — Additional comments

[] (default) | any MATLAB data type

Additional comments on the data set, specified as any MATLAB data type.

Object Functions

In general, any function applicable to system identification data is applicable to an iddata object. These functions are of three general types.

1. Functions that both operate on and return iddata objects enable you to manipulate and process iddata objects.

   • Use fft and ifft to transform existing iddata objects to and from the time and frequency domains. For example:

     datafd = fft(Data);
     datatd = ifft(Dataf);

   • Use merge (iddata) to merge iddata objects into a single iddata object containing multiple experiments. To extract an experiment from a multiexperiment iddata object, use getexp. For example:

     data123 = merge(data1,data2,data3);
     data2 = getexp(data123,2);
     

     For a more detailed example, see Extract and Model Specific Data Segments.

   • Use preprocessing functions such as detrend or idfilt to filter data in iddata objects and to remove bad data. For example:

     data_d = detrend(data);
     data_f = idfilt(data,filter);

2. Functions that perform analytical processing on iddata objects and create plots or return specific parameters or values let you analyze data and determine inputs to use for estimation.

   • Use analysis functions such as delayest and spa to compute variables such as time delay and frequency spectrum.

3. Functions that use the data in iddata objects to estimate, simulate, and validate models let you create dynamic models and evaluate how closely the model response matches validation data.

   • Use estimation functions such as ssest and tfest to estimate models with specific structures.

   • Use validation functions such as compare and sim to simulate estimated models and compare the simulated outputs with validation data and with other models.

   The following lists contain a representative subset of the functions you can use with iddata objects.

Data Visualization

idplot

Plot input and output channels of estimation data

Data Selection

getexp	Get specific experiments from multiple-experiment data set
merge (iddata)	Merge data sets into iddata object

Data Preprocessing

detrend	Subtract offset or trend from time-domain signals contained in iddata objects
retrend	Add offsets or trends to time-domain data signals stored in iddata objects
idfilt	Filter data using user-defined passbands, general filters, or Butterworth filters
diff	Difference signals in iddata objects
misdata	Reconstruct missing input and output data
idresamp	Resample time-domain data by decimation or interpolation

Data Transformation

fft	Fast Fourier transform (FFT) of iddata object
ifft	Transform iddata objects from frequency to time domain

Data Analysis

realdata	Determine whether iddata is based on real-valued signals
delayest	Estimate time delay (dead time) from data
isreal	Determine whether model parameters or data values are real
impulseest	Nonparametric impulse response estimation
pexcit	Level of excitation of input signals
checkFeedback	Identify possible feedback data
etfe	Estimate empirical transfer functions and periodograms
spafdr	Estimate frequency response and spectrum using spectral analysis with frequency-dependent resolution
spa	Estimate frequency response with fixed frequency resolution using spectral analysis
dataPlotOptions	Option set for idplot when plotting input/output estimation data contained in a timetable, numeric matrices, or an iddata object

Model Estimation, Simulation, and Validation

ssest	Estimate state-space model using time-domain or frequency-domain data
tfest	Estimate transfer function model
ar	Estimate parameters when identifying AR model or ARI model for scalar time series
sim	Simulate response of identified model
findstates	Estimate initial states of model
compare	Compare identified model output with measured output
predict	Predict identified model K-step-ahead output
goodnessOfFit	Goodness of fit between test and reference data for analysis and validation of identified models
procest	Estimate process model using time-domain or frequency-domain data
resid	Compute and test residuals

Examples

Time-Domain Data

Create an iddata object using single-input/single-output (SISO) time-domain data. The input and output each contain 1000 samples with a sample time of 0.08 seconds.

load dryer2_data output input;
data = iddata(output,input,0.08)

data = 
Time domain data set with 1000 samples.
Sample time: 0.08 seconds              
                                       
Outputs      Unit (if specified)       
   y1                                  
                                       
Inputs       Unit (if specified)       
   u1                                  
                                       
Data Properties

The software assigns the default channel name 'y1' to the first and only output channel. When the output signal contains several channels, the software assigns the default names 'y1','y2',...,'yn'. Similarly, the software assigns the default channel name 'u1' to the first and only input channel. For more information about naming channels, see Naming, Adding, and Removing Data Channels.

Plot the data.

idplot(data)

Adjacent plots display output data and input data.

Time-Series Data

Create an iddata object from time-series data. Time-series data has no input channel.

Load the output channel of a data set, and create an iddata object that has a sample time of 0.08 seconds.

load dryer2_data output
data = iddata(output,[],0.08)

data = 
Time domain data set with 1000 samples.
Sample time: 0.08 seconds              
                                       
Outputs      Unit (if specified)       
   y1                                  
                                       
Data Properties

Plot the data.

idplot(data)

You can use data for time-series model estimation.

Convert Timetable to iddata Object

Load the timetable data tt7 and display the first four rows.

load sdata7 tt7
head(tt7,4)

      t      u1      u2           y    
    _____    __    _______    _________

    1 sec     1     0.2749    -0.091981
    2 sec    -1    0.25148      0.22567
    3 sec    -1     1.2381     -0.28617
    4 sec    -1    -1.2216       1.4581

tt7 has two inputs, with variable names u1 and u2 and one output with variable name y. Convert tt7 to an iddata object.

z7conv = iddata(tt7)

z7conv =

Time domain data set with 400 samples.
Sample time: 1 seconds                 
                                       
Outputs      Unit (if specified)       
   y                                   
                                       
Inputs       Unit (if specified)       
   u1                                  
   u2                                  
                                       

z7conv.OutputName

ans = 1×1 cell array
    {'y'}

z7conv.InputName

ans = 2×1 cell
    {'u1'}
    {'u2'}

z7conv retains the sample time, and stores the variable names in the OutputName and InputName properties.

Frequency-Domain Data

Create and examine an iddata object from complex-valued frequency-domain input-output data. Convert the object into the time domain.

Input and output data is sometimes expressed in the form of the Fourier transforms of time-domain input-output signals. You can encapsulate this data in a frequency-domain iddata object.

Load the data, which consists of the complex-valued input-output frequency-domain data U and Y, frequency vector W, and sample time Ts.

load demofr1 U Y W Ts

Create the frequency-domain iddata object data_fr.

data_fr = iddata(Y,U,Ts,'Frequency',W)

data_fr = 
Frequency domain data set with responses at 501 frequencies.
Frequency range: 0 to 31.416 rad/seconds
Sample time: 0.1 seconds                                                                             
                                                                                                     
Outputs      Unit (if specified)                                                                     
   y1                                                                                                
                                                                                                     
Inputs       Unit (if specified)                                                                     
   u1                                                                                                
                                                                                                     
Data Properties

Examine the properties. Frequency-domain iddata objects include frequency-specific properties, such as Frequency for the frequency vector and FrequencyUnit for frequency units. In contrast, time-domain iddata objects include time-specific properties such as Tstart and SamplingInstants for time-domain data.

get(data_fr)

ans = struct with fields:
            Domain: 'Frequency'
              Name: ''
        OutputData: [501×1 double]
        OutputName: {'y1'}
        OutputUnit: {''}
         InputData: [501×1 double]
         InputName: {'u1'}
         InputUnit: {''}
            Period: Inf
       InterSample: 'zoh'
                Ts: 0.1000
     FrequencyUnit: 'rad/TimeUnit'
         Frequency: [501×1 double]
          TimeUnit: 'seconds'
    ExperimentName: 'Exp1'
             Notes: [0×1 string]
          UserData: []

Assign the contents of the frequency property to the variable F.

F = data_fr.Frequency;

Get the frequency units of the data. The property TimeUnit sets the units of the sample time.

frequ = data_fr.FrequencyUnit

frequ = 
'rad/TimeUnit'

timeu = data_fr.TimeUnit

timeu = 
'seconds'

Convert data_fr back into the time domain by using the inverse Fourier transform function ifft.

data_t = ifft(data_fr)

data_t = 
Time domain data set with 1000 samples.
Sample time: 0.1 seconds               
                                       
Outputs      Unit (if specified)       
   y1                                  
                                       
Inputs       Unit (if specified)       
   u1                                  
                                       
Data Properties

get(data_t)

ans = struct with fields:
              Domain: 'Time'
                Name: ''
          OutputData: [1000×1 double]
          OutputName: {'y1'}
          OutputUnit: {''}
           InputData: [1000×1 double]
           InputName: {'u1'}
           InputUnit: {''}
              Period: Inf
         InterSample: 'zoh'
                  Ts: 0.1000
              Tstart: 0.1000
    SamplingInstants: [1000×1 double]
            TimeUnit: 'seconds'
      ExperimentName: 'Exp1'
               Notes: [0×1 string]
            UserData: []

View and Modify Properties

View properties of an iddata object. Modify the properties both during and after object creation.

Load input and output data.

load dryer2_data input output

Create an iddata object.

data = iddata(output,input,0.08)

data = 
Time domain data set with 1000 samples.
Sample time: 0.08 seconds              
                                       
Outputs      Unit (if specified)       
   y1                                  
                                       
Inputs       Unit (if specified)       
   u1                                  
                                       
Data Properties

View all properties of the iddata object.

get(data)

ans = struct with fields:
              Domain: 'Time'
                Name: ''
          OutputData: [1000×1 double]
          OutputName: {'y1'}
          OutputUnit: {''}
           InputData: [1000×1 double]
           InputName: {'u1'}
           InputUnit: {''}
              Period: Inf
         InterSample: 'zoh'
                  Ts: 0.0800
              Tstart: 0.0800
    SamplingInstants: [1000×1 double]
            TimeUnit: 'seconds'
      ExperimentName: 'Exp1'
               Notes: [0×1 string]
            UserData: []

You can specify properties when you create an iddata object using name-value pair arguments. Create an iddata object from the same data inputs, but change the experiment name from its default setting to Dryer2.

data = iddata(output,input,0.08,'ExperimentName','Dryer2')

data = 
Time domain data set with 1000 samples.
Sample time: 0.08 seconds              
                                       
Outputs      Unit (if specified)       
   y1                                  
                                       
Inputs       Unit (if specified)       
   u1                                  
                                       
Data Properties

To change property values for an existing iddata object, use dot notation. Change the sample time property Ts to 0.05 seconds.

data.Ts = 0.05

data = 
Time domain data set with 1000 samples.
Sample time: 0.05 seconds              
                                       
Outputs      Unit (if specified)       
   y1                                  
                                       
Inputs       Unit (if specified)       
   u1                                  
                                       
Data Properties

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

data.exp = "Dryer2 January 2015"

data = 
Time domain data set with 1000 samples.      
Sample time: 0.05 seconds                    
                                             
Outputs                   Unit (if specified)
   y1                                        
                                             
Inputs                    Unit (if specified)
   u1                                        
                                             
Data Properties

You can use data.y as a shorthand for data.OutputData to access the output values, or use data.u as a shorthand for data.InputData to access the input values.

y_data = data.y;
u_data = data.u;

Version History

Introduced before R2006a

R2023a: iddata adds capability to convert timetables to iddata objects

As part of the expansion of System Identification Toolbox™ estimation data formats to timetables and comma-separated matrix pairs, iddata can now convert timetables to iddata objects.

To convert iddata objects to timetables, use iddata2timetable.