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 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:
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
- 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:
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 = nk.hrv_rsa(peaks, rsp_signal, sampling_rate=1000)
- 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:
Power analysis across frequency bands
power = nk.eeg_power(eeg_data, sampling_rate=250, channels=['Fz', 'Cz', 'Pz'])
Microstate analysis
microstates = nk.microstates_segment(eeg_data, n_microstates=4, method='kmod') static = nk.microstates_static(microstates) dynamic = nk.microstates_dynamic(microstates)
- 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:
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
sympathetic = nk.eda_sympathetic(signals, sampling_rate=100)
- 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:
Complete RSP processing
signals, info = nk.rsp_process(rsp_signal, sampling_rate=100)
Respiratory rate variability
rrv = nk.rsp_rrv(signals, sampling_rate=100)
Respiratory volume per time
rvt = nk.rsp_rvt(signals, sampling_rate=100)
- Electromyography (EMG)
Process muscle activity signals for activation detection and amplitude analysis. See references/emg.md for workflows.
Key functions:
Complete EMG processing
signals, info = nk.emg_process(emg_signal, sampling_rate=1000)
Muscle activation detection
activation = nk.emg_activation(signals, sampling_rate=1000, method='threshold')
- Electrooculography (EOG)
Analyze eye movement and blink patterns. See references/eog.md for workflows.
Key functions:
Complete EOG processing
signals, info = nk.eog_process(eog_signal, sampling_rate=500)
Extract blink features
features = nk.eog_features(signals, sampling_rate=500)
- 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:
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)
- 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:
Multiple complexity metrics at once
complexity_indices = nk.complexity(signal, sampling_rate=1000)
Specific measures
apen = nk.entropy_approximate(signal) dfa = nk.fractal_dfa(signal) lyap = nk.complexity_lyapunov(signal, sampling_rate=1000)
- 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:
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)
- Multi-Signal Integration
Process multiple physiological signals simultaneously with unified output. See references/bio_module.md for integration workflows.
Key functions:
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 uv pip install neurokit2
For development version:
uv pip install https://github.com/neuropsychology/NeuroKit/zipball/dev
Common Workflows Quick Start: ECG Analysis 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
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
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