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]

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.
properties

Return the properties of this file as a dictionary

These are the properties associated with the root TDMS object.

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

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.
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]

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.
path

Path to the TDMS object for this group

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)

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.
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.
path

Path to the TDMS object for this channel

name

The name of this channel

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
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[:]
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.

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)

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

Writing TDMS Files

class nptdms.TdmsWriter(file, mode='w')

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')

Initialise a new TDMS writer

Parameters:
  • file – Either the path to the tdms file to open or an already opened file.
  • mode – Either ‘w’ to open a new file or ‘a’ to append to an existing TDMS file.
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.
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.
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.
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.

seconds

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

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