Main Content

read

(Not recommended) Read channel data from MDF file

collapse all in page

The read function is not recommended and might be removed in a future release. Use mdfRead (Vehicle Network Toolbox) instead. See Version History.

Syntax

data = read(mdfObj)
data = read(mdfObj,chanList)
data = read(mdfObj,chanGroupIndex)
data = read(mdfObj,chanGroupIndex,chanName)
data = read(mdfObj,chanGroupIndex,chanName,startPosition)
data = read(mdfObj,chanGroupIndex,chanName,startPosition,endPosition)
data = read(___,Name=Value)
[data,time] = read(___,OutputFormat="Vector")

Description

data = read(mdfObj) reads all data for all channels from the MDF file identified by the MDF file object mdfObj, and assigns the output to data. If the file data is one channel group, the output is a timetable; multiple channel groups are returned as a cell array of timetables, where the cell array index corresponds to the channel group number.

example

data = read(mdfObj,chanList) reads data for all channels specified in the channel list table chanList.

example

data = read(mdfObj,chanGroupIndex) reads data for all channels in the specified channel group.

example

data = read(mdfObj,chanGroupIndex,chanName) reads data for the specified channels.

example

data = read(mdfObj,chanGroupIndex,chanName,startPosition) reads data from the position specified by startPosition.

example

data = read(mdfObj,chanGroupIndex,chanName,startPosition,endPosition) reads data for the range specified from startPosition to endPosition.

example

data = read(___,Name=Value) specifies certain function behaviors using optional name-value pairs.

example

[data,time] = read(___,OutputFormat="Vector") returns two vectors: one vector of channel data and a corresponding vector of timestamps. This form of syntax with two output arguments is supported only when OutputFormat="Vector".

example

Examples

collapse all

Read all available data from the MDF file.

mdfObj = mdf("MDFFile.mf4");
data = read(mdfObj);

Read raw data from a specified channel in the first channel group, without applying any conversion rules.

mdfObj = mdf("MDFFile.mf4");
data = read(mdfObj,1,"Unsigned_UInt32_LE_Primary_Offset_0",Conversion="None");
data(1:4,:)
ans =

  4×1 timetable

    Time     Unsigned_UInt32_LE_Primary_Offset_0
    _____    __________________________________

    0 sec                    0
    1 sec                    1
    2 sec                    2 
    3 sec                    3

Read all available data from the MDF file for channels specified as part of a channel list.

mdfObj = mdf("MDFFile.mf4");
chanList = channelList(mdfObj) % Channel table
data = read(mdfObj,chanList(1:3,:)); % First 3 channels

Read all available data from the MDF file for specified channels.

mdfObj = mdf("MDFFile.mf4");
data = read(mdfObj,1,["Channel1","Channel2"]);

Read a range of data from the MDF file using indexing for startPosition and endPosition to specify the data range.

mdfObj = mdf("MDFFile.mf4");
data = read(mdfObj,1,["Channel1","Channel2"],1,10);

Read a range of data from the MDF file using time values for startPosition and endPosition to specify the data range.

mdfObj = mdf("MDFFile.mf4");
data = read(mdfObj,1,["Channel1","Channel2"],seconds(5.5),seconds(7.3));

Read all available data from the MDF file, returning data and time vectors.

mdfObj = mdf("MDFFile.mf4");
[data,time] = read(mdfObj,1,"Channel1",OutputFormat="Vector");

Read all available data from the MDF file, returning time series data.

mdfObj = mdf("MDFFile.mf4");
data = read(mdfObj,1,"Channel1",OutputFormat="TimeSeries");

Read data from a channel identified by the channelList function.

Get list of channels and display their names and group numbers.

mdfObj = mdf("File05.mf4");
chlist = channelList(mdfObj);
chlist(1:2,1:2) % Partial listing
  2×2 table

                ChannelName                 ChannelGroupNumber
    ____________________________________    __________________

    "Float_32_LE_Offset_64"                         2         
    "Float_64_LE_Primary_Offset_0"                  2

Read data from the first channel in the list.

data = read(mdfObj,chlist{1,2},chlist{1,1});
data(1:5,:)
  5×1 timetable

      Time      Float_32_LE_Offset_64
    ________    _____________________

    0 sec                  5         
    0.01 sec             5.1         
    0.02 sec             5.2         
    0.03 sec             5.3         
    0.04 sec             5.4

Read data from an MDF file into a timetable, along with channel group and channel metadata.

Read from channel group 1 into a timetable.

mdfObj = mdf("File05.mf4");
TTout = read(mdfObj,1,IncludeMetadata=true);
TTout.Properties.CustomProperties
ans = 

CustomProperties with properties:

    ChannelGroupAcquisitionName: ""
            ChannelGroupComment: "Integer Types"
         ChannelGroupSourceInfo: [1×1 struct]
             ChannelDisplayName: [""    ""]
                 ChannelComment: [""    ""]
                    ChannelUnit: [""    ""]
                    ChannelType: [FixedLength    FixedLength]
                ChannelDataType: [IntegerSignedLittleEndian    IntegerUnsignedLittleEndian]
                 ChannelNumBits: [16 32]
           ChannelComponentType: [None    None]
         ChannelCompositionType: [None    None]
              ChannelSourceInfo: [1×2 struct]
              ChannelReadOption: [Numeric    Numeric]

Input Arguments

collapse all

MDF file, specified as an MDF file object.

Example: mdf("MDFFile.mf4")

List of channels, specified as a table in the format returned by the channelList (Vehicle Network Toolbox) function.

Example: channelList()

Data Types: table

Index of channel group, specified as a numeric value that identifies the channel group from which to read.

Example: 1

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Name of channel, specified as a string, character vector, or array. chanName identifies the name of a channel in the channel group. Use a cell array of character vectors or array of strings to identify multiple channels.

Example: "Channel1"

Data Types: char | string | cell

First position of channel data, specified as a numeric value or duration. The startPosition option specifies the first position from which to read channel data. Provide a numeric value to specify an index position; use a duration to specify a time position. If only startPosition is provided without the endPosition option, the data value at that location is returned. When used with endPosition to specify a range, the function returns data from the startPosition (inclusive) to the endPosition (noninclusive).

Example: 1

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | duration

Last position of channel data range, specified as a numeric value or duration. The endPosition option specifies the last position for reading a range of channel data. Provide both the startPosition and endPosition to specify retrieval of a range of data. The function returns up to but not including endPosition when reading a range. Provide a numeric value to specify an index position; use a duration to specify a time position.

Example: 1000

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | duration

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: Conversion="Numeric"

Format for output data, specified as a string or character vector. This option formats the output according to the following table.

OutputFormatDescription
"Timetable"

Return a timetable from one or more channels into one output variable. This is the only format allowed when reading from multiple channels at the same time. (Default.)

Note: The timetable format includes variables for the MDF channels. Because the variable titles must be valid MATLAB® identifiers, they might not be exactly the same as those values in the MDF object ChannelNames property. The variable headers are derived from the property using the function matlab.lang.makeValidName. The original channel names are available in the VariableDescriptions property of the timetable object.

"Vector"Return a vector of numeric data values, and optionally a vector of time values from one channel. Use one output variable to return only data, or two output variables to return vectors for both data and time stamps.
"TimeSeries"Return a time series of data from one channel.

Example: "Vector"

Data Types: char | string

Conversion option for MDF file data, specified as "Numeric", "All", or "None". The default uses the value specified in the Conversion property of the mdf object. This option overrides that setting.

  • "Numeric" — Apply only numeric conversion rules (CC_Type 1-6). Data with non-numeric conversion rules are imported as raw, unconverted values.

  • "None" — Do not apply any conversion rules. All data are imported as raw data.

  • "All" — Apply all numeric and text conversion rules (CC_Type 1-10).

Example: Conversion="All"

Data Types: char | string

Read channel group and channel metadata from the MDF file along with its data. The default value is false. Metadata can only be included when the OutputFormat is specified as "Timetable". The timetable cannot be empty. You can access the metadata in data.Properties.CustomProperties.

Specifying IncludeMetadata=true might impact function performance when reading data from a channel group with many channels.

Example: IncludeMetadata=true

Data Types: logical

Output Arguments

collapse all

Channel data, returned as a timetable, cell array of timetables, vector of doubles, or a time series according to the OutputFormat option value and the number of channel groups.

Channel data times, returned as a vector of double elements. The time vector is returned only when OutputFormat="Vector".

Version History

Introduced in R2016b

expand all

See Also

Functions

Topics