Representing Time- and Frequency-Domain Data Using iddata Objects :: Data Import and Processing (System Identification Toolbox™)

On this page…
iddata Constructor iddata Properties Creating Multiexperiment Data at the Command Line Subreferencing iddata Objects Modifying Time and Frequency Vectors Naming, Adding, and Removing Data Channels Concatenating iddata Objects

On this page…

iddata Constructor

iddata Properties

Creating Multiexperiment Data at the Command Line

Subreferencing iddata Objects

Modifying Time and Frequency Vectors

Naming, Adding, and Removing Data Channels

Concatenating 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 Importing Data into the 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 iddata Properties.

In this example, Ts is the sampling time, or the time interval, between successive data samples. For uniformly sampled data, Ts is a scalar value equal to the sampling interval of your experiment. The default time unit is seconds, but you can specify any unit string 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,Ts,[],'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 sampling interval.

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 sampling interval of 0.08 second.

load dryer2                 % Load input u2 and output y2.
data = iddata(y2,u2,0.08)   % Create iddata object.

MATLAB returns the following output:

Time domain data set with 1000 samples.
Sampling interval: 0.08

Outputs     Unit (if specified)
   y1

Inputs      Unit (if specified)
   u1

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

MATLAB returns the following object properties and values:

          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: ''
  ExperimentName: 'Exp1'
           Notes: []
        UserData: []

For a complete description of all properties, see the iddata reference page or type idprops iddata at the prompt.

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 sampling interval 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 SamplingIntervals).

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)           
% Get property values of data
  get(data)

MATLAB returns the following object properties and values:

            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.0800
             Units: 'rad/s'
         Frequency: [501x1 double]
          TimeUnit: ''
    ExperimentName: 'Exp1'
             Notes: []
          UserData: []

Creating Multiexperiment Data at the Command Line

Why Create Multiexperiment Data Sets?

You can create iddata objects that contain several experiments. Identifying models for an iddata object with multiple experiments results in an average model.

In the System Identification Toolbox product, experiments can either mean data collected during different sessions, or portions of the data collected during a single session. In the latter situation, you can create a multiexperiment iddata object by splitting the data from a single session into multiple segments to exclude bad data, and merge the good data portions.

Note The idfrd object does not support the iddata equivalent of multiexperiment data.

Limitations on Data Sets

You can only merge data sets that have all of the following characteristics:

Same number of input and output channels.
Same input and output channel names.
Same data domain (that is, time-domain data or frequency-domain data).

Entering Multiexperiment Data Directly

To construct an iddata object that includes N data sets, you can use this syntax:

data = iddata(y,u,Ts)

where y, u, and Ts are 1-by-N cell arrays containing data from the different experiments. Similarly, when you specify Tstart, Period, InterSample, and SamplingInstants properties of the iddata object, you must assign their values as 1-by-N cell arrays.

Merging Data Sets

Create a multiexperiment iddata object by merging iddata objects, where each contains data from a single experiment or is a multiexperiment data set. For example, you can use the following syntax to merge data:

load iddata1     % Loads iddata object z1
load iddata3     % Loads iddata object z3
z = merge(z1,z3) % Merges experiments z1 and z3 into
                 % the iddata object z

These commands create an iddata object that conatains two experiments, where the experiments are assigned default names 'Exp1' and 'Exp2', respectively.

Adding Experiments to an Existing iddata Object

You can add experiments individually to an iddata object as an alternative approach to merging data sets.

For example, to add the experiments in the iddata object dat4 to data, use the following syntax:

data(:,:,:,'Run4') = dat4

This syntax explicitly assigns the experiment name 'Run4' to the new experiment. The Experiment property of the iddata object stores experiment names.

For more information about subreferencing experiments in a multiexperiment data set, see Subreferencing Experiments.

Subreferencing 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 name strings.

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 name strings. 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)

Modifying Time and Frequency Vectors

The iddata object stores time-domain data or frequency-domain data and has several properties that specify the time or frequency values. To modify the time or frequency values, you must change the corresponding property 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. For more information, see Constructing an iddata Object for Time-Domain Data.

The following tables summarize time-vector and frequency-vector properties, respectively, and provides usage examples. In each example, data is an iddata object.

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

iddata Time-Vector Properties

Property Description Syntax Example

Ts

Sampling time interval.

For a single experiment, Ts is a scalar value.
For multiexperiement data with Ne experiments, Ts is a 1-by-Ne cell array, and each cell contains the sampling interval of the corresponding experiment.

To set the sampling interval to 0.05:

set(data,'ts',0.05)

data.ts = 0.05

Tstart

Starting time of the experiment.

For a single experiment, Ts is a scalar value.
For multiexperiement data with Ne experiments, Ts is a 1-by-Ne cell array, and each cell contains the sampling interval of the corresponding experiment.

To change starting time of the first data sample to 24:

data.Tstart = 24

Time units are set by the property TimeUnit.

SamplingInstants

Time values in the time vector, computed from the properties Tstart and Ts.

For a single experiment, SamplingInstants is an N-by-1 vector.
For multiexperiement data with Ne experiments, this property is a 1-by-Ne cell array, and each cell contains the sampling instants of the corresponding experiment.

To retrieve the time vector for iddata object data, use:

get(data,'sa')

To plot the input data as a function of time:

plot(data.sa,data.u)

Note sa is the first two letters of the SamplingInstants property that uniquely identifies this property.

TimeUnit

Unit of time.

To change the unit of the time vector to msec:

data.ti = 'msec'

iddata Frequency-Vector Properties

Property Description Syntax Example

Property	Description	Syntax Example
`Frequency`	Frequency values at which the Fourier transforms of the signals are defined. For a single experiment, `Frequency` is a scalar value. For multiexperiement data with `Ne` experiments, `Frequency` is a `1`-by-`Ne` cell array, and each cell contains the frequencies of the corresponding experiment.	To specify `100` frequency values in log space, ranging between `0.1` and `100`, use the following syntax: data.freq = logspace(-1,2,100)
`Units`	Frequency unit must have the following values: If the `TimeUnit` is empty or `s` (seconds), enter `rad/s` or `Hz` If the `TimeUnit` is any string unit (other than `s`), enter `rad/`unit. For multiexperiement data with `Ne` experiments, `Units` is a `1`-by-`Ne` cell array, and each cell contains the frequency unit for each experiment.	If you specified the `TimeUnit` as `msec`, your frequency units must be: data.unit= 'rad/msec'

Frequency

Frequency values at which the Fourier transforms of the signals are defined.

For a single experiment, Frequency is a scalar value.
For multiexperiement data with Ne experiments, Frequency is a 1-by-Ne cell array, and each cell contains the frequencies of the corresponding experiment.

To specify 100 frequency values in log space, ranging between 0.1 and 100, use the following syntax:

data.freq =
 logspace(-1,2,100)

Units

Frequency unit must have the following values:

If the TimeUnit is empty or s (seconds), enter rad/s or Hz
If the TimeUnit is any string unit (other than s), enter rad/unit.

For multiexperiement data with Ne experiments, Units is a 1-by-Ne cell array, and each cell contains the frequency unit for each experiment.

If you specified the TimeUnit as msec, your frequency units must be:

data.unit=
 'rad/msec'

Naming, Adding, and Removing Data Channels

What Are Input and Output Channels?

A multivariate system might contain several input variables or several output variables, or both. When an input or output signal includes several measured variables, these variables are called channels.

Naming Channels

The iddata properties InputName and OutputName store the channel names for the input and output signals. When you plot the data, you use channel names to select the variable displayed on the plot. If you have multivariate data, it is helpful to assign a name to each channel that describes the measured variable. For more information about selecting channels on a plot, see Selecting Measured and Noise Channels in Plots.

You can use the set command to specify the names of individual channels. For example, suppose data contains two input channels (voltage and current) and one output channel (temperature). To set these channel names, use the following syntax:

set(data,'InputName',{'Voltage','Current'},
         'OutputName','Temperature')

Tip You can also specify channel names as follows:

data.una = {'Voltage','Current')
data.yna = 'Temperature'

una is equivalent to the property InputName, and yna is equivalent to OutputName.

If you do not specify channel names when you create the iddata object, the toolbox assigns default names. By default, the output channels are named 'y1','y2',...,'yn', and the input channels are named 'u1','u2',...,'un'.

Adding Channels

You can add data channels to an iddata object.

For example, consider an iddata object named data that contains an input signal with four channels. To add a fifth input channel, stored as the vector Input5, use the following syntax:

data.u(:,5) = Input5;

Input5 must have the same number of rows as the other input channels. In this example, data.u(:,5) references all samples as (indicated by :) of the input signal u and sets the values of the fifth channel. This channel is created when assigning its value to Input5.

You can also combine input channels and output channels of several iddata objects into one iddata object using concatenation. For more information, see Concatenating iddata Objects.

Modifying Channel Data

After you create an iddata object, you can modify or remove specific input and output channels, if needed. You can accomplish this by subreferencing the input and output matrices and assigning new values.

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 replace data such that it only contains samples in y3, u1, and u4, type the following at the prompt:

data = data(:,3,[1 4])

The resulting data object contains one output channel and two input channels.

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

Importing Data into the GUI

Representing Frequency-Response Data Using idfrd Objects

Free Control Systems Interactive Kit

Learn more about resources for designing, testing, and implementing control systems.

Get free kit

Trials Available

Try the latest control systems products.

Get trial software

Products & Services	Solutions	Academia	Support	User Community	Company