domains / science / biosignal-processing / neurokit2

neurokit2

Skill card

combined

The copies diverge significantly in scope and rigor. The K-Dense-AI copy is a strict, reproducible research protocol that pins versions (0.2.13), enforces a specific data contract, and includes safety boundaries against medical diagnosis. The other copies (Vibe-Skills, OpenClaw, aipoch) are broader 'toolkit' guides that list capabilities and provide general code examples without the rigorous version pinning or safety constraints. Combining them is necessary to capture both the rigorous research workflow and the broader functional capabilities (like specific EEG/EMG/EOG functions) that the rigorous copy omits or truncates.

Repositories

Other copies

Combined skill

---
name: neurokit2
description: Builds and audits reproducible NeuroKit2 research workflows for physiological time-series preprocessing, event/interval analysis, multimodal alignment, variability, and complexity. Use when code imports neurokit2 or needs its current APIs, schemas, and method-aware validation—not for diagnosis or device validation.
license: MIT
compatibility: Python 3.10+ and uv; pinned workflows use NeuroKit2 0.2.13.
---

# NeuroKit2

## Scope and Safety Boundary

Use this skill for method-aware, reproducible biosignal research with NeuroKit2. 

**Do NOT present its output as:**
- A diagnosis, treatment recommendation, or patient-monitoring decision.
- Validation or regulatory evidence for a medical device.
- Proof that a physiological construct is validly measured in a new context.

Validate acquisition hardware, units, and preprocessing for the intended study. Preserve raw data and an auditable exclusion log.

## Reproducible Installation

For reproducible research, pin the version:
```bash
uv pip install "neurokit2==0.2.13"
```

For exploratory work or if specific new features are required, you may install the latest stable version, but record the exact version used:
```bash
uv pip install neurokit2
```

## Required Data Contract

Before processing, record:
1. Signal identity and sensor/channel configuration.
2. Native sampling rate (Hz) and physical unit.
3. Clock, timestamp origin, and synchronization evidence.
4. Polarity/orientation and acquisition-side filters.
5. Missing samples, discontinuities, and artifacts.
6. Event onset format (sample indices or seconds).
7. Planned preprocessing order and exclusions.

Never infer units from column names.

## Core Workflow

### 1. Inspect Before Transforming

Check for non-monotonic time, duplicate samples, gaps, and non-finite values before filtering.

### 2. Processing Pipelines

Most modalities follow a consistent structure:
1. `*_process(signal, sampling_rate=...)`: Produces cleaned signal and intermediate channels (peaks, phases) plus an `info` dict.
2. `*_analyze(processed_signals, sampling_rate=...)`: Computes summary features.

**Key Modalities:**

#### Cardiac (ECG/PPG)
```python
import neurokit2 as nk

# ECG Processing
signals, info = nk.ecg_process(ecg_signal, sampling_rate=1000)

# HRV Analysis (Time, Frequency, Nonlinear)
hrv = nk.hrv(info["ECG_R_Peaks"], sampling_rate=1000)
```

#### Electrodermal Activity (EDA)
```python
# EDA Processing (Tonic/Phasic decomposition)
signals, info = nk.eda_process(eda_signal, sampling_rate=100)

# Sympathetic Nervous System Index
sympathetic = nk.eda_sympathetic(signals, sampling_rate=100)
```

#### Respiratory (RSP)
```python
# RSP Processing
signals, info = nk.rsp_process(rsp_signal, sampling_rate=100)

# Respiratory Rate Variability
rrv = nk.rsp_rrv(signals, sampling_rate=100)
```

#### EEG (Brain Signals)
```python
# Power Analysis
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')
```

#### EMG and EOG
```python
# EMG Processing
signals, info = nk.emg_process(emg_signal, sampling_rate=1000)

# EOG Processing
signals, info = nk.eog_process(eog_signal, sampling_rate=1000)
```

### 3. Multimodal Integration

Use `bio_process` and `bio_analyze` for consistent multi-signal pipelines:

```python
bio_signals, bio_info = nk.bio_process(
    ecg=ecg,
    rsp=rsp,
    eda=eda,
    sampling_rate=1000
)
bio_results = nk.bio_analyze(bio_signals, sampling_rate=1000)
```

### 4. Event-Related Analysis

For stimulus-locked responses:

```python
# Detect events
events = nk.events_find(trigger, threshold=0.5)

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

# Grand average
grand_average = nk.epochs_average(epochs)
```

## Schema and Validation

Return columns depend on the NeuroKit2 version and method. Persist the observed schema with package version and parameters:

```python
observed_schema = {
    "columns": list(signals.columns),
    "info_keys": sorted(info),
    "version": nk.__version__
}
```