npTDMS

1.10.0 · active · verified Fri Apr 17

npTDMS is a cross-platform, NumPy-based Python module designed for reading TDMS files, a binary data format produced by LabVIEW and LabWindows/CVI from National Instruments. It provides efficient access to measurement data and metadata. The current version is 1.10.0, and the library maintains an active development cycle with frequent releases addressing bug fixes, performance improvements, and new features.

Common errors

```
KeyError: 'My Group Name' (or 'My Channel Name')
```
cause Attempting to access a non-existent group or channel by name. Group and channel names are case-sensitive and must match exactly.

fix Verify the exact group/channel names within your TDMS file. You can iterate through `tdms_file.groups()` and `group.channels()` to list all available names: `for group in tdms_file.groups(): print(group.name); for channel in group.channels(): print(channel.name)`.
```
TypeError: 'TdmsFile' object is not subscriptable
```
cause Trying to access groups or channels using integer indices (e.g., `tdms_file[0]`) instead of their string names.

fix Access groups and channels by their string names, for example, `tdms_file['GroupName']` and `group['ChannelName']`. To iterate, use `tdms_file.groups()` and `group.channels()` methods.
```
numpy.VisibleDeprecationWarning: Creating an ndarray from ragged nested sequences (which is a list-or-tuple of lists-or-tuples-or ndarrays with different lengths or shapes) is deprecated...
```
cause This and similar NumPy deprecation warnings often occur when an older version of npTDMS interacts with a newer version of NumPy, where API behaviors have changed.

fix Upgrade npTDMS to the latest version (`pip install --upgrade nptdms`). Version 1.10.0 specifically addresses compatibility with NumPy 2.0.

Warnings

breaking Support for Python 2.7 and Python 3.6 was dropped in npTDMS v1.6.0. Users on these Python versions must upgrade to Python 3.7 or newer to use v1.6.0+.
Fix: Upgrade your Python environment to version 3.7 or higher.
breaking npTDMS v1.10.0 includes critical fixes for compatibility with NumPy 2.x. Older versions of npTDMS (pre-1.10.0) may encounter errors or deprecation warnings when used with newer NumPy installations.
Fix: Upgrade npTDMS to the latest version: `pip install --upgrade nptdms`. Ensure NumPy is also updated: `pip install --upgrade numpy`.
gotcha Drastic performance improvements for reading TDMS files were introduced in v1.10.0. Users on older versions (especially with large files) might experience significantly slower data loading times.
Fix: Upgrade npTDMS to the latest version (`pip install --upgrade nptdms`) to benefit from enhanced read performance.
gotcha Older versions of npTDMS (pre-1.9.0) had fixes for reading truncated data and incomplete final segments. Using older versions may lead to misinterpretation or loss of data from malformed TDMS files.
Fix: Upgrade npTDMS to the latest version (`pip install --upgrade nptdms`) to ensure robust handling of various TDMS file structures and prevent data integrity issues.

Install

pip install nptdms Install stable version

Imports

TdmsFile
```
from nptdms import TdmsFile
```

Quickstart

This quickstart demonstrates how to open a TDMS file using `TdmsFile` and iterate through its groups and channels to access metadata and data. It includes error handling for `FileNotFoundError` as a common issue. Replace `example.tdms` with the actual path to your TDMS file.

import os
from nptdms import TdmsFile

# Create a dummy .tdms file for demonstration if it doesn't exist
# In a real scenario, you would have an existing TDMS file.
# For this quickstart, we'll simulate opening one.
# Note: nptdms primarily reads existing files; writing requires TdmsWriter.

tdms_file_path = "example.tdms"
# Normally, you'd ensure this file exists. For a runnable example without actual file creation,
# we'll just demonstrate the read pattern.

try:
    # Open the TDMS file
    with TdmsFile(tdms_file_path) as tdms_file:
        print(f"Successfully opened TDMS file: {tdms_file_path}")
        
        # Iterate through all groups and channels
        print("\nAvailable Groups and Channels:")
        for group in tdms_file.groups():
            print(f"  Group: {group.name}")
            for channel in group.channels():
                print(f"    Channel: {channel.name} (Data Type: {channel.dtype})")
                # Access data for a channel
                # data = channel.data # Uncomment to load actual data
                # print(f"      Data sample: {data[:5]}...") # Print first 5 elements
                
        # Access a specific group and channel by name (replace with actual names from your file)
        # try:
        #     my_group = tdms_file['MyGroupName']
        #     my_channel = my_group['MyChannelName']
        #     channel_data = my_channel.data
        #     print(f"\nData from 'MyChannelName': {channel_data[:5]}...")
        # except KeyError:
        #     print("\n'MyGroupName' or 'MyChannelName' not found in the TDMS file.")

except FileNotFoundError:
    print(f"Error: The file '{tdms_file_path}' was not found. Please provide a valid TDMS file.")
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →