Data Acquisition Toolbox™

getdata

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

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 up to the time of the `getdata` call.

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 up to the getdata call. The possible events that can be returned are identical to 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`.

Remarks

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

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;