{"id":9407,"library":"wfdb","title":"WFDB Python Package","description":"The WFDB Python Package is a native Python library offering tools for reading, writing, processing, and visualizing physiologic signal and annotation data. It adheres to the WFDB format specification and is designed to be user-friendly for researchers and developers working with biomedical waveform data. The current version is 4.3.1, with active development and regular releases addressing compatibility and adding features.","status":"active","version":"4.3.1","language":"en","source_language":"en","source_url":"https://github.com/MIT-LCP/wfdb-python","tags":["biomedical","signal processing","ECG","EEG","physiologic signals","waveform","physionet"],"install":[{"cmd":"pip install wfdb","lang":"bash","label":"Stable release from PyPI"}],"dependencies":[{"reason":"Core numerical operations for signal data.","package":"numpy"},{"reason":"Data structures, especially for `Record.to_dataframe()` functionality.","package":"pandas"},{"reason":"Scientific computing support, including signal processing tools.","package":"scipy"},{"reason":"Signal visualization and plotting.","package":"matplotlib"},{"reason":"For scientific models and analysis, optional for core I/O.","package":"scikit-learn","optional":true},{"reason":"Required on some less common systems for sound file handling.","package":"libsndfile","optional":true}],"imports":[{"symbol":"wfdb","correct":"import wfdb"},{"note":"Reads a WFDB record into a Record object.","symbol":"rdrecord","correct":"record = wfdb.rdrecord('record_name')"},{"note":"Reads WFDB signals and returns a NumPy array and a dictionary of metadata.","symbol":"rdsamp","correct":"signals, fields = wfdb.rdsamp('record_name')"},{"note":"Plots WFDB records and annotations. Requires a Record object.","symbol":"plot_wfdb","correct":"wfdb.plot_wfdb(record=record, title='Record X')"},{"note":"Reads WFDB annotation files into an Annotation object.","symbol":"Annotation","correct":"annotation = wfdb.rdann('record_name', 'atr')"}],"quickstart":{"code":"import wfdb\nimport matplotlib.pyplot as plt\n\n# Download and read a WFDB record from PhysioNet\n# '100' is a record name, 'mitdb' is the PhysioNet database directory\nrecord = wfdb.rdrecord('100', pn_dir='mitdb')\n\n# Plot the signal\nwfdb.plot_wfdb(record=record, title='Record 100 from MIT-BIH Arrhythmia Database', figsize=(10, 4))\nplt.show() # Crucial for displaying plots in non-interactive environments\n\n# Access signal data and metadata\nsignals = record.p_signal # Physical signals as NumPy array\nfs = record.fs # Sampling frequency\nsig_names = record.sig_name # Signal names\n\nprint(f\"Signals shape: {signals.shape}\")\nprint(f\"Sampling frequency: {fs} Hz\")\nprint(f\"Signal names: {sig_names}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always refer to the WFDB Python package's official documentation for API specifics. Do not assume parity with the C-language WFDB library.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Upgrade `wfdb` to version 4.3.1 or higher: `pip install --upgrade wfdb`.","message":"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.","severity":"breaking","affected_versions":"<4.3.1"},{"fix":"Upgrade `wfdb` to version 4.2.0 or higher: `pip install --upgrade wfdb`.","message":"Version 4.2.0 introduced support for NumPy 2.0, addressing changes to type promotion that could lead to overflow errors in earlier versions.","severity":"breaking","affected_versions":"<4.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<4.1.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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`.","error":"ModuleNotFoundError: No module named 'wfdb'"},{"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.","cause":"In non-interactive Python scripts or certain IDEs, Matplotlib plots do not automatically display. `wfdb.plot_wfdb` uses Matplotlib internally.","error":"Plot not showing up (e.g., when calling wfdb.plot_wfdb in a script)"},{"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.","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`).","error":"IOError: Cannot find header file for record: 'record_name' (or similar 'record not found' error)"}]}