read

(Not recommended) Read channel data from MDF file

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.

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

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

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

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

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

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

[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".

Examples

Read All Data from MDF File

Read all available data from the MDF file.

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

Read Raw Data

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 Data from Specified Channel List

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 Data from Multiple Channels

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

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

Read Range of Data from Specified Index Values

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 Range of Data from Specified Time Values

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 Data in Vector Format

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 Data in Time Series Format

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 Channel List Entry

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 and Metadata

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

mdfObj — MDF file

MDF file object

MDF file, specified as an MDF file object.

Example: mdf("MDFFile.mf4")

chanList — List of channels

table

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

Example: channelList()

Data Types: table

chanGroupIndex — Index of the channel group

numeric value

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

chanName — Name of channel

string | char vector

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

startPosition — First position of channel data

numeric value | duration

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

endPosition — Last position of channel data range

numeric value | 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"

OutputFormat — Format for output data

"Timetable" (default) | "Vector" | "TimeSeries"

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

OutputFormat	Description
"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 — Conversion option for MDF file data

"Numeric" (default) | "All" | "None"

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

IncludeMetadata — Read metadata with data

false (default) | true

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

data — Channel data

timetable (default) | double | time series | cell array

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.

time — Channel data times

double

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

Version History

Introduced in R2016b

R2023b: read Function Not Recommended

The mdf object and its read function are not recommended and might be removed in a future release.

You should update your code to use mdfRead (Vehicle Network Toolbox) and related functions instead. mdfRead directly accesses the MDF file, and returns a cell array of timetables, with a timetable for each channel group.

For more details, see Transition Your mdf Object Code (Vehicle Network Toolbox).