WFDB Python Package

Common errors

• ModuleNotFoundError: No module named 'wfdb'

  cause The 'wfdb' package is not found in the Python environment currently being used by your interpreter, IDE, or Jupyter Notebook. This often happens with multiple Python installations or when using `pip install --user`.
  fix Ensure you are running your code with the Python interpreter where `wfdb` was installed. In Jupyter, check the kernel. If using virtual environments, activate the correct one. Reinstall using `pip install wfdb` in the intended environment.

• Plot not showing up (e.g., when calling wfdb.plot_wfdb in a script)

  cause In non-interactive Python scripts or certain IDEs, Matplotlib plots do not automatically display. `wfdb.plot_wfdb` uses Matplotlib internally.
  fix Add `import matplotlib.pyplot as plt` and `plt.show()` after calling `wfdb.plot_wfdb()` or `wfdb.plot_items()` to explicitly render and display the plot.

• IOError: Cannot find header file for record: 'record_name' (or similar 'record not found' error)

  cause The specified WFDB record files (.hea, .dat, etc.) could not be found. This could be due to an incorrect local path, or if you're trying to access records from PhysioNet without specifying the correct PhysioNet directory (`pn_dir`).
  fix For local files, ensure `record_name` is the correct path to the record files. For PhysioNet data, specify the `pn_dir` argument (e.g., `wfdb.rdrecord('100', pn_dir='mitdb')`) and ensure you have an active internet connection.

Warnings

• breaking The WFDB Python package is developed independently of the original C-language WFDB software. While sharing core specifications, there are significant differences in implementation, and consistency between the two is not guaranteed. Code written for one may not directly translate to the other.
  Fix: Always refer to the WFDB Python package's official documentation for API specifics. Do not assume parity with the C-language WFDB library.
• breaking Version 4.3.1 includes a fix for Pandas 3.0 compatibility, specifically `DataFrame.set_index()` which no longer accepts raw NumPy arrays as keys. Older versions of `wfdb` might encounter errors with Pandas 3.0.
  Fix: Upgrade `wfdb` to version 4.3.1 or higher: `pip install --upgrade wfdb`.
• breaking Version 4.2.0 introduced support for NumPy 2.0, addressing changes to type promotion that could lead to overflow errors in earlier versions.
  Fix: Upgrade `wfdb` to version 4.2.0 or higher: `pip install --upgrade wfdb`.
• gotcha The `wfdb.wrsamp()` function (and `Record.wrsamp()` method) changed its rounding behavior in version 4.1.0. Floating-point input values are now rounded to the nearest sample value, rather than truncated towards zero.
  Fix: Be aware of the changed rounding behavior when writing signal data. If precise backward compatibility is needed for written files, ensure your environment uses `wfdb` version 4.1.0 or newer and re-evaluate expected output.

Install

• pip install wfdb Stable release from PyPI

Imports

• wfdb

  import wfdb

• rdrecord

  record = wfdb.rdrecord('record_name')

  Reads a WFDB record into a Record object.
• rdsamp

  signals, fields = wfdb.rdsamp('record_name')

  Reads WFDB signals and returns a NumPy array and a dictionary of metadata.
• plot_wfdb

  wfdb.plot_wfdb(record=record, title='Record X')

  Plots WFDB records and annotations. Requires a Record object.
• Annotation

  annotation = wfdb.rdann('record_name', 'atr')

  Reads WFDB annotation files into an Annotation object.

Quickstart

This quickstart example demonstrates how to import the `wfdb` library, download and read a record from the PhysioNet 'mitdb' database, plot the physiological signals, and access key metadata like signal data, sampling frequency, and signal names. The `plt.show()` call is important for displaying plots in many environments.

import wfdb
import matplotlib.pyplot as plt

# Download and read a WFDB record from PhysioNet
# '100' is a record name, 'mitdb' is the PhysioNet database directory
record = wfdb.rdrecord('100', pn_dir='mitdb')

# Plot the signal
wfdb.plot_wfdb(record=record, title='Record 100 from MIT-BIH Arrhythmia Database', figsize=(10, 4))
plt.show() # Crucial for displaying plots in non-interactive environments

# Access signal data and metadata
signals = record.p_signal # Physical signals as NumPy array
fs = record.fs # Sampling frequency
sig_names = record.sig_name # Signal names

print(f"Signals shape: {signals.shape}")
print(f"Sampling frequency: {fs} Hz")
print(f"Signal names: {sig_names}")