Documentation Center

  • Trial Software
  • Product Updates

getdata

Extract analog input data, time, and event information from data acquisition engine

Syntax

data = getdata(obj)
data = getdata(obj,samples)
data = getdata(obj,samples,'type')
[data,time] = getdata(...)
[data,time,abstime] = getdata(...)
[data,time,abstime,events] = getdata(...)
[data,...] = getdata(obj, 'P1', V1, 'P2', V2,...)

    Note:   You cannot use the legacy interface on 64–bit MATLAB®. See Session-Based Interface to acquire and generate data.

Arguments

obj

An analog input object.

samples

The number of samples to extract. If samples is not specified, the number of samples extracted is given by the SamplesPerTrigger property.

'type'

Specifies the format of the extracted data as double (the default) or as native.

data

An m-by-n array, where m is the number of samples extracted and n is the number of channels contained by obj.

time

An m-by-1 array of relative time values in seconds, where m is the number of samples extracted. time = 0 is defined as the point at which data logging begins, i.e., when the Logging property of obj is set to On. Measurement of time, with respect to 0, continues until the acquisition is stopped, i.e., when the Logging property of obj is set to Off.

abstime

The absolute time of the first trigger returned as a clock vector. This value is identical to the value stored by the InitialTriggerTime property.

events

A structure containing a list of events that occurred during the time period the samples were extracted.

Description

data = getdata(obj) extracts the number of samples specified by the SamplesPerTrigger property for each channel contained by obj. data is an m-by-n array, where m is the number of samples extracted and n is the number of channels.

data = getdata(obj,samples) extracts the number of samples specified by samples for each channel contained by obj.

data = getdata(obj,samples,'type') extracts the number of samples specified by samples in the format specified by type for each channel contained by obj.

[data,time] = getdata(...) returns data as sample-time pairs. time is an m-by-1 array of relative time values, where m is the number of samples returned in data. Each element of time indicates the relative time, in seconds, of the corresponding sample in data, measured with respect to the first sample logged by the engine.

[data,time,abstime] = getdata(...) extracts data as sample-time pairs and returns the absolute time of the trigger. The absolute time is returned as a clock vector and is identical to the value stored by the InitialTriggerTime property.

[data,time,abstime,events] = getdata(...) extracts data as sample-time pairs, returns the absolute time of the trigger, and returns a structure containing a list of events that occurred during the time period the samples were extracted. The events returned are a sub set of those stored by the EventLog property.

[data,...] = getdata(obj, 'P1', V1, 'P2', V2,...) specifies the number of samples to be returned, the format of the data matrix, and whether to return a tscollection object.

The following table shows a summary of properties.

Property

Description

Samples

Specify the number of samples to return.

DataFormat

Specify the data format as double (default) or native.

OutputFormat

Specify the output format as matrix (default) or tscollection.

    Note:   When the ClockSource property for this function is set to one of the External options, the timing will be controlled externally and the values returned in the time variable will not accurately reflect the actual relative time of each sample. It is however an approximation based on the SampleRate you have configured.

Examples

Create the analog input object ai for a National Instruments® board and add hardware channels 0 to 3 to it.

ai = analoginput('nidaq','Dev1');
addchannel(ai,0:3);

Configure a 1-second acquisition with SampleRate set to 1000 samples per second and SamplesPerTrigger set to 1000 samples per trigger.

set(ai,'SampleRate',1000)
set(ai,'SamplesPerTrigger',1000)
start(ai)

The following getdata command blocks execution control until all sample-time pairs, the absolute time of the trigger, and any events that occurred during the getdata call are returned.

wait(ai,1)
[data,time,abstime,events] = getdata(ai);

data is returned as a 1000-by-4 array of doubles, time is returned as a 1000-by-1 vector of relative times, abstime is returned as a clock vector, and events is returned as a 3-by-1 structure array.

To extract the 1000 data samples from hardware channel 0 only, examine the first column of data.

chan0_data = data(:,1);

The three events returned are the start event, the trigger event, and the stop event. To return specific event information about the stop event, you must access the Type and Data fields.

EventType = events(3).Type;
EventData = events(3).Data;

More About

expand all

Tips

More About getdata

  • In most circumstances, getdata returns all requested data and does not miss any samples. In the unlikely event that the engine cannot keep pace with the hardware device, it is possible that data is missed. If data is missed, the DataMissedFcn property is called and the device object is stopped.

  • getdata is a blocking function because it returns execution control to the MATLAB workspace only when the requested number of samples is extracted from the engine for each channel group member.

  • You can issue ^C (Ctrl+C) while getdata is blocking. This will not stop the acquisition but will return control to the MATLAB software.

  • The amount of data that you can extract from the engine is given by the SamplesAvailable property.

  • It is a good practice to use a wait command before your getdata command if the getdata is going to get all data returned by the analog input subsystem. For example, if your analog input object is ai and you have set duration to be the number of seconds for the acquisition, you could add the following line right before the getdata:

    wait(ai,duration+1)
  • Setting the OutputFormat property to tscollection causes getdata to return a tscollection object. In this case, only the data left-hand argument is used.

  • For more information on using the Time Series functionality, see Example: Time Series Objects and Methods in the MATLAB documentation.

More About Extracting Data From the Engine

  • After the requested data is extracted from the engine, the SamplesAvailable property value is automatically reduced by the number of samples returned.

  • If the requested number of samples is greater than the samples to be acquired, then an error is returned.

  • If the requested data is not returned in the expected amount of time, an error is returned. The expected time to return data is given by the time it takes the engine to fill one data block plus the time specified by the Timeout property.

  • If multiple triggers are included in a single getdata call, a NaN is inserted into the returned data and time arrays and the absolute time returned is given by the first trigger.

  • When you use multiple immediate triggers Data Acquisition Toolbox™ cannot determine the "dead" time between triggers. Because of this, the toolbox assumes the "dead" time = 1 sample. For example if the sample rate is 1000 samples per second the toolbox assumes the "dead" time between triggers is one millisecond. The time argument returned by getdata reflects this assumption.

See Also

| | | | | | | | | |

Was this topic helpful?