tdmsDatastore

Datastore for collection of TDMS files

Since R2022a

Description

Use the TDMSDatastore object to access data from a collection of TDMS files.

Creation

Syntax

tdmsds = tdmsDatastore(location)

tdmsds = tdmsDatastore(__,Name=Value)

Description

tdmsds = tdmsDatastore(location) creates a TDMSDatastore object based on a TDMS file or a collection of files in the folder specified by location. Within the folder, all files with the extension .tdms are included in the datastore.

tdmsds = tdmsDatastore(__,Name=Value) specifies function options and properties of tdmsds using optional name-value pairs.

Input Arguments

location — Location of TDMS datastore files

string | character vector | cell array

Location of TDMS datastore files, specified as a string, character vector, or cell array identifying either files or folders. The path can be relative or absolute, and can contain the wildcard characters ? and *. If location specifies a folder, the datastore includes all files in that folder with the extension .tdms.

Example: "C:\data\tdms_set1"

Data Types: char | string | cell

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.

You can specify file information or object Properties. Allowed options are IncludeSubfolders, AlternateFileSystemRoots, and the properties SelectedChannelGroup, SelectedChannels, RowTimes, and ReadSize.

Example: SelectedChannelGroup="Acceleration"

IncludeSubfolders — Include files in subfolders

false (default) | true

Include files in subfolders, specified as a logical. Specify true to include files in each folder and recursively in subfolders.

Example: IncludeSubfolders=true

Data Types: logical

AlternateFileSystemRoots — Root paths for different platforms

string array | cell array

Root paths to the TDMS files for different platforms, specified as an array of strings.

Example: AlternateFileSystemRoots=["Z:\datasets", "/tdms/datasets"]

Data Types: char | string | cell

Properties

Files — Files included in datastore

Read-only: char | string | cell

This property is read-only.

Files included in the datastore, specified as a character vector or string identifying a relative or absolute path to a file or folder. The wildcard characters ? and * are supported. All TDMS files in the specified folder are included in the datastore. The property value is stored as a string vector of file names.

Example: "file*.tdms"

Data Types: char | string

ChannelList — All channels present in first TDMS file

Read-only: table

This property is read-only.

All channels present in first TDMS file, returned as a table.

Those channels targeted for reading must have the same name and belong to the same channel group in each file of the TDMS datastore.

Data Types: table

SelectedChannelGroup — Channel group containing the channels to read from

string | char

Channel group containing the channels to read from, specified as a string or character vector.

Example: "Torque"

Data Types: string | char

SelectedChannels — Names of channels to read

char | string | cell

Names of channels to read, specified as a character vector, string, or array of either. The channels must be in the channel group specified by SelectedChannelGroup in each file of the TDMS datastore.

Example: ["Torque1" "Torque2"]

Data Types: char | string | cell

RowTimes — Times associated with rows of table

datetime | duration | channel name

Times associated with rows of the table, specified as a selected time channel name, a datetime vector, or a duration vector. Setting this property causes the read and readall functions to output a cell array of timetables. Each time element labels a row in the output timetable.

Example: duration(seconds([1:1000]/1000))

Data Types: datetime | duration | string

ReadSize — Size of data returned by read

20000 (default) | numeric | "file"

Size of data returned by the read function, specified as "file" or a numeric value. A string value of "file" causes a read of one TDMS file at a time; a numeric value specifies the number of records to read. The readall function ignores this property.

If you change the ReadSize property value after creating the TDMSDatastore object, the datastore resets.

Example: 5000

Data Types: double | string | char

Object Functions

read	Read data in TDMS datastore
readall	Read all data in TDMS datastore
preview	Read first 8 records from TDMS datastore
hasdata	Determine if data is available to read from TDMS datastore
reset	Reset TDMS datastore to initial state
combine	Combine data from multiple datastores
transform	Transform datastore

Examples

Read Data from a TDMS Datastore

Create a TDMS datastore from all the TDMS files in the folder C:\data\tdms, and read the data into tables.

Set up the datastore and view its channel list.

td = tdmsDatastore("C:\data\tdms");
td.ChannelList(:,1:4)

ans =

  6×4 table

    ChannelGroupNumber    ChannelGroupName    ChannelGroupDescription      ChannelName  
    __________________    ________________    _______________________    _______________

            1              "Acceleration"        "CGAcceleration"        "Acceleration1"
            1              "Acceleration"        "CGAcceleration"        "Acceleration2"
            2              "Force"               "CGForce"               "Force1"       
            2              "Force"               "CGForce"               "Force2"       
            3              "Torque"              "CGTorque"              "Torque1"      
            3              "Torque"              "CGTorque"              "Torque2"

Read all available data.

data_set = readall(td)

data_set =

  1×3 cell array

    {9936×2 table}    {9936×2 table}    {9936×2 table}

View the data from the first channel group.

data_set{1}

ans =

  9936×2 table

    Acceleration1    Acceleration2
    _____________    _____________

       -1.9851                0   
       -3.9702                0   
        11.911           1.5521   
        5.9553          -1.5521   
        1.9851          -4.6562   
        5.9553           4.6562   
        3.9702          -1.5521   
        3.9702          -4.6562   
        13.896                0   

          :                :      

       -4.8046          -2.2609   
       -4.8046           6.7826   
       -7.2068           2.2609   
       -7.2068           4.5218   
       -7.2068           6.7826   
       -2.4023           9.0435   
       -2.4023           4.5218   
       -9.6091           2.2609   
       -12.011           4.5218   

	Display all 9936 rows.

Read all available data for the channel group Force.

td.SelectedChannelGroup = "Force";
data_set = readall(td)

data_set =

  1×1 cell array

    {9936×2 table}

Read 500 entries of data.

td.ReadSize = 500;
data_set = read(td)

data_set =

  1×1 cell array

    {500×2 table}

Limitations

• TDMS functions are supported on Windows^® platforms only.

• As a special case of a datastore, the TDMSDatastore object does not support the following functionality:

  • Partitioning for parallel computing

  • Shuffling

Version History

Introduced in R2022a