Metadata-Version: 2.1
Name: aladin-ecg
Version: 1.0.0
Summary: ALADIN is a framework for ambulatory and clinical ECG processing, delineation, analysis, and diagnosis
Keywords: ecg,delineation,segmentation,diagnosis,arrhythmia,ambulatory,deep learning
Author: Lukas P.A. Arts
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: <3.15,>=3.11
Requires-Dist: torch<3,>=2.10
Requires-Dist: acvl-utils<0.3,>=0.2.6
Requires-Dist: dynamic-network-architectures<0.4,>=0.3.1
Requires-Dist: tqdm<5,>=4.67
Requires-Dist: seaborn<1,>=0.13
Requires-Dist: dicom2nifti<3,>=2.6
Requires-Dist: batchgenerators<0.26,>=0.25.3
Requires-Dist: batchgeneratorsv2<0.4,>=0.3.5
Requires-Dist: scikit-image<0.27,>=0.26
Requires-Dist: SimpleITK<3,>=2.5.5
Requires-Dist: google-cloud-storage<4,>=3
Requires-Dist: google-cloud-bigquery<4,>=3
Requires-Dist: boto3<2,>=1.40
Requires-Dist: openpyxl<4,>=3.1
Requires-Dist: neurokit2<0.3,>=0.2.12
Requires-Dist: wfdb<5,>=4.3
Requires-Dist: scipy<2,>=1.17.1
Requires-Dist: numpy<3,>=2.0
Requires-Dist: scikit-learn<2,>=1.9
Requires-Dist: psutil<8,>=7
Requires-Dist: rich<15,>=14
Requires-Dist: dtw-python<2,>=1.7.5
Requires-Dist: pandas<4,>=2.2
Requires-Dist: matplotlib<4,>=3.10
Requires-Dist: pymongo<5,>=4.17
Requires-Dist: huggingface-hub<2,>=1
Requires-Dist: graphviz<1,>=0.20
Requires-Dist: tifffile>=2025.6
Requires-Dist: requests<3,>=2.32
Requires-Dist: nibabel<6,>=5.3
Requires-Dist: yacs<1,>=0.1.8
Requires-Dist: einops<1,>=0.8
Provides-Extra: test
Requires-Dist: pytest<9,>=8; extra == "test"
Description-Content-Type: text/markdown

![ALADIN](data/resources/aladin_logo_2.png)

[![Cross-platform build](https://github.com/fastlib/ALADIN/actions/workflows/build.yaml/badge.svg)](https://github.com/fastlib/ALADIN/actions/workflows/build.yaml)
 
ALADIN is a neuro-symbolic AI model that preprocesses, segments, and diagnoses single- and multi-lead ECG signals. It has been validated extensively on three diverse patient cohorts with a combined size of 13,000 patients. ALADIN can handle any ECG recording from clinical MUSE recordings to handheld KardiaMobile measurements ranging from 6 seconds to 24 hours. 

```
pip install aladin-ecg
```
 
## Changelog:

💡Version 1.1.2 08/08/2026:
- Added PyPi support

💡Version 1.1.1 15/07/2026:
- Added Github Actions to verify cross-platform compatibality
- Added unit tests
- Downloads missing model weights automatically from Hugging Face (access required)

💡Version 1.1.0 16/03/2026:
- Added ability to handle 1, 3, and 12-lead ECG
- Added median beat extraction and corresponding beat median segmentations based on segmentation and QRS clusters

 
## System requirements:
- Linux Ubuntu >= 20.04 or MacOSX 13.6.x or Microsoft Windows >=10
- Python >3.10 
- 20Gb free diskspace
- Modern GPU with >12Gb VRAM is recommended for training and inference
 
Tested on Linux Ubuntu 20.04, MacOSX 13.6.x, and Microsoft Windows 10 and 11 Home. CPU-only support is available, but a modern GPU is required for training and will speed up inference substantially. Tested on NVidia GeForce 3090. 
 
## Installation

When on MacOS, a homebrew install of OpenMP is required:
```bash
brew install libomp
```

Next, clone and install ALADIN:
```bash
git clone https://github.com/fastlib/ALADIN.git
cd ALADIN
python -m venv VENV #create virtual environment
source VENV/bin/activate #activate environment

pip install scikit-build-core pybind11 ninja cmake #build tooling, must be installed before building aladin
pip install torch #must be installed before building aladin's C++ extension
pip install ./nnUNet
pip install ./aladin --no-build-isolation
mkdir models
```

## Example usage
```python
import numpy as np
from aladin import ALADIN
from aladin.core import Record

#ecg should be a dictionary with the keys being lead names
fs = 250 #hz
ecg = {"II": np.random.rand(fs*10)}

#create record object
record = Record(ecg, fs)

#create ALADIN object
aladin = ALADIN(modelpaths=["ClassificationTrainer__nnUNetWithClassificationPlans__1d_decoding"])

#perform segmentation
aladin.segment(record)

#perform diagnosis
aladin.analyse(record)

#perform median beat extraction
aladin.extract_median_beat(record)
median_beat = record.median_beat.ecg
```

## Example code
```bash
python demo.py --case=[recording]
```
Where `[recording]` can be one of `(STANFORD1, STANFORD2, A01986, A08391)`.

## Reproduce benchmark

See [Benchmark.md](benchmark.md) for details on benchmark reproduction.

## macOS build notes

ALADIN's C++ extension (`aladin._main`) uses OpenMP for native multithreading.
On macOS, Apple Clang doesn't ship OpenMP itself, so the extension is built
using Homebrew's `libomp` for headers — but it links against **PyTorch's own
bundled `libomp.dylib`** at runtime rather than Homebrew's copy. This is
necessary because loading two independent OpenMP runtimes into the same
Python process (one from Homebrew via this extension, one bundled with
PyTorch) causes macOS to crash under concurrent load, with segfaults inside
`libomp`'s `__kmp_suspend_64`. Sharing a single runtime with PyTorch avoids
that.

This has two consequences for how you install/rebuild ALADIN on macOS:

- **`torch` must already be installed before building `aladin`.** The build
  step needs to `import torch` to locate its bundled `libomp.dylib`. If torch
  isn't importable at build time, the build falls back to Homebrew's
  `libomp` with a `WARNING`, which reintroduces the crash risk above.
- **Always pass `--no-build-isolation` when installing/rebuilding `aladin`.**
  By default, `pip install` builds packages inside a temporary, isolated
  environment that can't see `torch` (or anything else) installed in your
  venv, even though it reuses the same Python interpreter — which defeats
  the point above. `--no-build-isolation` builds directly against your venv
  instead, so make sure `scikit-build-core`, `pybind11`, `ninja`, `cmake`,
  and `torch` are installed in the venv first (as in the install steps
  above). This applies every time you rebuild the extension, e.g. after
  `pip install -e ./aladin` for development.

ALADIN will automatically download the model weights from the private Hugging Face repo `AUMC/ALADIN` into
`~/.cache/aladin/models` the first time they're needed. However, this requires Hugging Face account access 
to the `AUMC/ALADIN` repo, and being authenticated locally via `huggingface-cli login` or 
the `HF_TOKEN` environment variable.

