Metadata-Version: 2.4
Name: pqrstann
Version: 0.1.0
Summary: ECG waveform delineation for P, QRS, and T waves with WFDB-compatible annotations
Author-email: Shaun D'Souza <shaundsouza270@gmail.com>, foreverallama <klockatoo@gmail.com>
License: MIT
Project-URL: Repository, https://github.com/foreverallama/pqrstann
Keywords: ECG,biomedical signal processing,physionet,wfdb
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.3.0
Requires-Dist: scipy>=1.16.0
Requires-Dist: wfdb>=4.3.0
Dynamic: license-file

# PQRSTann
[![DOI](https://zenodo.org/badge/1091567354.svg)](https://doi.org/10.5281/zenodo.19217332)

PQRSTann is a Python module for beat-to-beat ECG waveform delineation, providing annotations of complete P, QRS, and T waves, including both peaks and waveform boundaries, in WFDB-compatible formats. The module supports delineation of individual ECG cycles as well as full ECG waveforms.

Peak detection is performed using the Pan-Tompkins algorithm [1], after which PQRST boundaries are identified using algorithms described in [2, 3].

Key features of PQRSTann:

- Customizable parameters for tuning performance for different signal conditions which includes Adult and Fetal ECG signals
- Provides for single beat detection as well with an optional provided param of `DEFAULT_RR_MS`
- Works with signals of any sampling frequency
- Optional utility to save annotations to WFDB or CSV formats
- Allows for use of different R-peak detectors including use of own, instead of Pan-tompkins algorithm

PQRSTann is primarily a Python reimplementation of [ECGPUWAVE](https://physionet.org/content/ecgpuwave/1.3.4/) provided by PhysioNet, with extensions aimed at improved performance and usability.

## Methods

```python
get_pqrst_anns(file_path, channel=0, fs=None, write_annotation_file=False, r_peaks=None, running_rr=None, qrs_detector='pantompkins', params=None)
```

* **`file_path`** *(str)*: Path to the WFDB record (excluding the `.dat` or `.hea` extension).
* **`channel`** *(int, default=0)*: The index of the ECG channel/lead to process.
* **`fs`** *(float, optional)*: Sampling frequency of the signal in Hz.
* **`write_annotation_file`** *(bool, default=False)*: If `True`, writes the output annotations to a WFDB-compatible file alongside the original record.
* **`r_peaks`** *(array-like, optional)*: Pre-computed R-peak sample indices.
* **`running_rr`** *(array-like, optional)*: Array of RR intervals (in milliseconds). Overrides the dynamic interval calculation (which is necessary for single-cycle delineation where historical interval data is absent).
* **`qrs_detector`** *(str, default="pantompkins")*: The algorithm used for initial R-peak detection.
* **`params`** *(dict, optional)*: Dictionary to tune algorithmic performance and override default constraints. This allows users to optimize the detector for different signal conditions.

## Results

PQRSTann was qualitatively validated on adult (MIT-BIH Arrhythmia Database, MIT-BIH Normal Sinus Rhythm Database) and fetal ECG datasets (ADFECGDB scalp recordings, FECGSYN data). Qualitative comparisons with ECGPUWAVE (Physionet) are provided where it could be obtained.

### Adult ECG

![Adult ECG Validation](docs/adult_validation.png)
*(Top row: ECGPUWAVE Reference. Bottom row: PQRSTann)*

### Fetal ECG

![Fetal ECG Validation](docs/fetal_validation.png)

### Dynamic Window Configuration for Fetal ECG signals

Because fetal heart rates and waveform morphologies differ significantly from adult ECGs, PQRSTann supports dynamic windowing to isolate specific wave characteristics. During validation, the P-wave search windows were explicitly tuned for the target physiology via the `params` dictionary:

* **Adult ECG Parameters:**
  * `PWAVE_SEARCH_WINDOW_START_MS`: 225
  * `PWAVE_SEARCH_WINDOW_END_MS`: 70

* **Fetal ECG Parameters:**
  * `PWAVE_SEARCH_WINDOW_START_MS`: 165
  * `PWAVE_SEARCH_WINDOW_END_MS`: 41

## Acknowledgements

This module was primarily developed by Shaun Dsouza as part of a collaborative work between Sardar Patel Institute of Technology (Mumbai) and Indian Institute of Technology Bombay.

## References

[1] Pan, Jiapu, and Willis J. Tompkins. "A real-time QRS detection algorithm." IEEE transactions on biomedical engineering 3 (2007): 230-236.

[2] Laguna, Pablo, Raimon Jané, and Pere Caminal. "Automatic detection of wave boundaries in multilead ECG signals: Validation with the CSE database." Computers and biomedical research 27.1 (1994): 45-60.

[3] Jane, R., et al. "Evaluation of an automatic threshold based detector of waveform limits in Holter ECG with the QT database." Computers in Cardiology 1997. IEEE, 1997.
