Main Content

iddata

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

expand all in page

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.

example

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.

example

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.

example

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.

example

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.

example

Input Arguments

expand all

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 Ne element cell array for a multiexperiment data set, where Ne 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.

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-Nu matrix for a multiple-input system, where Nu is the number of input channels

  • An Ne element cell array for a multiexperiment data set, where Ne 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.

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.

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

expand all

Data time or frequency domain, specified as either:

  • 'Time' — Data is in the time domain

  • 'Frequency' — Data is in the frequency domain

Name of each data set contained in the iddata object, specified as an Ne-by-1 cell array of character vectors, where Ne 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 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-Ne cell array, where Ne 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.

Frequency units for frequency-domain data, specified as one of the following:

  1. A scalar for a single experiment.

    A 1-by-Ne cell array, where Ne is the number of experiments. Because all Frequency vectors must have the same units, all values of FrequencyUnit must be the same.

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

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

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

  • For multiple experiments, a cell array containing Ne single-experiment matrices, where Ne 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.

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

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

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

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 Nu-by-Ne cell array, where Nu is the number of input channels and Ne is the number of experiments. Each cell contains the behavior value associated with the experiment and input channel that the cell represents.

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

Example: 'dryer data'

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

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

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

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

  • For multiple experiments, a cell array containing Ne single-experiment matrices, where Ne 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.

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

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

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

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 Nu-by-1 vector, where Nu 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-Ne cell array, where Ne is the number of experiments and each cell contains a scalar or vector of periods for the corresponding experiment.

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-Ne cell array, where Ne 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.

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.

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-Ne cell array, where Ne 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.

Start time for time-domain data, specified as:

  • A scalar for a single experiment

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

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.

expand all

idplotPlot input and output channels of estimation data
getexpGet specific experiments from multiple-experiment data set
merge (iddata)Merge data sets into iddata object
detrendSubtract offset or trend from time-domain signals contained in iddata objects
retrendAdd offsets or trends to time-domain data signals stored in iddata objects
idfiltFilter data using user-defined passbands, general filters, or Butterworth filters
diffDifference signals in iddata objects
misdataReconstruct missing input and output data
idresampResample time-domain data by decimation or interpolation
fftFast Fourier transform (FFT) of iddata object
ifftTransform iddata objects from frequency to time domain
realdataDetermine whether iddata is based on real-valued signals
delayestEstimate time delay (dead time) from data
isrealDetermine whether model parameters or data values are real
impulseestNonparametric impulse response estimation
pexcitLevel of excitation of input signals
checkFeedbackIdentify possible feedback data
etfeEstimate empirical transfer functions and periodograms
spafdrEstimate frequency response and spectrum using spectral analysis with frequency-dependent resolution
spaEstimate frequency response with fixed frequency resolution using spectral analysis
dataPlotOptionsOption set for idplot when plotting input/output estimation data contained in a timetable, numeric matrices, or an iddata object
ssestEstimate state-space model using time-domain or frequency-domain data
tfestEstimate transfer function model
arEstimate parameters when identifying AR model or ARI model for scalar time series
simSimulate response of identified model
findstatesEstimate initial states of model
compareCompare identified model output with measured output
predictPredict identified model K-step-ahead output
goodnessOfFitGoodness of fit between test and reference data for analysis and validation of identified models
procestEstimate process model using time-domain or frequency-domain data
residCompute and test residuals

Examples

collapse all

Open Live Script

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

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)

Figure contains 2 axes objects. Axes object 1 with title y1 contains an object of type line. This object represents data. Axes object 2 with title u1 contains an object of type line. This object represents data.

Adjacent plots display output data and input data.

Open Live Script

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

Plot the data.

idplot(data)

Figure contains an axes object. The axes object with title y1 contains an object of type line. This object represents data.

You can use data for time-series model estimation.

Open Live Script

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.

Open Live Script

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

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: [501x1 double]
                 y: 'Same as OutputData'
        OutputName: {'y1'}
        OutputUnit: {''}
         InputData: [501x1 double]
                 u: 'Same as InputData'
         InputName: {'u1'}
         InputUnit: {''}
            Period: Inf
       InterSample: 'zoh'
                Ts: 0.1000
     FrequencyUnit: 'rad/TimeUnit'
         Frequency: [501x1 double]
          TimeUnit: 'seconds'
    ExperimentName: 'Exp1'
             Notes: {}
          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                                   
                                        

get(data_t)
ans = struct with fields:
              Domain: 'Time'
                Name: ''
          OutputData: [1000x1 double]
                   y: 'Same as OutputData'
          OutputName: {'y1'}
          OutputUnit: {''}
           InputData: [1000x1 double]
                   u: 'Same as InputData'
           InputName: {'u1'}
           InputUnit: {''}
              Period: Inf
         InterSample: 'zoh'
                  Ts: 0.1000
              Tstart: 0.1000
    SamplingInstants: [1000x1 double]
            TimeUnit: 'seconds'
      ExperimentName: 'Exp1'
               Notes: {}
            UserData: []
Open Live Script

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

View all properties of the iddata object. 

get(data)
ans = struct with fields:
              Domain: 'Time'
                Name: ''
          OutputData: [1000x1 double]
                   y: 'Same as OutputData'
          OutputName: {'y1'}
          OutputUnit: {''}
           InputData: [1000x1 double]
                   u: 'Same as InputData'
           InputName: {'u1'}
           InputUnit: {''}
              Period: Inf
         InterSample: 'zoh'
                  Ts: 0.0800
              Tstart: 0.0800
    SamplingInstants: [1000x1 double]
            TimeUnit: 'seconds'
      ExperimentName: 'Exp1'
               Notes: {}
            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 =

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

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 =

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

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 =

Experiment Dryer2 January 2015.Time domain data set with 1000 samples.
Sample time: 0.05 seconds                                              
                                                                       
Outputs                   Unit (if specified)                          
   y1                                                                  
                                                                       
Inputs                    Unit (if specified)                          
   u1

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

expand all

See Also

|

Topics