Metadata-Version: 2.4
Name: pantompkins
Version: 1.0.0
Summary: Python implementation of the Pan-Tompkins real-time QRS detection algorithm for ECG signals
Project-URL: Homepage, https://github.com/Hatem-Zehir/pan-tompkins-qrs-detector
Project-URL: Repository, https://github.com/Hatem-Zehir/pan-tompkins-qrs-detector
Project-URL: Bug Tracker, https://github.com/Hatem-Zehir/pan-tompkins-qrs-detector/issues
Project-URL: Documentation, https://github.com/Hatem-Zehir/pan-tompkins-qrs-detector/blob/main/docs/quickstart.md
Author-email: Hatem Zehir <hatem.zehir@univ-annaba.dz>
License: Copyright (c) 2018, Hooman Sedghamiz
        Copyright (c) 2026, Dr. Hatem Zehir
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are
        met:
        
            * Redistributions of source code must retain the above copyright
              notice, this list of conditions and the following disclaimer.
            * Redistributions in binary form must reproduce the above copyright
              notice, this list of conditions and the following disclaimer in
              the documentation and/or other materials provided with the distribution
            * Neither the name of the Linköping University nor the names
              of its contributors may be used to endorse or promote products derived
              from this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
        ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
        LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
        POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: ECG,Pan-Tompkins,QRS,biomedical,cardiology,signal processing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.9
Requires-Dist: matplotlib>=3.4
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: numpydoc>=1.6; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=1.3; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Description-Content-Type: text/markdown

# Pan-Tompkins QRS Detector — Python

A Python port of the Pan-Tompkins real-time QRS detection algorithm for ECG signals.

> **Original MATLAB implementation** by Hooman Sedghamiz (Feb 2018), MSc Biomedical Engineering, Linköping University.  
> **Python port** by Dr. Hatem Zehir.  
> Python conversion retains the original BSD 3-Clause license — see [`LICENSE`](LICENSE).

---

## Algorithm Overview

The Pan-Tompkins algorithm is a classic, widely used method for detecting QRS complexes (R-peaks) in ECG signals in real time. It processes the ECG through a signal-processing pipeline:

1. **Bandpass filter** (5–15 Hz) — removes baseline wander and high-frequency noise
2. **Derivative filter** — emphasises the steep slopes of QRS complexes
3. **Squaring** — makes all values positive and amplifies large slopes
4. **Moving-window integration** (~150 ms window) — produces a smooth envelope
5. **Adaptive thresholding & decision logic** — distinguishes true QRS complexes from T-waves and noise using two running thresholds updated after each beat

### References
- Pan, J. & Tompkins, W. J., *"A Real-Time QRS Detection Algorithm"*, IEEE Trans. Biomed. Eng., BME-32(3), March 1985.
- Sedghamiz, H., *"Matlab Implementation of Pan Tompkins ECG QRS detector"*, 2014. [ResearchGate](https://www.researchgate.net/publication/313673153)

---

## Installation

```bash
pip install -r requirements.txt
```

**Dependencies:**

| Package | Version |
|---------|---------|
| numpy | ≥ 1.21 |
| scipy | ≥ 1.7 |
| matplotlib | ≥ 3.4 |

---

## Usage

```python
import numpy as np
from pan_tompkins import pan_tompkins

# Load your ECG signal and sampling frequency
# ecg : 1-D numpy array of the raw ECG
# fs  : sampling frequency in Hz (e.g. 200, 360, 500)

qrs_amp, qrs_idx, delay = pan_tompkins(ecg, fs, gr=True)

print(f"Detected {len(qrs_idx)} QRS complexes")
print(f"R-peak sample indices: {qrs_idx}")
```

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `ecg` | `np.ndarray` | Raw 1-D ECG signal |
| `fs` | `float` | Sampling frequency in Hz |
| `gr` | `bool` | Plot intermediate stages and results (default `True`) |

### Returns

| Return value | Description |
|---|---|
| `qrs_amp_raw` | Amplitudes of detected R-waves (from bandpass-filtered signal) |
| `qrs_i_raw` | Sample indices of detected R-waves |
| `delay` | Filter delay in samples |

---

## Quick Demo

Running the script directly generates a synthetic ECG (~70 bpm, 10 s at 200 Hz) and detects QRS complexes:

```bash
python pan_tompkins.py
```

Expected output:
```
Detected 12 QRS complexes
R-peak indices: [ 100  270  440  610  780  950 1119 1289 1459 1629 1799 1969]
Delay: 15.0 samples
```

---

## Notes

- For `fs = 200 Hz`, separate low-pass (12 Hz) and high-pass (5 Hz) Butterworth filters are applied sequentially.
- For all other sampling rates, a single bandpass Butterworth filter (5–15 Hz) is used.
- The derivative filter kernel is interpolated to match the sampling rate when `fs ≠ 200`.
- `filtfilt` (zero-phase filtering) is used throughout, so `delay` reports the moving-average window contribution only.

---

## License

BSD 3-Clause License. Copyright (c) 2018, Hooman Sedghamiz. See [`LICENSE`](LICENSE) for full details.

Copyright (c) 2018 Hooman Sedghamiz  
Copyright (c) 2026 Dr. Hatem Zehir

---

## Citation

If you use this implementation in your research, please cite:

```bibtex
@article{PanTompkins1985,
  author = {Pan, J. and Tompkins, W. J.},
  title = {A Real-Time QRS Detection Algorithm},
  journal = {IEEE Transactions on Biomedical Engineering},
  year = {1985},
  volume = {BME-32},
  number = {3},
  pages = {230--236},
  doi = {10.1109/TBME.1985.325532}
}

@software{ZehirPythonPort2026,
  author = {Zehir, Hatem},
  title = {Pan-Tompkins QRS Detector — Python},
  year = {2026},
  url = {https://github.com/Hatem-Zehir/pan-tompkins-qrs-detector}
}
```

## 🤝 Contributing

Contributions, bug reports, and feature requests are welcome.

Please open an issue or submit a pull request.
