iddata

Time- or frequency-domain data

Syntax

data = iddata(y,[],Ts)
data = iddata(y,u,Ts)
data = iddata(y,u,Ts,'Frequency',W)
data = iddata(y,u,Ts,'P1',V1,...,'PN',VN)
data = iddata(idfrd_object)

Description

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

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

data = iddata(y,u,Ts,'Frequency',W) creates an iddata object containing a frequency-domain output signal y and input signal u, respectively.Ts specifies the sampling interval of the experimental data. W specifies the iddata property 'frequency' as a vector of frequencies.

data = iddata(y,u,Ts,'P1',V1,...,'PN',VN) creates an iddata object containing a time-domain or frequency-domain output signal y and input signal u, respectively. Ts specifies the sampling interval of the experimental data. 'P1',V1,...,'PN',VN are property-value pairs, as described in Properties.

data = iddata(idfrd_object) transforms an idfrd object to a frequency-domain iddata object.

Arguments

y

Name of MATLAB® variable that represents the output signal from a system. Sets the OutputData iddata property. For a single-output system, this is a column vector. For a multiple-output system with Ny output channels and NT time samples, this is an NT-by-Ny matrix.

    Note:   Output data must be in the same domain as input data.

u

Name of MATLAB variable that represents the input signal to a system. Sets the InputData iddata property. For a single-input system, this is a column vector. For a multiple-output system with Nu output channels and NT time samples, this is an NT-by-Nu matrix.

    Note:   Input data must be in the same domain as output data.

Ts

Time interval between successive data samples in seconds. Default value is 1. For continuous-time data in the frequency domain, set Ts to 0.

'P1',V1,...,'PN',VN

Pairs of iddata property names and property values.

idfrd_object

Name of idfrd data object.

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 Time-Domain Data Representation.

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.

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

  • For nonuniformly sampled data, Ts is [], and the value of the SamplingInstants property is 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.

    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.

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

Properties

After creating the object, you can use get or dot notation to access the object property values.

Use set or dot notation to set a property of an existing object.

The following table describes iddata object properties and their values. These properties are specified as property-value arguments 'P1',V1,...,'PN',VN' in the iddata constructor, or you can set them using the set command or dot notation. In the list below, N denotes the number of data samples in the input and output signals, ny is the number of output channels, nu is the number of input channels, and Ne is the number of experiments.

    Tip   Property names are not case sensitive. You do not need to type the entire property name. However, the portion you enter must by enough to uniquely identify the property.

Property NameDescriptionValue
Domain

Specifies whether the data is in the time domain or frequency domain.

  • 'Frequency' — Frequency-domain data.

  • 'Time' (Default) — Time-domain data.

ExperimentNameName of each data set contained in the iddata object.For Ne experiments, a 1-by-Ne cell array of strings. Each cell contains the name of the corresponding experiment. Default names are {'Exp1', 'Exp2',...}.
Frequency(Frequency-domain data only)

Frequency values for defining the Fourier Transforms of the signals.

For a single experiment, this is an N-by-1 vector. For Ne experiments, a 1-by-Ne cell array and each cell contains the frequencies of the corresponding experiment.

InputData

Name of MATLAB variable that stores the input signal to a system.

For nu input channels and N data samples, this is an N-by-nu matrix.
InputNameSpecifies the names of individual input channels.Cell array of length nu-by-1 contains the name string of each input channel. Default names are {'u1';'u2';...}.
InputUnitSpecifies the units of each input channel.Cell array of length nu-by-1. Each cell contains a string that specifies the units of each input channel.
InterSampleSpecifies the behavior of the input signals between samples for transformations between discrete-time and continuous-time.

For a single experiment:

  • zoh— (Default) 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 Ne experiments, InterSample is an nu-by-Ne cell array. Each cell contains one of these values corresponding to each experiment.

NameName of the data set. Text string.
NotesComments about the data set.Text string.
OutputData

Name of MATLAB variable that stores the output signal from a system.

For ny output channels and N samples, this is an N-by-ny matrix.

OutputNameFor a multiple-output system, specifies the names of individual output channels.Cell array of length ny-by-1 contains the name string of each output channel. Default names are {'y1';'y2';...}.
OutputUnitSpecifies the units of each output channel.For ny output channels, a cell array of length ny-by-1. Each cell contains a string that specifies the units of the corresponding output channel.
PeriodPeriod of the input signal.(Default) For a nonperiodic signal, set to inf. For a multiple-input signal, this is an nu-by-1 vector and the kth entry contains the period of the kth input. For Ne experiments, this is a 1-by-Ne cell array and each cell contains a scalar or vector of periods for the corresponding experiment.
SamplingInstants(Time-domain data only) The time values in the time vector calculated from the properties Tstart and Ts.

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

TimeUnit(Time-domain data only) Time unit.A string that specifies the time unit for the time vector. Specify TimeUnit as one of the following: 'nanoseconds','microseconds','milliseconds','seconds' (default), 'minutes','hours', 'days', 'weeks', 'months' or 'years'.
TsTime interval between successive data samples in seconds. Must be specified for both time- and frequency-domain data. For frequency-domain, it is used to compute Fourier transforms of the signals as discrete-time Fourier transforms (DTFT) with the indicated sampling interval.

    Note:   Your data must be uniformly sampled.

Default value is 1. For continuous-time data in the frequency domain, set to 0; the inputs and outputs are interpreted as continuous-time Fourier transforms of the signals. Note that Ts is essential also for frequency-domain data, for proper interpretation of how the Fourier transforms were computed: They are interpreted as discrete-time Fourier transforms (DTFT) with the indicated sampling interval.. For multiple-experiment data, Ts is a 1-by-Ne cell array and each cell contains the sampling interval of the corresponding experiment.
Tstart(Time-domain data only) Specifies the start time of the time vector.

For a single experiment, this is a scalar. For Ne experiments, Tstart is a 1-by-Ne cell array and each cell contains the starting time of the corresponding experiment.

FrequencyUnit(Frequency-domain data only)

Frequency unit.

Specifies the units of the frequency vector (see Frequency). Specify as one of the following: 'rad/TimeUnit', 'cycles/TimeUnit', 'rad/s', 'Hz', 'kHz', 'MHz', 'GHz', or 'rpm'. The units 'rad/TimeUnit' and 'cycles/TimeUnit' are relative to the time units specified in the TimeUnitproperty. Setting FrequencyUnit does not change the frequency vector. To convert the units and automatically scale frequency points, use chgFreqUnit.
UserDataAdditional comments.Text string.

To view the properties, use the get command. For example:

load dryer2                 % Load input u2 and output y2
data = iddata(y2,u2,0.08);  % Create iddata object
get(data)                   % Get property values of data

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). For example:

% 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)
Was this topic helpful?