NeuroKit2

0.2.13 verified Fri May 01 auth: no python

NeuroKit2 is a Python toolbox for neurophysiological signal processing (ECG, PPG, EDA, EMG, RSP, etc.). It provides end-to-end pipelines for cleaning, processing, and analyzing biosignals. The current version is 0.2.13, released in early 2025. The project is actively maintained with frequent releases.

pip install neurokit2

Common errors

error ModuleNotFoundError: No module named 'neurokit2' ↓

cause NeuroKit2 is not installed or installed as a different package name.

fix

Run pip install neurokit2 (note: all lowercase, no spaces).

error AttributeError: module 'neurokit2' has no attribute 'ecg_simulate' ↓

cause Function name typo or outdated version; 'ecg_simulate' is correct.

fix

Use nk.ecg_simulate(). Check version: pip show neurokit2 should be >=0.2.0.

error ValueError: cannot convert float NaN to integer ↓

cause Some algorithms may produce NaN values (e.g., when signal is too short).

fix

Ensure the signal length is sufficient for the method. Check that sampling_rate matches the actual sample rate.

error TypeError: ecg_process() got an unexpected keyword argument 'sampling_rate' ↓

cause Older version of NeuroKit2 may not support `sampling_rate` parameter in `ecg_process()`.

fix

Update to latest version: pip install --upgrade neurokit2.

Warnings

breaking In version 0.2.6, the `*_plot()` methods no longer accept `sampling_rate` as a separate argument; it must be provided via the plotting function's parameters. ↓

fix Use `nk.ecg_plot(signals, info, sampling_rate=100)` instead of passing `sampling_rate` to `ecg_plot` itself.

breaking In version 0.2.5, `ecg_clean()` updated the 'biosppy' method, which may produce slightly different cleaned signals. ↓

fix If you rely on exact previous output, specify an older method or adjust post-processing.

gotcha Many functions expect the signal to be a 1D array. Passing a 2D array (e.g., from pandas DataFrame) can cause silent errors or wrong results. ↓

fix Always flatten or select a single column: `ecg_signal = df['ECG'].values.flatten()`.

gotcha The `ecg_process()` function returns a tuple (signals, info). The `signals` DataFrame includes multiple channels (ECG_Clean, ECG_Rate, etc.). The `info` dict contains peak indices and other metadata. Confusing these two can lead to incorrect analysis. ↓

fix Confirm you are using the correct return: `signals` for derived time series, `info` for peak locations and parameters.

Imports

NeuroKit2
wrong
```
from neurokit2 import NeuroKit2
```
correct
```
import neurokit2 as nk
```
NeuroKit2 is commonly imported as nk, not as a class. Never import 'NeuroKit2' directly.
ecg_process
wrong
```
from neurokit2 import ecg_process
```
correct
```
import neurokit2 as nk; nk.ecg_process()
```
All functions are accessed via the 'nk' namespace, not imported directly.

Quickstart

Simulate ECG signal, process it, and compute heart rate.

import neurokit2 as nk
import numpy as np

# Simulate 5 seconds of ECG signal at 100 Hz
sampling_rate = 100
ecg_signal = nk.ecg_simulate(duration=5, sampling_rate=sampling_rate, noise=0.01)

# Process the signal
signals, info = nk.ecg_process(ecg_signal, sampling_rate=sampling_rate)

# Extract heart rate
hr = nk.ecg_rate(info, sampling_rate=sampling_rate)
print("Heart rate (BPM):", np.mean(hr))