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.

.

Creation

Syntax

data = iddata(y,u,Ts)
data = iddata(y,[],Ts)
data = iddata(y,u,Ts,'Frequency',W)
data = iddata(___,Name,Value)

Description

example

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(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

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

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 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 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.

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

plotPlot input and output channels of iddata object
getexpSpecific 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
fftTransform iddata object to frequency domain data
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
feedbackIdentify 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
iddataPlotOptionsOption set for plot when plotting data contained in an iddata object
ssestEstimate state-space model using time-domain or frequency-domain data
tfestEstimate transfer function
arEstimate parameters of AR model or ARI model for scalar time series
simSimulate response of identified model
findstatesEstimate initial states of model
compareCompare identified model output and measured output
predictPredict K-step-ahead model output
goodnessOfFitGoodness of fit between test and reference data for analysis and validation of identified models
procestEstimate process model using time or frequency 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. 

plot(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.

plot(data)

You can use data for time-series model estimation.

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: []
    SamplingInstants: []
            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: []
    SamplingInstants: [1000x0 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;

See Also

|

Topics

Introduced before R2006a

System Identification Toolbox Documentation

Support