DOCSEARCHbyAlgolia
Submit Docs

WFDB Python Package

repository·main·Indexed 21 days ago

https://github.com/mit-lcp/wfdb-python

A native Python library for reading, writing, and processing physiologic signals and annotations following the Waveform Database (WFDB) open standards. It provides tools for signal storage, analysis, and visualization, including support for PhysioNet databases and cloud storage (S3, GCS, Azure). The package includes utilities for QRS detection (XQRS, GQRS), heart rate calculation, signal resampling, and conversion of non-WFDB formats such as CSV, EDF, Matlab, TFF, and WAV.

Tokens
4.2K
Snippets
18
Records
41
Agent score
73%

What's inside wfdb

  1. Overview of the WFDB Python Package

    main

    The wfdb package provides Python implementations of the Waveform Database (WFDB) standards for storing, sharing, and analyzing physiologic signal and annotation data.

    Key characteristics:

    • Standard-based: Core I/O functionality follows the WFDB specifications.
    • API Parity: It aims to replicate many command-line APIs from the original WFDB Software Package in Python, though exact consistency is not guaranteed.
    • Use Cases: Biomedical research, clinical studies, and education involving physiologic signals.

  2. Introduction to the WFDB Python Package

    main
    The wfdb package is a native Python library designed for reading, writing, and processing Waveform Database (WFDB) signals and annotations. It provides a suite of tools for handling physiological signal data in the WFDB format.

  3. Supported non-WFDB waveform formats

    main

    The wfdb.io.convert subpackage provides tools to interface with several common waveform file formats. While specific function signatures are defined in their respective modules, the subpackage supports conversions for:

    • CSV: Via wfdb.io.convert.csv
    • EDF: Via wfdb.io.convert.edf
    • Matlab: Via wfdb.io.convert.matlab
    • TFF: Via wfdb.io.convert.tff
    • WAV: Via wfdb.io.convert.wav

  4. Understand the WFDB specifications used by wfdb-python

    main

    The wfdb-python package is designed to be compatible with the original WFDB software package specifications. When working with data formats, signal structures, or annotations, you should refer to the official WFDB documentation to ensure compatibility with other WFDB-compliant tools.

    Key specification areas include:

    • Header Specifications: Defines how WFDB header files are structured.
    • Signal Specifications: Defines the format and encoding of WFDB signals.
    • Annotation Specifications: Defines how annotations are stored and represented.

  5. Manage packages and dependencies with uv

    main

    This project uses uv for package and dependency management. Development dependencies are currently managed as optional dependencies. To add a new package to a specific optional group, use the --optional flag.

    uv add <somepackage> --optional <somegroup>

  6. Generate documentation locally with Sphinx

    main

    The project uses Sphinx to generate documentation from the docs/ directory. Documentation is hosted on ReadTheDocs (RTD).

    Note on requirements: There is redundancy between pyproject.toml and docs/requirements.txt. Ensure Sphinx requirements are consistent in both files, as RTD uses docs/requirements.txt.

    To generate HTML documentation on your local machine, navigate to the docs directory and run make html.

    # From the docs directory
make html

  7. Install the wfdb package

    main

    You can install the stable version of the wfdb package directly from PyPI using pip.

    Note: On some less-common systems, you may need to install libsndfile separately. Refer to the soundfile installation notes if you encounter issues.

    pip install wfdb

  8. Install the development version of wfdb

    main

    To install the development version from a local clone of the repository, navigate to the base directory and run pip install ..

    If you are a contributor and need the additional packages required for development, use the [dev] extra:

    pip install ".[dev]"
    pip install .

  9. Create and publish a new distribution

    main

    To release a new version of the package, follow these steps:

    1. Bump the version: Update the version number in wfdb/version.py.
    2. Update Changelog: Add a summary of changes to docs/changes.rst. Update relevant documentation if function arguments or behaviors have changed.
    3. Create a GitHub Release: After merging your PR, go to the GitHub releases page, click "Draft new release", and set the tag to the new version number.
    4. Build and Publish: Use uv to build the distribution and publish it to PyPI.

    Configuring Repository Access

    Before publishing, you must configure your API tokens. While the project uses uv for building/publishing, it uses poetry configuration commands to manage repository tokens:

    # Configure PyPI token
poetry config pypi-token.pypi <my-token>

# Configure TestPyPI (optional for previewing)
poetry config repositories.test-pypi https://test.pypi.org/legacy/
poetry config pypi-token.test-pypi <my-testpypi-token>

    Building and Uploading

    # Build the distribution
uv build

# Publish to TestPyPI (for previewing)
uv publish --publish-url https://test.pypi.org/legacy/

# Publish to PyPI
uv publish
    uv build
uv publish

  11. Read WFDB records and annotations from cloud storage

    main

    You can read WFDB records and annotations directly from cloud storage by passing a cloud URI (e.g., s3://, gs://, az://, or azureml://) as the record_name argument. This functionality is powered by the fsspec library.

    Prerequisites

    Install the appropriate fsspec backend for your provider:

    • Amazon S3: pip install s3fs
    • Google Cloud Storage: pip install gcsfs
    • Azure Blob Storage: pip install adlfs

    Authentication

    Credentials are handled automatically via standard provider mechanisms (e.g., ~/.aws/credentials for S3 or GOOGLE_APPLICATION_CREDENTIALS for GCS).

    Important Note

    Cloud URIs must be passed as the record_name argument. The pn_dir parameter is reserved exclusively for PhysioNet database names (e.g., "mitdb") and cannot be used with cloud URIs.

    import wfdb

# Read a record from Amazon S3
record = wfdb.rdrecord("s3://my-bucket/wfdb-data/100")

# Read from Google Cloud Storage
record = wfdb.rdrecord("gs://my-bucket/wfdb-data/100")

# Read annotations from S3
ann = wfdb.rdann("s3://my-bucket/wfdb-data/100", "atr")

  12. Run tests with pytest

    main

    Tests are executed using pytest. You can run the full suite normally, or use pytest-xdist to distribute tests across multiple CPU cores for faster execution using the -n auto flag.

    # Run all tests
pytest

# Run tests across multiple cores
pytest -n auto