pepbench 0.1.1__tar.gz

pepbench-0.1.1/.gitignore

@@ -0,0 +1,245 @@
+# ignore local config file that specifies local paths
+config.json
+paper_path.json
+*_timing_information.json
+
+# ignore playground folder
+playground
+
+# ignore local cachedir
+cachedir
+
+.ipynb_checkpoints
+*/.ipynb_checkpoints/*
+
+# IPython
+profile_default/
+ipython_config.py
+
+# Remove previous ipynb_checkpoints
+#   git rm -r .ipynb_checkpoints/
+
+### Linux ###
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+
+# IPython
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+### Windows ###
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# End of https://www.toptal.com/developers/gitignore/api/jupyternotebooks,linux,macos,python,windows
+
+# Virtual env
+.venv
+
+# vscode (full)
+.vscode
+
+# PyCharm
+.idea
+
+
+# Pyenv
+.python-version
+
+# debug folder
+_debug

pepbench-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Machine Learning and Data Analytics Lab (MaD Lab), Friedrich-Alexander-Universität Erlangen-Nürnberg (FAU)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pepbench-0.1.1/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: pepbench
+Version: 0.1.1
+Summary: A python package to benchmark different pre-ejection period (PEP) extraction algorithms.
+Author-email: Robert Richer <robert.richer@fau.de>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: <4.0,>=3.10
+Requires-Dist: biopsykit>=0.12.3
+Requires-Dist: jinja2<4,>=3.1.4
+Requires-Dist: pooch>=1.8.2
+Requires-Dist: pytest-cov>=6.0.0
+Requires-Dist: tpcp>=2
+Description-Content-Type: text/markdown
+
+# PEPbench - The python package for automated pre-ejection period (PEP) extraction algorithms.
+
+_pepbench_ presents a framework for the automated extraction of the pre-ejection period (PEP) from
+electrocardiogram (ECG) and impedance cardiography (ICG) signals. The package includes a variety of 
+algorithms for PEP extraction, as well as tools for the evaluation of these algorithms.
+
+
+- 💻 3 Q-peak and 10 B-point Detection [Algorithms](https://pepbench.readthedocs.io/en/latest/modules/index.html) from the literature
+- 📚 Extensive [documentation](https://pepbench.readthedocs.io/en/latest/)
+- 📝 Build to be [easily extendable](https://pepbench.readthedocs.io/en/latest/source/user_guide/create_own_algorithm.html)
+- 📁 2 manually annotated [reference datasets](https://pepbench.readthedocs.io/en/latest/source/user_guide/datasets.html) for evaluation  
+- 📊 [Evaluation tools](https://pepbench.readthedocs.io/en/latest/source/user_guide/evaluation.html) for PEP extraction algorithms
+
+**Documentation:** [pepbench.readthedocs.io](https://pepbench.readthedocs.io/en/latest/README.html)
+
+
+## Installation
+
+First install a supported Python version (3.10 or higher) and then install the package using `pip`.
+
+```bash
+pip install pepbench
+```
+
+### Installing from GitHub
+
+If you want to install the latest version from GitHub, you can use the following command:
+
+```bash
+pip install "git+https://github.com/empkins/pepbench.git"
+```
+
+If you run into problems, clone the repository and install the package locally.
+
+```bash
+git clone https://github.com/empkins/pepbench.git
+cd pepbench
+pip install .
+```
+
+Note: We don't guarantee that the latest version on GitHub is stable.
+
+## Usage Recommendation
+
+`pepbench` is designed to be used in the following ways:
+
+1.  **Usage as a full end-to-end pipeline**:  
+    We provide configurable pipelines to extract the PEP per-heartbeat from ECG and ICG signals. The exact 
+    configuration of the pipeline (i.e., which algorithm combinations are used) depend on the dataset and 
+    can be adjusted to the specific use case. A systematic evaluation of different algorithm combinations
+    is subject to the paper "PEPbench – Open, Reproducible, and Systematic Benchmarking of Automated 
+    Pre-Ejection Period Extraction Algorithms".
+
+    In this case, we recommend to cite the paper and the package as follows:
+
+    > PEP extraction was performed using the `pepbench` Python library pipeline (version {insert version you used}) 
+    > as described in the paper [[1]] with the Q-peak extraction proposed by Martinez et al. [[2]] and the B-point 
+    > extraction algorithm proposed by Drost et al. [[3]].
+
+    ```
+    [1] <pepbench citation>
+    [2] Martinez, J. P., Almeida, R., Olmos, S., Rocha, A. P., & Laguna, P. (2004). A wavelet-based ECG delineator
+    evaluation on standard databases. IEEE Transactions on Biomedical Engineering, 51(4), 570-581.
+    https://doi.org/10.1109/TBME.2003.821031
+    [3] Drost, L., Finke, J. B., Port, J., & Schächinger, H. (2022). Comparison of TWA and PEP as indices of a2- and
+    ß-adrenergic activation. Psychopharmacology. https://doi.org/10.1007/s00213-022-06114-8
+    ```
+
+2.  **Usage of individual algorithms**:
+    If you are only interested in a specific algorithm, you can use the individual algorithms provided in the package. 
+    If you are using individual algorithms in this way, we recommend citing the original papers the algorithms were 
+    proposed in and `pepbench` as a software library.  You can find the best references for each algorithm in the documentation of the respective algorithm.
+    
+
+    > B-points were extracted using the{name of algorithm} algorithm [[1]] as implemented in the `pepbench` Python 
+    library [[2]] (version {insert version you used}).
+    
+    ```
+    [1] <algorithm citation>
+    [2] <pepbench citation>
+    ```
+
+
+
+## Contributing
+
+**We want to hear from you (and we want your algorithms)!**
+
+👍 We are always happy to receive feedback and contributions.
+If you run into any issues or have any questions, please open an [issue on GitHub](https://github.com/empkins/pepbench/issues)
+or start a [discussions](https://github.com/empkins/pepbench/discussions) thread.
+
+📚 If you are using *pepbench* in your research or project, we would love to hear about it and link your work here!
+
+💻 And most importantly, we want your algorithms!
+If you have an algorithm that you think would be a good fit for _pepbench_, open an issue, and we can discuss how to integrate it.
+We are happy to help you with the integration process.
+Even if you are not confident in your Python skills, we can discuss ways to get your algorithm into _pepbench_.
+
+
+## License
+
+_pepbench_ (and _biopsykit_, which contains the core algorithm implementations) are published under a 
+[MIT license](https://opensource.org/license/mit/). This is a permissive license, which allows you to use the code in 
+nearly any way you want, as long as you include the original license in you modified version.
+
+
+## For Developers
+
+Install Python >=3.10 and [uv](https://docs.astral.sh/uv/getting-started/installation/).
+Then run the commands below to install [poethepoet](https://poethepoet.natn.io), get the latest source,
+and install the dependencies:
+
+```bash
+git clone https://github.com/empkins/pepbench.git
+uv tool install poethepoet
+uv sync --all-extras --dev
+```
+
+All dependencies are specified in the main `pyproject.toml` when running `uv sync`.
+
+To run any of the tools required for the development workflow, use the provided 
+[poethepoet](https://github.com/nat-n/poethepoet) commands:
+
+```bash
+uv run poe
+...
+CONFIGURED TASKS
+  format            Format all files with black.
+  lint              Lint all files with ruff.
+  check             Check all potential format and linting issues.
+  test              Run Pytest with coverage.
+  docs              Build the html docs using Sphinx.
+  conf_jupyter      Register the pepbench environment as a Jupyter kernel for testing.
+  version           Bump version in all relevant places.
+
+```
+
+### Format and Linting
+
+To ensure consistent code structure this project uses black and ruff to automatically check (and fix) the code format.
+
+```
+poe format  # runs ruff format and ruff lint with the autofix flag
+poe lint # runs ruff without autofix (will show issues that can not automatically be fixed)
+```
+
+If you want to check if all code follows the code guidelines, run `poe ci_check`.
+This can be useful in the CI context.
+
+
+### Tests
+
+All tests are located in the `tests` folder and can be executed by using `poe test`.
+
+
+## Funding and Support
+
+This work was developed within the *Empkins* collaborative research center (SFB 1483) funded by the Deutsche 
+Forschungsgemeinschaft (DFG, German Research Foundation) - Project-ID 442419336, EmpkinS.
+
+<p align="center">
+<img src="./docs/_static/logo/logo_empkins.svg" height="400">
+</p>

pepbench-0.1.1/README.md

@@ -0,0 +1,164 @@
+# PEPbench - The python package for automated pre-ejection period (PEP) extraction algorithms.
+
+_pepbench_ presents a framework for the automated extraction of the pre-ejection period (PEP) from
+electrocardiogram (ECG) and impedance cardiography (ICG) signals. The package includes a variety of 
+algorithms for PEP extraction, as well as tools for the evaluation of these algorithms.
+
+
+- 💻 3 Q-peak and 10 B-point Detection [Algorithms](https://pepbench.readthedocs.io/en/latest/modules/index.html) from the literature
+- 📚 Extensive [documentation](https://pepbench.readthedocs.io/en/latest/)
+- 📝 Build to be [easily extendable](https://pepbench.readthedocs.io/en/latest/source/user_guide/create_own_algorithm.html)
+- 📁 2 manually annotated [reference datasets](https://pepbench.readthedocs.io/en/latest/source/user_guide/datasets.html) for evaluation  
+- 📊 [Evaluation tools](https://pepbench.readthedocs.io/en/latest/source/user_guide/evaluation.html) for PEP extraction algorithms
+
+**Documentation:** [pepbench.readthedocs.io](https://pepbench.readthedocs.io/en/latest/README.html)
+
+
+## Installation
+
+First install a supported Python version (3.10 or higher) and then install the package using `pip`.
+
+```bash
+pip install pepbench
+```
+
+### Installing from GitHub
+
+If you want to install the latest version from GitHub, you can use the following command:
+
+```bash
+pip install "git+https://github.com/empkins/pepbench.git"
+```
+
+If you run into problems, clone the repository and install the package locally.
+
+```bash
+git clone https://github.com/empkins/pepbench.git
+cd pepbench
+pip install .
+```
+
+Note: We don't guarantee that the latest version on GitHub is stable.
+
+## Usage Recommendation
+
+`pepbench` is designed to be used in the following ways:
+
+1.  **Usage as a full end-to-end pipeline**:  
+    We provide configurable pipelines to extract the PEP per-heartbeat from ECG and ICG signals. The exact 
+    configuration of the pipeline (i.e., which algorithm combinations are used) depend on the dataset and 
+    can be adjusted to the specific use case. A systematic evaluation of different algorithm combinations
+    is subject to the paper "PEPbench – Open, Reproducible, and Systematic Benchmarking of Automated 
+    Pre-Ejection Period Extraction Algorithms".
+
+    In this case, we recommend to cite the paper and the package as follows:
+
+    > PEP extraction was performed using the `pepbench` Python library pipeline (version {insert version you used}) 
+    > as described in the paper [[1]] with the Q-peak extraction proposed by Martinez et al. [[2]] and the B-point 
+    > extraction algorithm proposed by Drost et al. [[3]].
+
+    ```
+    [1] <pepbench citation>
+    [2] Martinez, J. P., Almeida, R., Olmos, S., Rocha, A. P., & Laguna, P. (2004). A wavelet-based ECG delineator
+    evaluation on standard databases. IEEE Transactions on Biomedical Engineering, 51(4), 570-581.
+    https://doi.org/10.1109/TBME.2003.821031
+    [3] Drost, L., Finke, J. B., Port, J., & Schächinger, H. (2022). Comparison of TWA and PEP as indices of a2- and
+    ß-adrenergic activation. Psychopharmacology. https://doi.org/10.1007/s00213-022-06114-8
+    ```
+
+2.  **Usage of individual algorithms**:
+    If you are only interested in a specific algorithm, you can use the individual algorithms provided in the package. 
+    If you are using individual algorithms in this way, we recommend citing the original papers the algorithms were 
+    proposed in and `pepbench` as a software library.  You can find the best references for each algorithm in the documentation of the respective algorithm.
+    
+
+    > B-points were extracted using the{name of algorithm} algorithm [[1]] as implemented in the `pepbench` Python 
+    library [[2]] (version {insert version you used}).
+    
+    ```
+    [1] <algorithm citation>
+    [2] <pepbench citation>
+    ```
+
+
+
+## Contributing
+
+**We want to hear from you (and we want your algorithms)!**
+
+👍 We are always happy to receive feedback and contributions.
+If you run into any issues or have any questions, please open an [issue on GitHub](https://github.com/empkins/pepbench/issues)
+or start a [discussions](https://github.com/empkins/pepbench/discussions) thread.
+
+📚 If you are using *pepbench* in your research or project, we would love to hear about it and link your work here!
+
+💻 And most importantly, we want your algorithms!
+If you have an algorithm that you think would be a good fit for _pepbench_, open an issue, and we can discuss how to integrate it.
+We are happy to help you with the integration process.
+Even if you are not confident in your Python skills, we can discuss ways to get your algorithm into _pepbench_.
+
+
+## License
+
+_pepbench_ (and _biopsykit_, which contains the core algorithm implementations) are published under a 
+[MIT license](https://opensource.org/license/mit/). This is a permissive license, which allows you to use the code in 
+nearly any way you want, as long as you include the original license in you modified version.
+
+
+## For Developers
+
+Install Python >=3.10 and [uv](https://docs.astral.sh/uv/getting-started/installation/).
+Then run the commands below to install [poethepoet](https://poethepoet.natn.io), get the latest source,
+and install the dependencies:
+
+```bash
+git clone https://github.com/empkins/pepbench.git
+uv tool install poethepoet
+uv sync --all-extras --dev
+```
+
+All dependencies are specified in the main `pyproject.toml` when running `uv sync`.
+
+To run any of the tools required for the development workflow, use the provided 
+[poethepoet](https://github.com/nat-n/poethepoet) commands:
+
+```bash
+uv run poe
+...
+CONFIGURED TASKS
+  format            Format all files with black.
+  lint              Lint all files with ruff.
+  check             Check all potential format and linting issues.
+  test              Run Pytest with coverage.
+  docs              Build the html docs using Sphinx.
+  conf_jupyter      Register the pepbench environment as a Jupyter kernel for testing.
+  version           Bump version in all relevant places.
+
+```
+
+### Format and Linting
+
+To ensure consistent code structure this project uses black and ruff to automatically check (and fix) the code format.
+
+```
+poe format  # runs ruff format and ruff lint with the autofix flag
+poe lint # runs ruff without autofix (will show issues that can not automatically be fixed)
+```
+
+If you want to check if all code follows the code guidelines, run `poe ci_check`.
+This can be useful in the CI context.
+
+
+### Tests
+
+All tests are located in the `tests` folder and can be executed by using `poe test`.
+
+
+## Funding and Support
+
+This work was developed within the *Empkins* collaborative research center (SFB 1483) funded by the Deutsche 
+Forschungsgemeinschaft (DFG, German Research Foundation) - Project-ID 442419336, EmpkinS.
+
+<p align="center">
+<img src="./docs/_static/logo/logo_empkins.svg" height="400">
+</p>

pepbench-0.1.1/pyproject.toml

@@ -0,0 +1,97 @@
+[project]
+name = "pepbench"
+version = "0.1.1"
+description = "A python package to benchmark different pre-ejection period (PEP) extraction algorithms."
+authors = [{ name = "Robert Richer", email = "robert.richer@fau.de" }]
+requires-python = ">=3.10,<4.0"
+readme = "README.md"
+license = "MIT"
+dependencies = [
+    "biopsykit>=0.12.3",
+    "tpcp>=2",
+    "jinja2>=3.1.4,<4",
+    "pytest-cov>=6.0.0",
+    "pooch>=1.8.2",
+]
+
+[dependency-groups]
+dev = [
+    "black>=24.8.0,<25",
+    "ruff>=0.6.3,<0.7",
+    "ipython>=8.26.0,<9",
+    "ipywidgets>=8.1.3,<9",
+    "ipympl>=0.9.4,<0.10",
+    "ipykernel>=6.29.5,<7",
+    "pytest>=8.3.4,<9",
+    "numpydoc>=1.8.0,<2",
+    "poethepoet>=0.33.0",
+    "toml>=0.10.2",
+    "sphinx-gallery>=0.19.0",
+    "recommonmark>=0.7.1",
+    "memory-profiler>=0.61.0",
+    "pydata-sphinx-theme>=0.16.1",
+    "sphinx-copybutton>=0.5.2",
+    "nbsphinx>=0.9.7",
+]
+
+[tool.uv.sources]
+biopsykit = { git = "https://github.com/mad-lab-fau/BioPsyKit.git", branch = "main" }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/pepbench"]
+
+[tool.hatch.build.targets.wheel]
+include = ["src/pepbench"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/pepbench" = "pepbench"
+
+[tool.black]
+line-length = 120
+target-version = ['py310']
+exclude = '''
+(
+  /(
+      \.eggs         # exclude a few common directories in the
+    | \.git          # root of the project
+    | \.hg
+    | \.mypy_cache
+    | \.tox
+    | \.venv
+    | _build
+    | docs
+    | build
+    | dist
+    | \.virtual_documents
+  )/
+)
+'''
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+line_length = 120
+skip_gitignore = true
+
+[tool.poe.tasks]
+_format = "ruff format ."
+_auto_fix = "ruff check . --fix-only --show-fixes --exit-zero"
+_auto_fix_unsafe = "ruff check . --fix-only --show-fixes --exit-zero --unsafe-fixes"
+format = ["_auto_fix", "_format"]
+format_unsafe = ["_auto_fix_unsafe", "_format"]
+lint = { cmd = "ruff check src --fix", help = "Lint all files with ruff." }
+_lint_ci = "ruff check src --output-format=github"
+_check_format = "ruff format . --check"
+ci_check = { sequence = ["_check_format", "_lint_ci"], help = "Check all potential format and linting issues." }
+test = { cmd = "pytest --cov=pepbench --cov-report=term-missing --cov-report=xml", help = "Run Pytest with coverage." }
+docs = { "script" = "_tasks:task_docs()",  help = "Build the html docs using Sphinx." }
+docs_clean = { "script" = "_tasks:task_docs(clean=True)",  help = "Remove all old build files and build a clean version of the docs." }
+docs_preview = { cmd = "python -m http.server --directory docs/_build/html", help = "Preview the built html docs." }
+version = { cmd = "uvx bump-my-version" }
+conf_jupyter = { cmd = "python -m ipykernel install --user --name pepbench --display-name pepbench", help = "Add a new jupyter kernel for the project."}
+remove_jupyter = { cmd = "jupyter kernelspec uninstall pepbench", help = "Remove the project specific jupyter kernel."}
+update_example_data = { script="_tasks:task_update_example_data", help = "Update the example data registry."}