daqread

Read Data Acquisition Toolbox (.daq) file

Syntax

data = daqread('filename') [data,time] = daqread(...) [data,time,abstime] = daqread(...) [data,time,abstime,events] = daqread(...) [data,time,abstime,events,daqinfo] = daqread(...) data = daqread(...,'Param1', Val1,...) daqinfo = daqread('filename','info')

Description

data = daqread('filename') reads all the data from the Data Acquisition Toolbox™ (.daq) file specified by filename. daqread returns data, an m-by-n data matrix, where m is the number of samples and n is the number of channels. If data includes data from multiple triggers, the data from each trigger is separated by a NaN. If you set the OutputFormat property to tscollection, daqread returns a time series collection object. See below for more information.

[data,time] = daqread(...) returns time/value pairs. time is an m-by-1 vector, the same length as data, that contains the relative time for each sample. Relative time is measured with respect to the first trigger that occurs.

[data,time,abstime] = daqread(...) returns the absolute time of the first trigger. abstime is returned as a clock vector.

[data,time,abstime,events] = daqread(...) returns a log of events. events is a structure containing event information. If you specify either theSamples, Time, or Triggers parameters (see below), the events structure contains only the specified events.

[data,time,abstime,events,daqinfo] = daqread(...) returns a structure, daqinfo, that contains two fields: ObjInfo and HwInfo. ObjInfo is a structure containing property name/property value pairs and HwInfo is a structure containing hardware information. The entire event log is returned to daqinfo.ObjInfo.EventLog.

data = daqread(...,'Param1', Val1,...) specifies the amount of data returned and the format of the data, using the following parameters.

Parameter	Description
`Samples`	Specify the sample range.
`Time`	Specify the relative time range.
`Triggers`	Specify the trigger range.
`Channels`	Specify the channel range. Channel names can be specified as a cell array.
`DataFormat`	Specify the data format as `doubles` (default) or `native`.
`TimeFormat`	Specify the time format as `vector` (default) or `matrix`.
`OutputFormat`	Specify the output format as `matrix` (the default) or `tscollection`. When you specify `tscollection`, `daqread` only returns `data`.

The Samples, Time, and Triggers properties are mutually exclusive; that is, either Samples, Triggers or Time can be defined at once.

daqinfo = daqread('filename','info') returns metadata from the file in the daqinfo structure, without incurring the overhead of reading the data from the file as well. The daqinfo structure contains two fields:

daqinfo.ObjInfo: a structure containing parameter/value pairs for the data acquisition object used to create the file, filename. Note: The UserData property value is not restored.
daqinfo.HwInfo: a structure containing hardware information. The entire event log is returned to daqinfo.ObjInfo.EventLog.

Examples

Use Data Acquisition Toolbox to acquire data. The analog input object, ai, acquires one second of data for four channels, and saves the data to the output file data.daq.

ai = analoginput('nidaq','Dev1');
chans = addchannel(ai,0:3);
set(ai,'SampleRate',1000)
ActualRate = get(ai,'SampleRate');
set(ai,'SamplesPerTrigger, ActualRate)
set(ai,'LoggingMode','Disk&Memory')
set(ai,'LogFileName','data.daq')
start(ai)

After the data has been collected and saved to a disk file, you can retrieve the data and other acquisition related information using daqread.

Read all the sample-time pairs from data.daq:

[data,time] = daqread('data.daq');

Read samples 500 to 1000 for all channels from data.daq:

data = daqread('data.daq','Samples',[500 1000]);

Read only samples 1000 to 2000 of channel indices 2, 4, and 7 in native format from the file data.daq:

data = daqread('data.daq', 'Samples', [1000 2000],...
               'Channels', [2 4 7], 'DataFormat', 'native');

Read only the data that represents the first and second triggers on all channels from the file data.daq:

[data,time] = daqread('data.daq', 'Triggers', [1 2]);

Obtain the channel property information from data.daq:

daqinfo = daqread('data.daq','info');
chaninfo = daqinfo.ObjInfo.Channel;

Obtain a list of event types and event data contained in data.daq:

daqinfo = daqread('data.daq','info');
events = daqinfo.ObjInfo.EventLog;
event_type = {events.Type};
event_data = {events.Data};

Read all the data from the file data.daq and return it as a time series collection object:

data = daqread('data.daq','OutputFormat','tscollection');

Tips

More About .daq Files

The format used by daqread to return data, relative time, absolute time, and event information is identical to the format used by the getdata function that is part of Data Acquisition Toolbox. For more information, see the Data Acquisition Toolbox documentation.
If data from multiple triggers is read, then the size of the resulting data array is increased by the number of triggers issued because each trigger is separated by a NaN.
ObjInfo.EventLog always contains the entire event log regardless of the value specified by Samples, Time, or Triggers.
The UserData property value is not restored when you return device object (ObjInfo) information.
When reading a .daq file, the daqread function does not return property values that were specified as a cell array.
Data Acquisition Toolbox (.daq) files are created by specifying a value for the LogFileName property (or accepting the default value), and configuring the LoggingMode property to Disk or Disk&Memory.

More About Time Series Collection Object Returned

When OutputFormat is set to tscollection, daqread returns a time series collection object. This time series collection object contains an absolute time series object for each channel in the file. The following describes how daqread sets some of the properties of the time series collection object and the time series objects.

The time property of the time series collection object is set to the value of the InitialTriggerTime property specified in the file.
The name property of each time series object is set to the value of the Name property of a channel in the file. If this name cannot be used as a time series object name, daqread sets the name to 'Channel' with the HwChannel property of the channel appended.
The value of the Units property of the time series object depends on the value of the DataFormat parameter. If the DataFormat parameter is set to 'double', daqread sets the DataInfo property of each time series object in the collection to the value of the Units property of the corresponding channel in the file. If the DataFormat parameter is set to 'native', daqread sets the Units property to 'native'. See the Data Acquisition Toolbox documentation for more information on these properties.
Each time series object will have tsdata.event objects attached corresponding to the log of events associated with the channel.

If daqread returns data from multiple triggers, the data from each trigger is separated by a NaN in the time series data. This increases the length of data and time vectors in the time series object by the number of triggers.

Documentation