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.
- 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.
- 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.
- 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)
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.
- 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)
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', 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’sopen
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 beTrue
to store a.tdms_index
file at the same folder location orFalse
to only write the data.tdms
file. Iffile
is a readable object,index_file
can either be a readable object to write into orFalse
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. Ifdestination
is a pathindex_file
can either beTrue
orFalse
to store a.tdms_index
file at the same folder location or not. Ifdestination
is a readable objectindex_file
can either be a redable object orFalse
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’