Alterlab Neurokit2

NeuroKit2

Overview

NeuroKit2 is a comprehensive Python toolkit for processing and analyzing physiological signals (biosignals). Use this skill to process cardiovascular, neural, autonomic, respiratory, and muscular signals for psychophysiology research, clinical applications, and human-computer interaction studies.

When to Use This Skill

Apply this skill when working with:

• Cardiac signals: ECG, PPG, heart rate variability (HRV), pulse analysis
• Brain signals: EEG frequency bands, microstates, complexity, source localization
• Autonomic signals: Electrodermal activity (EDA/GSR), skin conductance responses (SCR)
• Respiratory signals: Breathing rate, respiratory variability (RRV), volume per time
• Muscular signals: EMG amplitude, muscle activation detection
• Eye tracking: EOG, blink detection and analysis
• Multi-modal integration: Processing multiple physiological signals simultaneously
• Complexity analysis: Entropy measures, fractal dimensions, nonlinear dynamics

Does NOT Trigger

Core Capabilities

1. Cardiac Signal Processing (ECG/PPG)

Process electrocardiogram and photoplethysmography signals for cardiovascular analysis. See references/ecg_cardiac.md for detailed workflows.

Primary workflows:

• ECG processing pipeline: cleaning → R-peak detection → delineation → quality assessment
• HRV analysis across time, frequency, and nonlinear domains
• PPG pulse analysis and quality assessment
• ECG-derived respiration extraction

Key functions:

pythonCopy code
import neurokit2 as nk

# Complete ECG processing pipeline
signals, info = nk.ecg_process(ecg_signal, sampling_rate=1000)

# Analyze ECG data (event-related or interval-related)
analysis = nk.ecg_analyze(signals, sampling_rate=1000)

# Comprehensive HRV analysis
hrv = nk.hrv(peaks, sampling_rate=1000)  # Time, frequency, nonlinear domains

2. Heart Rate Variability Analysis

Compute comprehensive HRV metrics from cardiac signals. See references/hrv.md for all indices and domain-specific analysis.

Supported domains:

• Time domain: SDNN, RMSSD, pNN50, SDSD, and derived metrics
• Frequency domain: ULF, VLF, LF, HF, VHF power and ratios
• Nonlinear domain: Poincaré plot (SD1/SD2), entropy measures, fractal dimensions
• Specialized: Respiratory sinus arrhythmia (RSA), recurrence quantification analysis (RQA)

Key functions:

pythonCopy code
# All HRV indices at once
hrv_indices = nk.hrv(peaks, sampling_rate=1000)

# Domain-specific analysis
hrv_time = nk.hrv_time(peaks)
hrv_freq = nk.hrv_frequency(peaks, sampling_rate=1000)
hrv_nonlinear = nk.hrv_nonlinear(peaks, sampling_rate=1000)
# hrv_rsa takes the *processed* ECG and RSP signal DataFrames (from ecg_process/rsp_process,
# not raw arrays or bare peaks); pass R-peak indices via rpeaks=. See references/hrv.md.
hrv_rsa = nk.hrv_rsa(ecg_signals, rsp_signals=rsp_signals,
                     rpeaks=info['ECG_R_Peaks'], sampling_rate=1000)

3. Brain Signal Analysis (EEG)

Analyze electroencephalography signals for frequency power, complexity, and microstate patterns. See references/eeg.md for detailed workflows and MNE integration.

Primary capabilities:

• Frequency band power analysis (Delta, Theta, Alpha, Beta, Gamma)
• Channel quality assessment and re-referencing
• Source localization (sLORETA, MNE)
• Microstate segmentation and transition dynamics
• Global field power and dissimilarity measures

Key functions:

pythonCopy code
# Power analysis across frequency bands (returns power per channel × band).
# Select/subset channels upstream on the MNE Raw or array; eeg_power has no `channels` arg.
power = nk.eeg_power(eeg_data, sampling_rate=250)

# Microstate analysis (sampling_rate is required for the default train='gfp' path)
microstates = nk.microstates_segment(eeg_data, n_microstates=4, method='kmod',
                                     sampling_rate=250)
static = nk.microstates_static(microstates, sampling_rate=250)
dynamic = nk.microstates_dynamic(microstates)

4. Electrodermal Activity (EDA)

Process skin conductance signals for autonomic nervous system assessment. See references/eda.md for detailed workflows.

Primary workflows:

• Signal decomposition into tonic and phasic components
• Skin conductance response (SCR) detection and analysis
• Sympathetic nervous system index calculation
• Autocorrelation and changepoint detection

Key functions:

pythonCopy code
# Complete EDA processing
signals, info = nk.eda_process(eda_signal, sampling_rate=100)

# Analyze EDA data
analysis = nk.eda_analyze(signals, sampling_rate=100)

# Sympathetic nervous system activity: pass the EDA vector (raw or signals["EDA_Clean"]),
# not the processed DataFrame; the default 'posada' method needs > 64 s of signal
sympathetic = nk.eda_sympathetic(eda_signal, sampling_rate=100)

5. Respiratory Signal Processing (RSP)

Analyze breathing patterns and respiratory variability. See references/rsp.md for detailed workflows.

Primary capabilities:

• Respiratory rate calculation and variability analysis
• Breathing amplitude and symmetry assessment
• Respiratory volume per time (fMRI applications)
• Respiratory amplitude variability (RAV)

Key functions:

pythonCopy code
# Complete RSP processing
signals, info = nk.rsp_process(rsp_signal, sampling_rate=100)

# Respiratory rate variability (accepts the processed DataFrame)
rrv = nk.rsp_rrv(signals, sampling_rate=100)

# Respiratory volume per time: rsp_process already adds an "RSP_RVT" column;
# to recompute, pass the 1-D respiration vector (a DataFrame raises ValueError)
rvt = nk.rsp_rvt(rsp_signal, sampling_rate=100)

6. Electromyography (EMG)

Process muscle activity signals for activation detection and amplitude analysis. See references/emg.md for workflows.

Key functions:

pythonCopy code
# Complete EMG processing (adds EMG_Amplitude, EMG_Activity, EMG_Onsets, EMG_Offsets)
signals, info = nk.emg_process(emg_signal, sampling_rate=1000)

# Re-run activation detection with other settings: pass the amplitude vector, not the DataFrame
activity, activation_info = nk.emg_activation(
    emg_amplitude=signals["EMG_Amplitude"], sampling_rate=1000, method="threshold"
)

7. Electrooculography (EOG)

Analyze eye movement and blink patterns. See references/eog.md for workflows.

Key functions:

pythonCopy code
# Complete EOG processing. Blink detection defaults to method="mne" (requires
# `uv pip install mne`); method="neurokit" avoids the MNE dependency
signals, info = nk.eog_process(eog_signal, sampling_rate=500, method="neurokit")

# Extract blink features: needs the cleaned signal and the blink peak indices
features = nk.eog_features(signals["EOG_Clean"], info["EOG_Blinks"], sampling_rate=500)

8. General Signal Processing

Apply filtering, decomposition, and transformation operations to any signal. See references/signal_processing.md for comprehensive utilities.

Key operations:

• Filtering (lowpass, highpass, bandpass, bandstop)
• Decomposition (EMD, SSA, wavelet)
• Peak detection and correction
• Power spectral density estimation
• Signal interpolation and resampling
• Autocorrelation and synchrony analysis

Key functions:

pythonCopy code
# Filtering
filtered = nk.signal_filter(signal, sampling_rate=1000, lowcut=0.5, highcut=40)

# Peak detection
peaks = nk.signal_findpeaks(signal)

# Power spectral density
psd = nk.signal_psd(signal, sampling_rate=1000)

9. Complexity and Entropy Analysis

Compute nonlinear dynamics, fractal dimensions, and information-theoretic measures. See references/complexity.md for all available metrics.

Available measures:

• Entropy: Shannon, approximate, sample, permutation, spectral, fuzzy, multiscale
• Fractal dimensions: Katz, Higuchi, Petrosian, Sevcik, correlation dimension
• Nonlinear dynamics: Lyapunov exponents, Lempel-Ziv complexity, recurrence quantification
• DFA: Detrended fluctuation analysis, multifractal DFA
• Information theory: Fisher information, mutual information

Key functions:

pythonCopy code
# Multiple complexity metrics at once (note: complexity() takes no sampling_rate)
complexity_indices, info = nk.complexity(signal)

# Specific measures: entropy_*, fractal_*, and complexity_* functions return a
# (value, info) tuple, so unpack them
apen, _ = nk.entropy_approximate(signal)
dfa, _ = nk.fractal_dfa(signal)
lle, _ = nk.complexity_lyapunov(signal, delay=1, dimension=2)

10. Event-Related Analysis

Create epochs around stimulus events and analyze physiological responses. See references/epochs_events.md for workflows.

Primary capabilities:

• Epoch creation from event markers
• Event-related averaging and visualization
• Baseline correction options
• Grand average computation with confidence intervals

Key functions:

pythonCopy code
# Find events in signal
events = nk.events_find(trigger_signal, threshold=0.5)

# Create epochs around events
epochs = nk.epochs_create(signals, events, sampling_rate=1000,
                          epochs_start=-0.5, epochs_end=2.0)

# Average across epochs
grand_average = nk.epochs_average(epochs)

11. Multi-Signal Integration

Process multiple physiological signals simultaneously with unified output. See references/bio_module.md for integration workflows.

Key functions:

pythonCopy code
# Process multiple signals at once
bio_signals, bio_info = nk.bio_process(
    ecg=ecg_signal,
    rsp=rsp_signal,
    eda=eda_signal,
    emg=emg_signal,
    sampling_rate=1000
)

# Analyze all processed signals
bio_analysis = nk.bio_analyze(bio_signals, sampling_rate=1000)

Analysis Modes

NeuroKit2 automatically selects between two analysis modes based on data duration:

Event-related analysis (< 10 seconds):

• Analyzes stimulus-locked responses
• Epoch-based segmentation
• Suitable for experimental paradigms with discrete trials

Interval-related analysis (≥ 10 seconds):

• Characterizes physiological patterns over extended periods
• Resting state or continuous activities
• Suitable for baseline measurements and long-term monitoring

Most *_analyze() functions automatically choose the appropriate mode.

Installation

bashCopy code
uv pip install neurokit2

Function signatures in this skill are verified against neurokit2 0.2.13 (current release as of 2026-09; requires Python >= 3.10). If you need a reproducible env, pin it: uv pip install "neurokit2==0.2.13". EEG helpers (mne_*, source localization) and the default EOG blink detector also need MNE-Python: uv pip install mne.

For development version:

bashCopy code
uv pip install https://github.com/neuropsychology/NeuroKit/zipball/dev

Common Workflows

Quick Start: ECG Analysis

pythonCopy code
import neurokit2 as nk

# Load example data
ecg = nk.ecg_simulate(duration=60, sampling_rate=1000)

# Process ECG
signals, info = nk.ecg_process(ecg, sampling_rate=1000)

# Analyze HRV
hrv = nk.hrv(info['ECG_R_Peaks'], sampling_rate=1000)

# Visualize
nk.ecg_plot(signals, info)

Multi-Modal Analysis

pythonCopy code
# Process multiple signals
bio_signals, bio_info = nk.bio_process(
    ecg=ecg_signal,
    rsp=rsp_signal,
    eda=eda_signal,
    sampling_rate=1000
)

# Analyze all signals
results = nk.bio_analyze(bio_signals, sampling_rate=1000)

Event-Related Potential

pythonCopy code
# Find events
events = nk.events_find(trigger_channel, threshold=0.5)

# Create epochs
epochs = nk.epochs_create(processed_signals, events,
                          sampling_rate=1000,
                          epochs_start=-0.5, epochs_end=2.0)

# Event-related analysis for each signal type
ecg_epochs = nk.ecg_eventrelated(epochs)
eda_epochs = nk.eda_eventrelated(epochs)

References

This skill includes comprehensive reference documentation organized by signal type and analysis method:

• ecg_cardiac.md: ECG/PPG processing, R-peak detection, delineation, quality assessment
• hrv.md: Heart rate variability indices across all domains
• eeg.md: EEG analysis, frequency bands, microstates, source localization
• eda.md: Electrodermal activity processing and SCR analysis
• rsp.md: Respiratory signal processing and variability
• ppg.md: Photoplethysmography signal analysis
• emg.md: Electromyography processing and activation detection
• eog.md: Electrooculography and blink analysis
• signal_processing.md: General signal utilities and transformations
• complexity.md: Entropy, fractal, and nonlinear measures
• epochs_events.md: Event-related analysis and epoch creation
• bio_module.md: Multi-signal integration workflows

Load specific reference files as needed using the Read tool to access detailed function documentation and parameters.

Additional Resources

• Official Documentation: https://neuropsychology.github.io/NeuroKit/
• GitHub Repository: https://github.com/neuropsychology/NeuroKit
• Publication: Makowski et al. (2021). NeuroKit2: A Python toolbox for neurophysiological signal processing. Behavior Research Methods. https://doi.org/10.3758/s13428-020-01516-y

Part of the AlterLab Academic Skills suite.