npTDMS API Reference

Reading TDMS Files

class nptdms.TdmsFile

Reads and stores data from a TDMS file.

There are two main ways to create a new TdmsFile object. TdmsFile.read will read all data into memory:

tdms_file = TdmsFile.read(tdms_file_path)

or you can use TdmsFile.open to read file metadata but not immediately read all data, for cases where a file is too large to easily fit in memory or you don’t need to read data for all channels:

with TdmsFile.open(tdms_file_path) as tdms_file:
    # Use tdms_file
    ...

This class acts like a dictionary, where the keys are names of groups in the TDMS files and the values are TdmsGroup objects. A TdmsFile can be indexed by group name to access a group within the TDMS file, for example:

tdms_file = TdmsFile.read(tdms_file_path)
group = tdms_file[group_name]

And you can check for the presence of a group with the in keyword:

contains_group = group_name in tdms_file

Iterating over a TdmsFile produces the names of groups in this file, or you can use the groups method to directly access all groups:

for group in tdms_file.groups():
    # Use group
    ...
static read(file, raw_timestamps=False, memmap_dir=None)

Creates a new TdmsFile object and reads all data in the file

Parameters:

  • file – Either the path to the tdms file to read as a string or pathlib.Path, or an already opened file.

  • raw_timestamps – By default TDMS timestamps are read as numpy datetime64 but this loses some precision. Setting this to true will read timestamps as a custom TdmsTimestamp type.

  • memmap_dir – The directory to store memory mapped data files in, or None to read data into memory. The data files are created as temporary files and are deleted when the channel data is no longer used. tempfile.gettempdir() can be used to get the default temporary file directory.

static open(file, raw_timestamps=False, memmap_dir=None)
Creates a new TdmsFile object and reads metadata, leaving the file open

to allow reading channel data

Parameters:

  • file – Either the path to the tdms file to read as a string or pathlib.Path, or an already opened file.

  • raw_timestamps – By default TDMS timestamps are read as numpy datetime64 but this loses some precision. Setting this to true will read timestamps as a custom TdmsTimestamp type.

  • memmap_dir – The directory to store memory mapped data files in, or None to read data into memory. The data files are created as temporary files and are deleted when the channel data is no longer used. tempfile.gettempdir() can be used to get the default temporary file directory.

static read_metadata(file, raw_timestamps=False)

Creates a new TdmsFile object and only reads the metadata

Parameters:

  • file – Either the path to the tdms file to read as a string or pathlib.Path, or an already opened file.

  • raw_timestamps – By default TDMS timestamps are read as numpy datetime64 but this loses some precision. Setting this to true will read timestamps as a custom TdmsTimestamp type.

groups()

Returns a list of the groups in this file

Return type:

List of TdmsGroup.

property tdms_version

The TDMS format version of this file

property properties

Return the properties of this file as a dictionary

These are the properties associated with the root TDMS object.

property file_status

Return information about the file status

Return type:

FileStatus

as_dataframe(time_index=False, absolute_time=False, scaled_data=True, arrow_dtypes=False)

Converts the TDMS file to a DataFrame. DataFrame columns are named using the TDMS object paths.

Parameters:

  • time_index – Whether to include a time index for the dataframe.

  • absolute_time – If time_index is true, whether the time index values are absolute times or relative to the start time.

  • scaled_data – By default the scaled data will be used. Set to False to use raw unscaled data. For DAQmx data, there will be one column per DAQmx raw scaler and column names will include the scale id.

  • arrow_dtypes – Use PyArrow data types in the DataFrame.

Returns:

The full TDMS file data.

Return type:

pandas.DataFrame

as_hdf(filepath, mode='w', group='/')

Converts the TDMS file into an HDF5 file

Parameters:

  • filepath – The path of the HDF5 file you want to write to.

  • mode – The write mode of the HDF5 file. This can be ‘w’ or ‘a’

  • group – A group in the HDF5 file that will contain the TDMS data.

data_chunks()

A generator that streams chunks of data from disk. This method may only be used when the TDMS file was opened without reading all data immediately.

Return type:

Generator that yields DataChunk objects

close()

Close the underlying file if it was opened by this TdmsFile

If this TdmsFile was initialised with an already open file then the reference to it is released but the file is not closed.

class nptdms.TdmsGroup

Represents a group of channels in a TDMS file.

This class acts like a dictionary, where the keys are names of channels in the group and the values are TdmsChannel objects. A TdmsGroup can be indexed by channel name to access a channel in this group, for example:

channel = group[channel_name]

And you can check for the presence of a channel with the in keyword:

contains_channel = channel_name in group

Iterating over a TdmsGroup produces the names of channels in this group, or you can use the channels method to directly access all channels:

for channel in group.channels():
    # Use channel
    ...
Variables:

~.properties – Dictionary of TDMS properties defined for this group.

property path

Path to the TDMS object for this group

property name

The name of this group

channels()

The list of channels in this group

Return type:

A list of TdmsChannel

as_dataframe(time_index=False, absolute_time=False, scaled_data=True, arrow_dtypes=False)

Converts the TDMS group to a DataFrame. DataFrame columns are named using the channel names.

Parameters:

  • time_index – Whether to include a time index for the dataframe.

  • absolute_time – If time_index is true, whether the time index values are absolute times or relative to the start time.

  • scaled_data – By default the scaled data will be used. Set to False to use raw unscaled data. For DAQmx data, there will be one column per DAQmx raw scaler and column names will include the scale id.

  • arrow_dtypes – Use PyArrow data types in the DataFrame.

Returns:

The TDMS object data.

Return type:

pandas.DataFrame

class nptdms.TdmsChannel

Represents a data channel in a TDMS file.

This class acts like an array, you can get the length of a channel using len(channel), and can iterate over values in the channel using a for loop, or index into a channel using an integer index to get a single value:

for value in channel:
    # Use value
    ...
first_value = channel[0]

Or you can index using a slice to retrieve a range of data as a numpy array. To get all data in this channel as a numpy array:

all_data = channel[:]

Or to retrieve a subset of data:

data_subset = channel[start:stop]
Variables:

~.properties – Dictionary of TDMS properties defined for this channel, for example the start time and time increment for waveforms.

property path

Path to the TDMS object for this channel

property name

The name of this channel

property group_name

The name of the group that contains this channel

property dtype

NumPy data type of the channel data

For data with a scaling this is the data type of the scaled data

Return type:

numpy.dtype

property data

If the TdmsFile was created by reading all data, this property provides direct access to the numpy array containing the data for this channel.

Indexing into the channel with a slice should be preferred to using this property, for example:

channel_data = channel[:]
property raw_data

If the TdmsFile was created by reading all data, this property provides direct access to the numpy array of raw, unscaled data. For unscaled objects this is the same as the data property.

property raw_scaler_data

If the TdmsFile was created by reading all data, this property provides direct access to the numpy array of raw DAQmx scaler data as a dictionary mapping from scale id to raw data arrays.

data_chunks()

A generator that streams chunks data for this channel from disk. This method may only be used when the TDMS file was opened without reading all data immediately.

Return type:

Generator that yields ChannelDataChunk objects

read_data(offset=0, length=None, scaled=True)

Reads data for this channel from the TDMS file and returns it as a numpy array

Indexing into the channel with a slice should be preferred over using this method, but this method is needed if you want to read raw, unscaled data.

Parameters:

  • offset – Initial position to read data from.

  • length – Number of values to attempt to read. Fewer values will be returned if attempting to read beyond the end of the available data.

  • scaled – By default scaling will be applied to the returned data. Set this parameter to False to return raw unscaled data. For DAQmx data a dictionary of scaler id to raw scaler data will be returned.

time_track(absolute_time=False, accuracy='ns')

Return an array of time or the independent variable for this channel

This depends on the object having the wf_increment and wf_start_offset properties defined. Note that wf_start_offset is usually zero for time-series data. If you have time-series data channels with different start times, you should use the absolute time or calculate the time offsets using the wf_start_time property.

For larger timespans, the accuracy setting should be set lower. The default setting is ‘ns’, which has a timespan of [1678 AD, 2262 AD]. For the exact ranges, refer to http://docs.scipy.org/doc/numpy/reference/arrays.datetime.html section “Datetime Units”.

Parameters:

  • absolute_time – Whether the returned time values are absolute times rather than relative to the start time. If true, the wf_start_time property must be set.

  • accuracy – The accuracy of the returned datetime64 array.

Return type:

NumPy array.

Raises:

KeyError if required properties aren’t found

as_dataframe(time_index=False, absolute_time=False, scaled_data=True, arrow_dtypes=False)

Converts the TDMS channel to a DataFrame. The DataFrame column is named using the channel path.

Parameters:

  • time_index – Whether to include a time index for the dataframe.

  • absolute_time – If time_index is true, whether the time index values are absolute times or relative to the start time.

  • scaled_data – By default the scaled data will be used. Set to False to use raw unscaled data. For DAQmx data, there will be one column per DAQmx raw scaler and column names will include the scale id.

  • arrow_dtypes – Use PyArrow data types in the DataFrame.

Returns:

The TDMS object data.

Return type:

pandas.DataFrame

class nptdms.DataChunk

A chunk of data in a TDMS file

Can be indexed by group name to get the data for a group in this channel, which can then be indexed by channel name to get the data for a channel in this chunk. For example:

group_chunk = data_chunk[group_name]
channel_chunk = group_chunk[channel_name]
groups()

Returns chunks of data for all groups

Return type:

List of GroupDataChunk

class nptdms.GroupDataChunk

A chunk of data for a group in a TDMS file

Can be indexed by channel name to get the data for a channel in this chunk. For example:

channel_chunk = group_chunk[channel_name]
Variables:

~.name – Name of the group

channels()

Returns chunks of channel data for all channels in this group

Return type:

List of ChannelDataChunk

class nptdms.ChannelDataChunk

A chunk of data for a channel in a TDMS file

Is an array-like object that supports indexing to access data, for example:

chunk_length = len(channel_data_chunk)
chunk_data = channel_data_chunk[:]
Variables:

  • ~.name – Name of the channel

  • ~.offset – Starting index of this chunk of data in the entire channel

class nptdms.tdms.FileStatus

Contains status information about a read TDMS file

incomplete_final_segment

Boolean indicating whether the last data segment was not written completely, meaning it may contain less data than expected

channel_statuses

Dictionary mapping from channel paths to ChannelSegmentStatus objects when the last segment is incomplete or had an unexpected length

class nptdms.tdms.ChannelSegmentStatus
expected_length

Number of values expected in the segment

read_length

Number of values read from the segment

Writing TDMS Files

class nptdms.TdmsWriter(file, mode='w', version=4712, index_file=False)

Writes to a TDMS file.

A TdmsWriter should be used as a context manager, for example:

with TdmsWriter(path) as tdms_writer:
    tdms_writer.write_segment(segment_data)
__init__(file, mode='w', version=4712, index_file=False)

Initialise a new TDMS writer

Parameters:

  • file – Either the path to the tdms file, an already opened file or a bytes stream.

  • mode – The mode to open the file with, used when file is a file path. This will be passed through to Python’s open function with ‘b’ appended to ensure the file is opened in binary mode. For example, use ‘w’ (the default) to open a new file or ‘a’ to append to an existing TDMS file.

  • version – The TDMS format version to write, which must be either 4712 (the default) or 4713. It’s important that if you are appending segments to an existing TDMS file, this matches the existing file version (this can be queried with the tdms_version property).

  • index_file – Whether to write an index file besides the data file. Index files can be used to accelerate reading speeds for faster channel extraction and data positions inside the data files. If file```variable is a path, ``index_file can be True to store a .tdms_index file at the same folder location or False to only write the data .tdms file. If file is a readable object, index_file can either be a readable object to write into or False to omit.

classmethod defragment(source, destination, version=4712, index_file=False)

Defragemnts an existing TdmsFile by loading and moving each Object to a separate channel to stream read one consecutive part of the file for faster access.

Parameters:

  • source – Either the path to the tdms file to read as a string or pathlib.Path, or an already opened file.

  • destination – Either the path to the tdms file

  • version – The TDMS format version to write, which must be either 4712 (the default) or 4713. It’s important that if you are appending segments to an existing TDMS file, this matches the existing file version (this can be queried with the tdms_version property).

  • index_file – Depends on the destination input. If destination is a path index_file can either be True or False to store a .tdms_index file at the same folder location or not. If destination is a readable object index_file can either be a redable object or False to store a .tdms_index file inside of the submitted object or not.

write_segment(objects)

Write a segment of data to a TDMS file

Parameters:

objects – A list of TdmsObject instances to write

class nptdms.RootObject(properties=None)

The root TDMS object containing properties for the TDMS file

__init__(properties=None)

Initialise a new GroupObject

Parameters:

properties – A dictionary mapping property names to their value.

property path

The string representation of the root path

class nptdms.GroupObject(group, properties=None)

A TDMS object for a group

__init__(group, properties=None)

Initialise a new GroupObject

Parameters:

  • group – The name of this group.

  • properties – A dictionary mapping property names to their value.

property path

The string representation of this group’s path

class nptdms.ChannelObject(group, channel, data, properties=None)

A TDMS object for a channel with data

__init__(group, channel, data, properties=None)

Initialise a new ChannelObject

Parameters:

  • group – The name of the group this channel is in.

  • channel – The name of this channel.

  • data – 1-D Numpy array of data to be written.

  • properties – A dictionary mapping property names to their value.

property path

The string representation of this channel’s path

Data Types for Property Values

class nptdms.types.Int8(value)
class nptdms.types.Int16(value)
class nptdms.types.Int32(value)
class nptdms.types.Int64(value)
class nptdms.types.Uint8(value)
class nptdms.types.Uint16(value)
class nptdms.types.Uint32(value)
class nptdms.types.Uint64(value)
class nptdms.types.SingleFloat(value)
class nptdms.types.DoubleFloat(value)
class nptdms.types.String(value)
class nptdms.types.Boolean(value)
class nptdms.types.TimeStamp(value)

Timestamps

class nptdms.timestamp.TdmsTimestamp(seconds, second_fractions)

A Timestamp from a TDMS file

The TDMS format stores timestamps as a signed number of seconds since the epoch 1904-01-01 00:00:00 UTC and number of positive fractions (2^-64) of a second.

Variables:

  • ~.seconds – Seconds since the epoch as a signed integer

  • ~.second_fractions – A positive number of 2^-64 fractions of a second

as_datetime64(resolution='us')

Convert this timestamp to a numpy datetime64 object

Parameters:

resolution – The resolution of the datetime64 object to create as a numpy unit code. Must be one of ‘s’, ‘ms’, ‘us’, ‘ns’ or ‘ps’

as_datetime()

Convert this timestamp to a Python datetime.datetime object

class nptdms.timestamp.TimestampArray

A numpy array of TDMS timestamps

Indexing into a TimestampArray returns TdmsTimestamp objects.

property seconds

The number of seconds since the TDMS epoch (1904-01-01 00:00:00 UTC) as a numpy array

property second_fractions

The number of 2**-64 fractions of a second as a numpy array

as_datetime64(resolution='us')

Convert to an array of numpy datetime64 objects

Parameters:

resolution – The resolution of the datetime64 objects to create as a numpy unit code. Must be one of ‘s’, ‘ms’, ‘us’, ‘ns’ or ‘ps’

Indices and Tables