ECG & Accelerometry (EDF) Preprocessing Pipeline

An end-to-end Python pipeline for processing multi-day wearable sensor data from .EDF files. It extracts heart rate, heart rate variability (HRV) and physical activity metrics, performs quality control and imputation, and generates summary reports and visualisations.

📖 Full documentation: cardiac-prep.readthedocs.io

You do not need to be a programmer to use this. Follow the steps in order, copying each command exactly.

🚦 The three commands

Once set up, this is the whole pipeline. Run them in this order:

1. Process your recordings

cardiac-prep process

Reads every .edf file in input_data and writes results to output. About 30 seconds per file.

2. Summarise the whole dataset

cardiac-prep summarise

Creates population-level plots across all participants.

3. Inspect one participant (optional)

cardiac-prep inspect --list

cardiac-prep inspect --subject NAME_FROM_THE_LIST

Add --show to open the plots in a window as well as saving them.

First time here? Do the Setup below first. Add --help to any command to see its options.

Features ✨

• Parallel Processing: Uses all CPU cores except one, so your machine stays usable (no GPU needed). Configurable via n_processes.
• Preprocessing: QRS detection, artifact removal, signal quality assessment.
• Data Imputation: Linear interpolation for short gaps, time-of-day averaging for longer ones.
• Comprehensive Metrics:
  • Heart Rate (Resting, Min, Max, Average)
  • Heart Rate Variability (RMSSD and log-normalised RMSSD to account for HR)
  • Physical Activity (time in Sedentary, Light, Moderate and Vigorous zones)
• Automated Reporting: A 2-page PDF summary report per participant.
• Dataset Summarisation: Population-level trend plots.

Before you start 📝

You need Python 3.9, 3.10, 3.11 or 3.12. Python 3.13 is not yet supported.

To check what you have, open a terminal and type:

python --version

If that says "command not found", or shows a version outside the range, install Miniforge from https://conda-forge.org/download/ and reopen your terminal.

Opening a terminal: on macOS press Cmd + Space, type "Terminal", press Enter. On Windows press Start, type "Miniforge Prompt", press Enter. On Linux press Ctrl + Alt + T.

Setup 🚀

You only do this once.

Step 1 – Create a separate environment

An environment is a private space for this project's software, so it cannot clash with anything else on your computer. Pick ONE option.

Option A – conda (recommended)

conda create -n cardiacprep python=3.11 -y

conda activate cardiacprep

Option B – venv (built into Python)

python -m venv .venv

Activate it. On macOS or Linux:

source .venv/bin/activate

On Windows:

.venv\Scripts\activate

✅ How to tell it worked: your prompt now starts with (cardiacprep) or (.venv).

⚠️ Activate the environment every time you open a new terminal. If your prompt does not show the name in brackets, run the activate line again.

Step 2 – Install the pipeline

pip install cardiacprep

This takes several minutes. It is finished when your prompt reappears.

Step 3 – Set up a folder for your study

Go to wherever you want your results to live, then:

cardiac-prep init

This creates config.yaml plus the input_data, output and models folders, and prints the handful of settings worth checking before you start.

Step 4 – The heartbeat detector

The pipeline uses a machine-learning model to find heartbeats. It is too big for this repository, so it is downloaded separately.

You do not need to do anything here. The first run fetches it into the models folder, checks it against a known checksum, and carries on.

To fetch it now instead, useful before working somewhere with no wifi:

cardiac-prep download

⚠️ No internet on the machine doing the processing? Fetch the model elsewhere, copy the .keras file into models, and set auto_download_model: false in config.yaml.

Step 5 – Check it works

cardiac-prep --help

If you see a list of options, setup is complete. 🎉

Running it 🏃

Put your .edf files into the input_data folder, then use the three commands above.

To preview what will be processed without processing anything:

cardiac-prep process --dry-run

To use folders elsewhere on your computer:

cardiac-prep process --input /path/to/my/edfs --output /path/to/my/results

Changing settings ⚙️

All settings live in config.yaml. Open it in any text editor. Every setting is explained in comments and every one is optional, so deleting a line restores its default.

You should never need to edit a .py file.

Mistakes are reported clearly and stop the run immediately, before anything is processed.

Outputs 📂

An ./output/ directory containing:

• Participant folders: a plots directory with the PDF report, and a processed_data directory with detailed CSVs.
• Top-level files: an aggregated df_info_summary.csv.gz plus dataset-wide summary plots.

Every row of df_info_summary.csv.gz records model_file and model_sha256, identifying exactly which detector produced those results. Failed recordings get failed = 1 and a failure_reason explaining why.

Reading *_df_qc.csv.gz

One row = one 10-second segment of the recording. The index is seconds from the start, so row 0 is 00:00:00–00:00:10, row 10 is the next segment, and so on.

Why are the beat columns so often blank? They are only computed for segments that were actually analysed. A segment is skipped when the device was not worn, the signal was too noisy or clipped to pass initial checks, or the detector found fewer than n_beats_min beats. Separately, RRm_raw is deliberately blanked wherever passed_finalQC is False, so blank means "not measurable here", not "missing data".

Lots of blanks therefore means a lot of non-wear time or poor signal quality, and is expected rather than a bug. To judge quality fairly, look at prop_ECG_worn_passed_finalQC in the summary file: it measures quality among worn time only, so it is not diluted by periods when the device was off.

Things to be aware of ⚠️

Resting heart rate and HRV use a fixed 21:00–09:00 window. Participants who sleep outside those hours, such as shift workers or someone who regularly sleeps 02:00–11:00, will have these metrics computed from the wrong hours or not at all. You can move the window in config.yaml, but it is one fixed window applied to everybody.

Planned improvement: detect each participant's main sleep period from their own accelerometer data instead of assuming a clock window.

Activity cut-points come from older adults. The thresholds are from Etzkorn et al. (2024), derived in 381 adults with a median age of 78. Interpret cautiously in younger populations.

A note on HRV normalisation

This pipeline uses the natural logarithm of RMSSD to normalise HRV. This removes the mathematical influence of a person's average heart rate, allowing fairer comparisons. For a detailed explanation, see Should we normalize HRV by heart rate? by Marco Altini.

If something goes wrong 🔧

For developers 🛠️

Work from a clone rather than the released package:

git clone https://github.com/OxWearables/cardiac-prep.git

cd cardiac-prep && pip install -e ".[dev]"

pytest

Tests use synthetic data only, so no recordings or model weights are needed. GitHub Actions runs the tests and ruff check . on Python 3.9–3.12 for every push.

A clone also has process.py, summarise_dataset.py and plot_subject.py at the root, which run the same three subcommands without installing anything.

See the developer documentation for the layout, how the docs are built, and how releases are made.

Licence

Academic Use Licence, see LICENSE. Free for academic, non-commercial research and teaching. Commercial use requires a separate licence - contact Oxford University Innovation at enquiries@innovation.ox.ac.uk.

Copyright © 2026, University of Oxford.

Authors

• Stefan van Duijvenboden
• Anna Bator