Metadata-Version: 2.4
Name: ECGProcess
Version: 1.3.1
Summary: A python module to process and standardise ECG data
Author-email: "A. Floriaan Schmidt" <floriaanschmidt@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://gitlab.com/SchmidtAF/ECGProcess
Project-URL: Documentation, https://SchmidtAF.gitlab.io/ECGProcess/
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENCE.txt
Requires-Dist: lxml>=5
Requires-Dist: xmltodict>=1.0.3
Requires-Dist: pandas>=2.1.1
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.7
Requires-Dist: pydicom>=2
Requires-Dist: matplotlib>=3.9
Provides-Extra: dev
Requires-Dist: pytest>=6; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"
Requires-Dist: pytest-dependency>=0.5; extra == "dev"
Requires-Dist: codespell; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: bump2version>=1; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: sphinx-rtd-theme; extra == "dev"
Requires-Dist: sphinx-bootstrap-theme; extra == "dev"
Requires-Dist: furo; extra == "dev"
Requires-Dist: myst-parser; extra == "dev"
Requires-Dist: nbsphinx; extra == "dev"
Requires-Dist: nbsphinx-link; extra == "dev"
Requires-Dist: sphinx-argparse; extra == "dev"
Requires-Dist: numpydoc; extra == "dev"
Requires-Dist: docutils<0.21; extra == "dev"
Requires-Dist: notebook; extra == "dev"
Requires-Dist: jupyter; extra == "dev"
Provides-Extra: tensorflow
Requires-Dist: tensorflow>=2.16; extra == "tensorflow"
Provides-Extra: wfdb
Requires-Dist: wfdb<5,>=4.3.1; extra == "wfdb"
Provides-Extra: all
Requires-Dist: tensorflow>=2.16; extra == "all"
Requires-Dist: wfdb<5,>=4.3.1; extra == "all"
Dynamic: license-file

<!-- TODO once dev is merged into master and the pages job redeploys, switch
     this back to the Sphinx-published URL:
     https://SchmidtAF.gitlab.io/ECGProcess/_static/ecgp_logo.png -->
<img src="https://gitlab.com/SchmidtAF/ECGProcess/-/raw/d853ccf/docs/source/_static/ecgp_logo.png" alt="ECGProcess icon" width="250"/>

# An ECG processing module
__version__: `1.3.1`

This repository hosts a collection of functions for processing
electrocardiogram (ECG) data and preparing it for analysis.

At a glance, ECGProcess is driven by three units:

* A **processor** unit, reads individual ECG files and based on 
  a user-supplied configuration file extracts waveform
  signals, median beats, and metadata to python dictionaries; see [Configuration files](https://SchmidtAF.gitlab.io/ECGProcess/configuration_files.html)).
* The **table** unit, `ECGTable`, loops over a directory of ECG files, 
  calls the reader for each one, while applying optional engineering steps
  (e.g. resampling, calibration, lead correction), and again optionally 
  concatenating multiple files together.
* A **writer** unit, tells `ECGTable` what to write to disk
  (tables, NumPy arrays, WFDB records, images, ...). 

Together these units implement an application programming interface (API),
mapping ECG data from distinct file types to class attributes
providing a fixed interface for downstream processing. 
The package ships with boilerplate classes and validation utilities,
letting the user expand **processing** of additional file types,
build custom **engineering** (e.g. standardisation) pipelines, as well as 
create custom **writers**.

Please consult the [documentation](https://SchmidtAF.gitlab.io/ECGProcess/)
for the full picture.

## Installation 
The package is available on PyPI, and conda, with the latest source code 
available on gitlab. 

### Installation using PyPI

To install the package from PyPI, run:

```bash
pip install ecgprocess
```

This installs the latest stable release along with its dependencies.

### Installation using conda

A Conda package is maintained in my personal Conda channel.
To install from this channel, run:

```bash
conda install afschmidt::ecgprocess
```

### Installation using gitlab

If you require the latest updates, potentially not yet formally released,
you can install the package directly from GitLab.

First, clone the repository and move into its root directory:

```bash
git clone git@gitlab.com:SchmidtAF/ecgprocess.git
cd ecgprocess
```

Install the dependencies:

```bash
# From the root of the repository
conda env create --file ./resources/conda/envs/conda_create.yaml
```

To add to an existing environment use:

```bash
# From the root of the repository
conda env update --file ./resources/conda/envs/conda_update.yaml
```

Next the package can be installed: 

```bash
make install
```

#### Development
For development work, install the package in editable mode, with its
development dependencies (`pytest`, `codespell`, `sphinx`, ...) and Git
commit hooks configured:

```bash
make install-dev
```

This command installs the package in editable mode with the `[dev]`
extras and configures Git commit hooks, allowing you to run `git pull`
to update the repository or switch branches without reinstalling.

Alternatively, you can install manually. This is exactly equivalent
to `make install-dev`:

```bash
python -m pip install -e ".[dev]"
python .githooks/.setup_git_hooks.py
```

#### Git Hooks Configuration


When setting up a development environment, the `setup-hooks` command 
configures Git hooks to enforce conventional commit message formatting and 
spell check using `codespell`.

To view the commit message format requirements, run:

```bash
./.githooks/commit-msg -help
```

For frequent use, add this function to your shell configuration (`~/.bashrc` 
or `~/.zshrc`):

```bash
commit-format-help() {
    local git_root
    git_root=$(git rev-parse --show-toplevel 2>/dev/null)
    
    if [ -z "$git_root" ]; then
        echo "Error: Not inside a git repository"
        return 1
    fi
    
    local hook_path="$git_root/.githooks/commit-msg"
    
    if [ ! -f "$hook_path" ]; then
        echo "Error: commit-msg hook not found"
        return 1
    fi
    
    "$hook_path" --help
}
```

## Next steps...
If you installed with `make install-dev`, you might wish to run `pytest` to 
confirm everything is in working order. 

```sh
# From the root of the repository
pytest tests
```

## Usage

Please have a look at the [example](https://SchmidtAF.gitlab.io/ECGProcess/examples.html)
 recipes. 

## Icon

The package icon features the Etruscan shrew, one of the smallest
mammals, whose heart can beat over 1,500 times a minute, the fastest
heart rate of any mammal.
