Main Content

mdfRead

Read channel data from MDF file

Since R2023a

collapse all in page

Syntax

data = mdfRead(mdfFileName)
data = mdfRead(___,Name=Value)

Description

data = mdfRead(mdfFileName) reads all data for all channels from the specified MDF file, and assigns the output to the cell array data. The output cell array contains a timetable for each channel group of returned data, where the cell array index corresponds to the sequence of returned channel groups.

data = mdfRead(___,Name=Value) allows name-value arguments to filter on specific channels and channel groups, request metadata, and apply other options.

example

Examples

collapse all

Read all available data from the MDF file.

data = mdfRead("VehicleData.mf4");
head(data{1}) % First timetable in returned cell array.
      time      EngineRPM    Brake    Throttle    Gear    ImpellerTorque    OutputTorque    TransmissionRPM    VehicleSpeed
    ________    _________    _____    ________    ____    ______________    ____________    _______________    ____________

    0 sec          1000        0           60      1          52.919           282.65                0                 0   
    0.04 sec     1383.3        0       59.946      1           101.4           532.63           13.593           0.30047   
    0.08 sec     1685.4        0       59.893      1          150.76           776.41           35.847            0.7924   
    0.12 sec     1907.2        0       59.839      1          193.42           973.15           65.768            1.4538   
    0.16 sec       2062        0       59.785      1          227.02           1117.6           101.53            2.2443   
    0.2 sec      2161.2        0       59.732      1          251.11           1212.8           141.45            3.1268   
    0.24 sec     2221.4        0       59.678      1          267.24           1264.3           183.86            4.0644   
    0.28 sec     2257.2        0       59.624      1          276.35           1271.2           227.25            5.0234

Read raw data without applying any conversion rules.

dataraw = mdfRead("VehicleData.mf4",ReadRaw=true);

Read all available data from the MDF file for specified channel names.

data = mdfRead("VehicleData.mf4",Channel=["*Torque" "*Rate"]);

Read a range of data from the MDF file using indexing to specify the start and end.

data = mdfRead("VehicleData.mf4",IndexRange=[65,128]);

Read a range of data from the MDF file over a specified span of time.

data = mdfRead("VehicleData.mf4",TimeRange=seconds([0,30]));

Read data from channels identified by the mdfChannelInfo function.

Get a table of channels and display their names and group numbers.

chanInfoTable = mdfChannelInfo("VehicleData.mf4",Channel=["*Torque","*Speed"]);
chanInfoTable(:,1:3) % Partial display.
ans = 
  3×3 table

          Name          GroupNumber    GroupNumSamples
    ________________    ___________    _______________

    "ImpellerTorque"         1               751
    "OutputTorque"           1               751
    "VehicleSpeed"           1               751

Read data from specified channels.

data = mdfRead("VehicleData.mf4",Channel=chanInfoTable);
head(data{1}) % View top of data timetable.
      time      ImpellerTorque    OutputTorque    VehicleSpeed
    ________    ______________    ____________    ____________

    0 sec           52.919           282.65               0
    0.04 sec         101.4           532.63         0.30047
    0.08 sec        150.76           776.41          0.7924
    0.12 sec        193.42           973.15          1.4538   
    0.16 sec        227.02           1117.6          2.2443
    0.2 sec         251.11           1212.8          3.1268
    0.24 sec        267.24           1264.3          4.0644
    0.28 sec        276.35           1271.2          5.0234

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

Read all data from an MDF file with its metadata, then view the metadata of the first channel group.

dataGrp1 = mdfRead("VehicleData.mf4",IncludeMetadata=true);
dataGrp1{1}.Properties.CustomProperties
ans = 

CustomProperties with properties:

           ChannelGroupAcquisitionName: ""
                   ChannelGroupComment: "Simulation of an automatic transmission controller during passing maneuver."
                ChannelGroupSourceName: ""
                ChannelGroupSourcePath: ""
             ChannelGroupSourceComment: ""
                ChannelGroupSourceType: Unspecified
             ChannelGroupSourceBusType: Unspecified
    ChannelGroupSourceBusChannelNumber: 0
                    ChannelDisplayName: [""    ""    ""    ""    ""    ""    ""    ""]
                        ChannelComment: [""    ""    ""    ""    ""    ""    ""    ""]
                           ChannelUnit: ["rpm"    "ft*lbf"    "%"    ""    "ft*lbf"    "ft*lbf"    "rpm"    "mph"]
                           ChannelType: [FixedLength    FixedLength    FixedLength    FixedLength    FixedLength    FixedLength    …    ]
                       ChannelDataType: [RealLittleEndian    IntegerUnsignedLittleEndian    RealLittleEndian    …    ]
                        ChannelNumBits: [64 8 64 8 64 64 64 64]
                  ChannelComponentType: [None    None    None    None    None    None    None    None]
                ChannelCompositionType: [None    None    None    None    None    None    None    None]
                     ChannelSourceName: [""    ""    ""    ""    ""    ""    ""    ""]
                     ChannelSourcePath: [""    ""    ""    ""    ""    ""    ""    ""]
                  ChannelSourceComment: [""    ""    ""    ""    ""    ""    ""    ""]
                     ChannelSourceType: [Unspecified    Unspecified    Unspecified    Unspecified    Unspecified    Unspecified    …    ]
                  ChannelSourceBusType: [Unspecified    Unspecified    Unspecified    Unspecified    Unspecified    Unspecified    …    ]
         ChannelSourceBusChannelNumber: [0 0 0 0 0 0 0 0]
                     ChannelReadOption: [All    All    All    All    All    All    All    All]

Input Arguments

collapse all

MDF file name, specified as a string or character vector, including the necessary full or relative path. You can use a URL to specify a file on a remote server.

Depending on the location you are accessing, mdfFileName can take one of these forms.

Location

Form

Current folder or MATLAB® path

To access a file in the current folder or MATLAB path, specify the name of the file in filename, including the file extension.

Example: "myMdfFile.mf4"

Other folders

To access a file in a folder other than the current folder, specify the full or relative path name in filename.

Example: "C:\myFolder\myMdfFile.mf4"

Example: "\dataDir\myMdfFile.mf4"

Remote locations

To access a file in a remote location, filename must contain the full path of the file specified as a uniform resource locator (URL) of the form:

scheme://path_to_file/myMdfFile.mf4

Based on the remote location, scheme can be one of the values in this table.

Remote Locationscheme
Amazon S3™s3
Windows Azure® Blob Storagewasb, wasbs
HDFS™hdfs

For more information, see Work with Remote Data.

Example: "s3://bucketname/path_to_file/myMdfFile.mf4"

Data Types: string | char

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: GroupNumber=2

Channel group number, specified as a numeric scalar for one group, or numeric vector for multiple groups. The function returns data from channels found only in these specified channel groups. If unspecified, data for all channel groups are returned.

Example: GroupNumber=[1,2]

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

Channel names to return data from, specified as a string or array of strings, or as a character vector or cell array of character vectors. Use an array to match on any of multiple channel names. Wildcards allow partial matching. If unspecified, data for all channels are returned.

You can also specify channels using a table generated by the mdfChannelInfo function. When using a table to specify channels, the GroupNumber option is ignored.

Example: Channel=["*Rate","*Speed"]

Data Types: string | char | cell | table

Return absolute timestamps, specified as true or false. If specified true, the returned timetable has absolute timestamps in datetime. If specified false, the returned timetable has relative timestamps in duration, elapsed from the initial timestamp of the file. The default value is false, to return relative timestamps.

Example: AbsoluteTime=true

Data Types: logical

Start time and end time of an interval to read data from, specified as a 2-element vector. If AbsoluteTime=true, specify TimeRange as a datetime vector. If AbsoluteTime=false (default), specify TimeRange as a duration vector. If unspecified, all data samples are read. You cannot combine this option with IndexRange.

Example: TimeRange=seconds([0,60])

Data Types: datetime | duration

Start index and end index of the interval to read data from, specified as a 2-element vector. The indices are inclusive. If unspecified, all data samples are read. You cannot combine this option with TimeRange.

Example: IndexRange=[65:128]

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

Read raw data values, specified as true or false. If specified true, data are read as raw values. If specified false, data are read as physical values. The default value is false.

Example: ReadRaw=true

Data Types: logical

Include channel group metadata and channel metadata in the results, specified as true or false. If true, metadata are added as custom properties to each returned timetable. Metadata are included only for output timetables that are not empty. If false, metadata are not included. The default value is false.

Because mdfRead returns a timetable for each channel group, metadata for this channel group and all channels in this group are added to the timetable as custom properties. You can access the timetable tt custom properties at tt.Properties.CustomProperties.

The mdfRead function takes longer to execute when metadata are included.

Example: IncludeMetadata=true

Data Types: logical

Attach event table to each channel group output timetable, specified as true or false. When true (default) the function attaches an eventtable to each timetable output, accessible in the returned timetable's properties at tt.Properties.Events.

For more information, see the example Work with MDF Events.

Example: IncludeEvents=false

Data Types: logical

Instruction for reading validity data from MDF file, specified as one of the following string values:

  • "include" (default) — Read validity data and store it in the returned timetable's custom property at tt.Properties.CustomProperties.Validity.

  • "ignore" — Do not read validity data.

  • "replace" — Read validity data and replace all invalid samples with the MATLAB missing value. All integer channels containing invalid samples are converted to double.

For more information, see the example Read Validity Data from MDF Files.

Example: ValidityRule="replace"

Data Types: char | string

Output Arguments

collapse all

Channel data, returned as a cell array of timetables, with a timetable for each group.

Limitations

  • mdfRead does not support array channels with more than 3 dimensions.

  • Reading from a nested composition of channels is not supported. You can read from simple structure channels or array channels, but not from a structure or array of composed signals.

  • mdfRead does not support reading from channels with partial conversion rules.

Version History

Introduced in R2023a

expand all

See Also

Functions

Topics