Install and quickstart

physioKIT requires Python 3.12–3.14. Start in a Python project or virtual environment, then run the synthetic ECG example below. No external dataset is needed. If you already have a recording, begin here to check the installation, then move to Use your own data.

Installation

uv project

Create a project and add physioKIT. In an existing uv project, start with uv add physiokit.

uv init --python 3.12 my-physio-project
cd my-physio-project
uv add physiokit

pip

Install into an active virtual environment.

python -m pip install physiokit

After installation, check that your project can import the package. Use uv run python in a uv project or python in an activated virtual environment:

import physiokit as pk

print(pk.__version__)

Generate, clean, and measure ECG

This example produces a synthetic ECG, cleans it, finds R-peaks, and calculates heart rate variability measures. Run it in a notebook or Python script after installation.

Python

import physiokit as pk

sample_rate = 1000  # Hz
signal_length = 8 * sample_rate
ecg, segments, fiducials = pk.ecg.synthesize(
    signal_length=signal_length,
    sample_rate=sample_rate,
    heart_rate=64,
    leads=1,
)
ecg = ecg.squeeze()
clean = pk.ecg.clean(ecg, sample_rate=sample_rate)
peaks = pk.ecg.find_peaks(clean, sample_rate=sample_rate)
intervals = pk.ecg.compute_rr_intervals(peaks)
mask = pk.ecg.filter_rr_intervals(intervals, sample_rate=sample_rate)
hrv = pk.hrv.compute_hrv_time(intervals[mask == 0], sample_rate=sample_rate)
print(hrv)

The generator returns the waveform plus segmentation and fiducial arrays. This example uses the one-lead waveform. find_peaks returns positions in samples, compute_rr_intervals calculates the spacing between them in samples, and filter_rr_intervals marks intervals to exclude. The accepted intervals go to compute_hrv_time, which uses sample_rate to calculate time-domain HRV measures.

The following saved plot illustrates a cleaned synthetic ECG. The documentation build does not execute the example.

Where to go next

Try a different heart_rate in the generator, then compare the detected peak positions. To process a recording, follow Use your own data. The ECG guide shows more of the ECG workflow; the other signal guides cover PPG, respiration, motion, HRV, and shared utilities. The API Reference gives parameter and return-value details.

The plot source notebook generated the saved visuals. It contains data placeholders and is not a standalone quickstart.