Representing Time- and Frequency-Domain Data Using iddata Objects

Representing Time- and Frequency-Domain Data Using `iddata` Objects

iddata Constructor

Requirements for Constructing an iddata Object

To construct an iddata object, you must have already imported data into the MATLAB^® workspace, as described in Representing Data in MATLAB Workspace.

Constructing an iddata Object for Time-Domain Data

Use the following syntax to create a time-domain iddata object data:

data = iddata(y,u,Ts)

You can also specify additional properties, as follows:

data = iddata(y,u,Ts,'Property1',Value1,...,'PropertyN',ValueN)

For more information about accessing object properties, see Properties.

In this example, Ts is the sample time, or the time interval, between successive data samples. For uniformly sampled data, Ts is a scalar value equal to the sample time of your experiment. The default time unit is seconds, but you can set it to a new value using the TimeUnit property. For more information about iddata time properties, see Modifying Time and Frequency Vectors.

For nonuniformly sampled data, specify Ts as [], and set the value of the SamplingInstants property as a column vector containing individual time values. For example:

data = iddata(y,u,[],'SamplingInstants',TimeVector)

Where TimeVector represents a vector of time values.

Note

You can modify the property SamplingInstants by setting it to a new vector with the length equal to the number of data samples.

To represent time-series data, use the following syntax:

ts_data = iddata(y,[],Ts)

where y is the output data, [] indicates empty input data, and Ts is the sample time.

The following example shows how to create an iddata object using single-input/single-output (SISO) data from dryer2.mat. The input and output each contain 1000 samples with the sample time of 0.08 second.

% Load input u2 and output y2 .
load dryer2                 
% Create iddata object.
data = iddata(y2,u2,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 default channel name 'y1' is assigned to the first and only output channel. When y2 contains several channels, the channels are assigned default names 'y1','y2','y2',...,'yn'. Similarly, the default channel name 'u1' is assigned to the first and only input channel. For more information about naming channels, see Naming, Adding, and Removing Data Channels.

Constructing an iddata Object for Frequency-Domain Data

Frequency-domain data is the Fourier transform of the input and output signals at specific frequency values. To represent frequency-domain data, use the following syntax to create the iddata object:

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

'Frequency' is an iddata property that specifies the frequency values w, where w is the frequency column vector that defines the frequencies at which the Fourier transform values of y and u are computed. Ts is the time interval between successive data samples in seconds for the original time-domain data. w, y, and u have the same number of rows.

Note

You must specify the frequency vector for frequency-domain data.

For more information about iddata time and frequency properties, see Modifying Time and Frequency Vectors.

To specify a continuous-time system, set Ts to 0.

You can specify additional properties when you create the iddata object, as follows:

data = iddata(y,u,Ts,'Property1',Value1,...,'PropertyN',ValueN)

For more information about accessing object properties, see Properties.

iddata Properties

To view the properties of the iddata object, use the get command. For example, type the following commands at the prompt:

% Load input u2 and output y2.
load dryer2                 
% Create iddata object.
data = iddata(y2,u2,0.08);  
% Get property values of data.
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: []

For a complete description of all properties, see the iddata reference page.

You can specify properties when you create an iddata object using the constructor syntax:

data = iddata(y,u,Ts,'Property1',Value1,...,'PropertyN',ValueN)

To change property values for an existing iddata object, use the set command or dot notation. For example, to change the sample time to 0.05, type the following at the prompt:

set(data,'Ts',0.05)

or equivalently:

data.ts = 0.05

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.

Tip

You can use data.y as an alternative to data.OutputData to access the output values, or use data.u as an alternative to data.InputData to access the input values.

An iddata object containing frequency-domain data includes frequency-specific properties, such as Frequency for the frequency vector and Units for frequency units (instead of Tstart and SamplingInstants).

To view the property list, type the following command sequence at the prompt:

% Load input u2 and output y2.
  load dryer2;
% Create iddata object.
  data = iddata(y2,u2,0.08);
% Take the Fourier transform of the data
% transforming it to frequency domain.
  data = fft(data)

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

% Get property values of data.
  get(data)

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.0800
     FrequencyUnit: 'rad/TimeUnit'
         Frequency: [501×1 double]
          TimeUnit: 'seconds'
    ExperimentName: 'Exp1'
             Notes: [0×1 string]
          UserData: []

Select Data Channels, I/O Data and Experiments in iddata Objects

Subreferencing Input and Output Data

Subreferencing data and its properties lets you select data values and assign new data and property values.

Use the following general syntax to subreference specific data values in iddata objects:

data(samples,outputchannels,inputchannels,experimentname)

In this syntax, samples specify one or more sample indexes, outputchannels and inputchannels specify channel indexes or channel names, and experimentname specifies experiment indexes or names.

For example, to retrieve samples 5 through 30 in the iddata object data and store them in a new iddata object data_sub, use the following syntax:

data_sub = data(5:30)

You can also use logical expressions to subreference data. For example, to retrieve all data values from a single-experiment data set that fall between sample instants 1.27 and 9.3 in the iddata object data and assign them to data_sub, use the following syntax:

data_sub = data(data.sa>1.27&data.sa<9.3)

Note

You do not need to type the entire property name. In this example, sa in data.sa uniquely identifies the SamplingInstants property.

You can retrieve the input signal from an iddata object using the following commands:

u = get(data,'InputData')

data.InputData

data.u    % u is the abbreviation for InputData

Similarly, you can retrieve the output data using

data.OutputData

data.y    % y is the abbreviation for OutputData

Subreferencing Data Channels

Use the following general syntax to subreference specific data channels in iddata objects:

data(samples,outputchannels,inputchannels,experiment)

To specify several channel names, you must use a cell array of character vectors of names.

For example, suppose the iddata object data contains three output channels (named y1, y2, and y3), and four input channels (named u1, u2, u3, and u4). To select all data samples in y3, u1, and u4, type the following command at the prompt:

% Use a cell array to reference
% input channels 'u1' and 'u4'
data_sub = data(:,'y3',{'u1','u4'})

or equivalently

% Use channel indexes 1 and 4
% to reference the input channels
  data_sub = data(:,3,[1 4])

Tip

Use a colon (:) to specify all samples or all channels, and the empty matrix ([]) to specify no samples or no channels.

If you want to create a time-series object by extracting only the output data from an iddata object, type the following command:

data_ts = data(:,:,[])

You can assign new values to subreferenced variables. For example, the following command assigns the first 10 values of output channel 1 of data to values in samples 101 through 110 in the output channel 2 of data1. It also assigns the values in samples 101 through 110 in the input channel 3 of data1 to the first 10 values of input channel 1 of data.

data(1:10,1,1) = data1(101:110,2,3)

Subreferencing Experiments

Use the following general syntax to subreference specific experiments in iddata objects:

data(samples,outputchannels,inputchannels,experimentname)

When specifying several experiment names, you must use a cell array of character vectors of names. The iddata object stores experiments name in the ExperimentName property.

For example, suppose the iddata object data contains five experiments with default names, Exp1, Exp2, Exp3, Exp4, and Exp5. Use the following syntax to subreference the first and fifth experiment in data:

data_sub = data(:,:,:,{'Exp1','Exp5'}) % Using experiment name

data_sub = data(:,:,:,[1 5])           % Using experiment index

Tip

Use a colon (:) to denote all samples and all channels, and the empty matrix ([]) to specify no samples and no channels.

Alternatively, you can use the getexp command. The following example shows how to subreference the first and fifth experiment in data:

data_sub = getexp(data,{'Exp1','Exp5'}) % Using experiment name

data_sub = getexp(data,[1 5])           % Using experiment index

The following example shows how to retrieve the first 100 samples of output channels 2 and 3 and input channels 4 to 8 of Experiment 3:

dat(1:100,[2,3],[4:8],3)

Increasing Number of Channels or Data Points of iddata Objects

iddata Properties Storing Input and Output Data

The InputData iddata property stores column-wise input data, and the OutputData property stores column-wise output data. For more information about accessing iddata properties, see iddata Properties.

Horizontal Concatenation

Horizontal concatenation of iddata objects creates a new iddata object that appends all InputData information and all OutputData. This type of concatenation produces a single object with more input and output channels. For example, the following syntax performs horizontal concatenation on the iddata objects data1,data2,...,dataN:

data = [data1,data2,...,dataN]

This syntax is equivalent to the following longer syntax:

data.InputData =
     [data1.InputData,data2.InputData,...,dataN.InputData]
data.OutputData =
     [data1.OutputData,data2.OutputData,...,dataN.OutputData]

For horizontal concatenation, data1,data2,...,dataN must have the same number of samples and experiments , and the sameTs and Tstart values.

The channels in the concatenated iddata object are named according to the following rules:

Combining default channel names — If you concatenate iddata objects with default channel names, such as u1 and y1, channels in the new iddata object are automatically renamed to avoid name duplication.
Combining duplicate input channels — If data1,data2,...,dataN have input channels with duplicate user-defined names, such that dataK contains channel names that are already present in dataJ with J < K, the dataK channels are ignored.
Combining duplicate output channels — If data1,data2,...,dataN have input channels with duplicate user-defined names, only the output channels with unique names are added during the concatenation.

Vertical Concatenation

Vertical concatenation of iddata objects creates a new iddata object that vertically stacks the input and output data values in the corresponding data channels. The resulting object has the same number of channels, but each channel contains more data points. For example, the following syntax creates a data object such that its total number of samples is the sum of the samples in data1,data2,...,dataN.

data = [data1;data2;... ;dataN]

This syntax is equivalent to the following longer syntax:

data.InputData =
     [data1.InputData;data2.InputData;...;dataN.InputData]
data.OutputData =
     [data1.OutputData;data2.OutputData;...;dataN.OutputData]

For vertical concatenation, data1,data2,...,dataN must have the same number of input channels, output channels, and experiments.