## BeliefPPG: Uncertainty-aware Heart Rate Estimation from PPG signals via Belief Propagation
BeliefPPG is a novel learning-based method that achieves state-of-the-art performance on several heart rate estimation benchmarks extracted from photoplethysmography signals (PPG). It considers the evolution of the heart rate in the context of a discrete-time stochastic process that is represented as a hidden Markov model. It derives a distribution over possible heart rate values for a given PPG signal window through a trained neural network. Using belief propagation, it incorporates the statistical distribution of heart rate changes to refine these estimates in a temporal context. From this, it obtains a quantized probability distribution over the range of possible heart rate values that captures a meaningful and well-calibrated estimate of the inherent predictive uncertainty.
Install
----------
You can install the pip package using:
```bash
pip install beliefppg
```
Quick Start
----------
To start inferring heart rate from PPG and accelerometer data, you first need to import the `infer_hr` function from the `beliefppg` package.
```python
from beliefppg import infer_hr
# Example of a simple function call (adjust 'ppg' and 'sampling_rate' as per your data)
hr, uncertainty, time_intervals = infer_hr(ppg, sampling_rate)
```
The accuracy of BeliefPPG can be enhanced by incorporating accelerometer data alongside the PPG signals. Additionally, users can choose between belief propagation and Viterbi decoding, specify the uncertainty measure, and decide whether to disable the time-domain backbone of the network architecture. Detailed explanations of these features can be found in our [paper](https://static.siplab.org/papers/uai2023-beliefppg.pdf) and [supplementary material](https://static.siplab.org/papers/uai2023-beliefppg-supplementary.pdf).
```python
from beliefppg import infer_hr
ppg_sampling_rate = 128 # Hz (sampling rate of ppg sensor)
acc_sampling_rate = 128 # Hz (sampling rate of accelerometer)
# Load data item containing the PPG, HR, and IMU signals --- challenging custom dataset
data = np.load('Data/example.npy', allow_pickle=True).item()
ppg = data['PPG head'].reshape((-1,1)) # reshape ppg to (n_samples, n_channels)
IMU_X = data['IMU X head']
IMU_Y = data['IMU Y head']
IMU_Z = data['IMU Z head']
acc = np.stack([IMU_X,IMU_X, IMU_Z], axis=-1)
hr, uncertainty, time_intervals = infer_hr(
ppg, # PPG signal data with shape (n_samples, n_channels)
ppg_sampling_rate, # Sampling frequency of the PPG signal in Hz
acc=acc, # Accelerometer signal data with shape (n_samples, n_channels). BeliefPPG to function without accelerometer signal data, but its accuracy may be reduced.
acc_freq=acc_sampling_rate, # Sampling frequency of the accelerometer signal in Hz
decoding='sumproduct', # Decoding method to use, either "sumproduct" or "viterbi"
use_time_backbone=True, # Whether to use the time-domain backbone or not
uncertainty='std' # Measure for predictive uncertainty, either "entropy" or "std"
)
# The function returns predicted heart rates in BPM, uncertainties (entropy or std), and time intervals in seconds.
```
For a complete example demonstrating how to use BeliefPPG for heart rate inference, see the [tutorial notebook](https://github.com/eth-siplab/BeliefPPG/blob/master/tutorial.ipynb).
Citation
----------
If your find our paper or codes useful, please cite our work:
@InProceedings{uai2023-beliefppg,
author={Bieri, Valentin and Streli, Paul and Demirel, Berken Utku and Holz, Christian},
title = {BeliefPPG: Uncertainty-aware Heart Rate Estimation from PPG signals via Belief Propagation},
year = {2023},
organization={PMLR},
booktitle = {Conference on Uncertainty in Artificial Intelligence (UAI)}
}
License and Acknowledgement
----------
This project is released under the MIT license.
Raw data
{
"_id": null,
"home_page": "https://github.com/eth-siplab/BeliefPPG",
"name": "beliefppg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "PPG, heart rate, signal processing, uncertainty estimation, biomedical signals",
"author": "Paul Streli",
"author_email": "paul.streli@inf.ethz.ch",
"download_url": "https://files.pythonhosted.org/packages/8f/ae/6334e4b828474ff78c0abdd52605d8267e2a50e5d10f2f903a928f72b255/beliefppg-0.1.3.tar.gz",
"platform": null,
"description": "## BeliefPPG: Uncertainty-aware Heart Rate Estimation from PPG signals via Belief Propagation\n\nBeliefPPG is a novel learning-based method that achieves state-of-the-art performance on several heart rate estimation benchmarks extracted from photoplethysmography signals (PPG). It considers the evolution of the heart rate in the context of a discrete-time stochastic process that is represented as a hidden Markov model. It derives a distribution over possible heart rate values for a given PPG signal window through a trained neural network. Using belief propagation, it incorporates the statistical distribution of heart rate changes to refine these estimates in a temporal context. From this, it obtains a quantized probability distribution over the range of possible heart rate values that captures a meaningful and well-calibrated estimate of the inherent predictive uncertainty.\n\nInstall\n----------\nYou can install the pip package using:\n```bash\npip install beliefppg\n```\n\nQuick Start\n----------\nTo start inferring heart rate from PPG and accelerometer data, you first need to import the `infer_hr` function from the `beliefppg` package.\n```python\nfrom beliefppg import infer_hr\n\n# Example of a simple function call (adjust 'ppg' and 'sampling_rate' as per your data)\nhr, uncertainty, time_intervals = infer_hr(ppg, sampling_rate)\n```\n\nThe accuracy of BeliefPPG can be enhanced by incorporating accelerometer data alongside the PPG signals. Additionally, users can choose between belief propagation and Viterbi decoding, specify the uncertainty measure, and decide whether to disable the time-domain backbone of the network architecture. Detailed explanations of these features can be found in our [paper](https://static.siplab.org/papers/uai2023-beliefppg.pdf) and [supplementary material](https://static.siplab.org/papers/uai2023-beliefppg-supplementary.pdf).\n```python\nfrom beliefppg import infer_hr\n\nppg_sampling_rate = 128 # Hz (sampling rate of ppg sensor)\nacc_sampling_rate = 128 # Hz (sampling rate of accelerometer)\n\n# Load data item containing the PPG, HR, and IMU signals --- challenging custom dataset\ndata = np.load('Data/example.npy', allow_pickle=True).item()\n\nppg = data['PPG head'].reshape((-1,1)) # reshape ppg to (n_samples, n_channels)\nIMU_X = data['IMU X head']\nIMU_Y = data['IMU Y head']\nIMU_Z = data['IMU Z head']\nacc = np.stack([IMU_X,IMU_X, IMU_Z], axis=-1)\n\nhr, uncertainty, time_intervals = infer_hr(\n ppg, # PPG signal data with shape (n_samples, n_channels)\n ppg_sampling_rate, # Sampling frequency of the PPG signal in Hz\n acc=acc, # Accelerometer signal data with shape (n_samples, n_channels). BeliefPPG to function without accelerometer signal data, but its accuracy may be reduced.\n acc_freq=acc_sampling_rate, # Sampling frequency of the accelerometer signal in Hz\n decoding='sumproduct', # Decoding method to use, either \"sumproduct\" or \"viterbi\"\n use_time_backbone=True, # Whether to use the time-domain backbone or not\n uncertainty='std' # Measure for predictive uncertainty, either \"entropy\" or \"std\"\n)\n# The function returns predicted heart rates in BPM, uncertainties (entropy or std), and time intervals in seconds.\n```\nFor a complete example demonstrating how to use BeliefPPG for heart rate inference, see the [tutorial notebook](https://github.com/eth-siplab/BeliefPPG/blob/master/tutorial.ipynb).\n\nCitation\n----------\nIf your find our paper or codes useful, please cite our work:\n\n @InProceedings{uai2023-beliefppg,\n author={Bieri, Valentin and Streli, Paul and Demirel, Berken Utku and Holz, Christian},\n title = {BeliefPPG: Uncertainty-aware Heart Rate Estimation from PPG signals via Belief Propagation},\n year = {2023},\n organization={PMLR},\n booktitle = {Conference on Uncertainty in Artificial Intelligence (UAI)}\n }\n\nLicense and Acknowledgement\n----------\nThis project is released under the MIT license.\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Taking multi-channel PPG and Accelerometer signals as input, BeliefPPG predicts the instantaneous heart rate and provides an uncertainty estimate for the prediction.",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/eth-siplab/BeliefPPG"
},
"split_keywords": [
"ppg",
" heart rate",
" signal processing",
" uncertainty estimation",
" biomedical signals"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "30b9268b1d971ac83d7e004dec4d69e959e351f9b8f2dc2d92eea87499b42508",
"md5": "780c095ea83fdf93111d8531a653b1be",
"sha256": "d3c605551f80aee2c72be22f309d7c4bb960f978e44e74d57ead519b11aa1920"
},
"downloads": -1,
"filename": "beliefppg-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "780c095ea83fdf93111d8531a653b1be",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 818812,
"upload_time": "2024-05-06T18:37:53",
"upload_time_iso_8601": "2024-05-06T18:37:53.100881Z",
"url": "https://files.pythonhosted.org/packages/30/b9/268b1d971ac83d7e004dec4d69e959e351f9b8f2dc2d92eea87499b42508/beliefppg-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8fae6334e4b828474ff78c0abdd52605d8267e2a50e5d10f2f903a928f72b255",
"md5": "0140a716a766b9d20919d938e9732f4d",
"sha256": "240a86b198171e914636da6a358de8209b40cca70b0d1772f5019775754c59a3"
},
"downloads": -1,
"filename": "beliefppg-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "0140a716a766b9d20919d938e9732f4d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 817374,
"upload_time": "2024-05-06T18:37:55",
"upload_time_iso_8601": "2024-05-06T18:37:55.038667Z",
"url": "https://files.pythonhosted.org/packages/8f/ae/6334e4b828474ff78c0abdd52605d8267e2a50e5d10f2f903a928f72b255/beliefppg-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-06 18:37:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eth-siplab",
"github_project": "BeliefPPG",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "beliefppg"
}
JSON
