neurokit2
Use NeuroKit2 to build or audit reproducible research workflows for physiological time-series preprocessing, event/interval analysis, multimodal alignment, variability, and complexity. Trigger when code imports neurokit2 or needs its current APIs, schemas, and method-aware validation—not for diagnosis or device validation.
- License 许可
- MIT
- 最近更新
- 2026-10-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- neurokit2
- license
- MIT
- metadata
- { "version": "1.1", "skill-author": "K-Dense Inc." }
- description
- Use NeuroKit2 to build or audit reproducible research workflows for physiological time-series preprocessing, event/interval analysis, multimodal alignment, variability, and complexity. Trigger when code imports neurokit2 or needs its current APIs, schemas, and method-aware validation—not for diagnosis or device validation.
- allowed-tools
- Read Write Edit Bash Glob
- compatibility
- Python 3.10+ and uv; pinned workflows use NeuroKit2 0.2.13. Core processing needs NumPy, SciPy, pandas, scikit-learn, matplotlib, PyWavelets, requests, and setuptools; selected EEG, cvxEDA, plotting, file-format, and RQA features need separately locked optional packages.
02 资源文件 19
- 参考文档references/bio_module.md7.5 KB
- 参考文档references/complexity.md7.3 KB
- 参考文档references/ecg_cardiac.md6.7 KB
- 参考文档references/eda.md6.8 KB
- 参考文档references/eeg.md7.1 KB
- 参考文档references/emg.md5.6 KB
- 参考文档references/eog.md5.2 KB
- 参考文档references/epochs_events.md6.9 KB
- 参考文档references/hrv.md8.2 KB
- 参考文档references/ppg.md6.7 KB
- 参考文档references/rsp.md6.7 KB
- 参考文档references/signal_processing.md6.7 KB
- 脚本scripts/_common.py18.5 KB
- 脚本scripts/ecg_hrv_pipeline.py10.7 KB
- 脚本scripts/eda_pipeline.py9.8 KB
- 脚本scripts/generate_synthetic.py7.4 KB
- 脚本scripts/inspect_signal.py13.2 KB
- 脚本scripts/plan_epochs.py9.8 KB
- 脚本scripts/validate_multimodal.py12.2 KB
03 SKILL.md 正文
NeuroKit2
Scope and evidence cutoff
Use this skill for method-aware, reproducible biosignal research with NeuroKit2. The snapshot was checked on 2026-07-23 against:
- stable PyPI 0.2.13, released 2026-03-02;
- Python metadata (
>=3.10; classifiers 3.10–3.14) and wheel dependencies; - GitHub release notes/tags,
NEWS.rst, source at tagv0.2.13; - official API pages/examples (the live site identified itself as
0.2.13.dev214); and - pinned 0.2.13 runtime signatures and synthetic output schemas.
The live documentation can be ahead of the stable wheel. Prefer the pinned runtime for reproducible work and name both versions if consulting development docs.
Boundary
NeuroKit2 is a research and educational toolbox. Do not present its output as:
- a diagnosis, treatment recommendation, patient-monitoring decision, or alarm;
- validation, certification, or regulatory evidence for a medical device; or
- proof that a physiological construct is measured validly in a new sensor, protocol, environment, population, or disease group.
Validate acquisition hardware, electrode/optode placement, units, sampling and clock accuracy, preprocessing, detector/decomposition method, population, task, and outcomes for the intended study. Preserve raw data and an auditable exclusion log. Use deidentified local files only; do not place PHI in prompts, logs, examples, or bundled fixtures.
Reproducible installation
uv pip install "neurokit2==0.2.13"
For optional features, create a uv project, add only the packages actually required at
reviewed exact versions, and commit/review the resulting uv.lock before
uv sync --locked. NeuroKit2 exposes an upstream full extra, but this skill
intentionally does not install that floating transitive set in an automated workflow.
Optional capabilities can require MNE, cvxopt, Plotly, PyEMD, pyRQA, Pillow, OpenCV,
or file readers. Record the resolved environment with the analysis. Provision any MNE
data/template download as an explicit, checksummed study input. Do not install a moving
development branch for a reproducible study.
Required data contract
Before processing, record:
- signal identity and sensor/channel configuration;
- native sampling rate in Hz and physical unit (or explicitly
arbitrary_unit); - clock, timestamp origin, drift correction, and synchronization evidence;
- polarity/orientation and acquisition-side filters/gain;
- missing samples, discontinuities, saturation, flatlines, motion, and annotations;
- whether event onsets are zero-based sample indices or seconds;
- planned preprocessing order, methods, parameters, exclusions, and outputs; and
- participant-level grouping needed to prevent leakage in later statistics.
Never infer units from a column name. Do not silently treat samples as milliseconds, volts, microsiemens, or arbitrary units.
Core workflow
1. Inspect before transforming
python skills/neurokit2/scripts/inspect_signal.py \
--input recording.csv --root . --deidentified \
--columns ECG,RSP,EDA --time-column time_s \
--units ECG=mV,RSP=a.u.,EDA=uS
The inspector is bounded and emits no row values or paths. Resolve non-monotonic time, duplicate samples, gaps, non-finite values, flat runs, and sampling-rate disagreement before filtering.
2. Preserve preprocessing order
Use this default reasoning order, adapting it to the acquisition and cited method:
- preserve immutable raw signal and annotations;
- verify time base, units, polarity, clipping, gaps, and artifacts;
- segment at long gaps; only interpolate short gaps under a declared policy;
- apply modality-specific cleaning at the native sampling rate;
- detect peaks/onsets or decompose components;
- inspect quality outputs and raw overlays;
- correct peaks only with logged categories and sensitivity checks;
- derive rates/features;
- align continuous modalities on a declared common time grid; and
- map event indices to that grid, epoch, baseline, and analyze.
Do not resample binary markers or peak-index arrays as ordinary continuous signals. Map their timestamps to the target grid. Filtering and interpolation can create edge artifacts and false precision; retain masks for padded, missing, and rejected regions.
3. Treat schemas as runtime observations
Return columns depend on NeuroKit2 version, function, method, signal availability, and analysis mode. Never claim that one column list is universal.
signals, info = nk.ecg_process(ecg, sampling_rate=250)
observed_schema = {
"columns": list(signals.columns),
"info_keys": sorted(info),
}
Persist the observed schema with package version, method parameters, sampling rate, and quality/exclusion summary. Reference files list verified default schemas for 0.2.13, not guarantees for every method.
Current patterns
ECG, corrected peaks, and duration-aware HRV
In stable 0.2.13, ecg_process() performs cleaning, R-peak detection with
correct_artifacts=True, rate, default averageQRS quality, DWT delineation, and phase.
signals, info = nk.ecg_process(ecg, sampling_rate=250, method="neurokit")
time_hrv = nk.hrv_time(info, sampling_rate=250)
Inspect ECG_R_Peaks_Uncorrected and ECG_fixpeaks_*; a corrected series is not
automatically a valid NN series. For frequency/nonlinear HRV, enforce metric-specific
duration and beat-count requirements. Five minutes is the conventional short-term
reference; ULF is a long-recording measure, and VLF interpretation from short records
is unsafe. Do not interpret LF/HF as a direct sympathovagal balance. PPG pulse-rate
variability is not interchangeable with ECG HRV.
Use the bounded pipeline:
python skills/neurokit2/scripts/ecg_hrv_pipeline.py \
--synthetic --sampling-rate 250 --duration 300 \
--domains time,frequency,nonlinear
EDA with explicit decomposition
The stable default eda_process(method="neurokit") uses high-pass tonic/phasic
decomposition, not cvxEDA. Choose and report decomposition explicitly:
clean = nk.eda_clean(eda, sampling_rate=100, method="neurokit")
components = nk.eda_phasic(clean, sampling_rate=100, method="highpass")
markers, info = nk.eda_peaks(
components["EDA_Phasic"],
sampling_rate=100,
method="neurokit",
amplitude_min=0.1,
)
For neurokit/kim2004, amplitude_min is relative to the largest detected response;
it is not an absolute microsiemens threshold. cvxEDA needs optional cvxopt.
python skills/neurokit2/scripts/eda_pipeline.py \
--synthetic --sampling-rate 100 --duration 60 \
--phasic-method highpass --peak-method neurokit
Events, epochs, and baseline
events_find() reports zero-based sample onsets; duration/spacing arguments are in
samples. epochs_create() takes epoch limits in seconds.
events = nk.events_find(trigger, threshold=0.5, duration_min=2)
epochs = nk.epochs_create(
signals,
events,
sampling_rate=100,
epochs_start=-0.2,
epochs_end=0.8,
baseline_correction=False,
)
Plan sample-exact windows first:
python skills/neurokit2/scripts/plan_epochs.py \
--events 1000,2500,4000 --event-unit samples \
--sampling-rate 100 --recording-samples 5000 \
--epoch-start -0.2 --epoch-end 0.8 \
--baseline-start -0.2 --baseline-end 0
In 0.2.13 the epoch slice is end-exclusive, but the generated floating time index
includes epochs_end. Built-in baseline correction subtracts the epoch mean from its
start through t=0; use manual correction for a narrower prespecified baseline.
Boundary epochs are padded and can contain NaN. Decide drop/pad/error before analysis.
RSA and multimodal processing
bio_process() assumes all inputs already share one sampling rate and alignment. It
does not resample, synchronize, estimate drift, or create nested modality dictionaries;
its info output is flat. Unequal lengths are concatenated by index and can introduce
NaN. RSA is added only when synchronized ECG and RSP are present.
Validate a strict local manifest before calling it:
python skills/neurokit2/scripts/validate_multimodal.py \
--manifest streams.json --root . --deidentified
After independent modality QC and alignment:
bio_signals, bio_info = nk.bio_process(
ecg=ecg_aligned,
rsp=rsp_aligned,
eda=eda_aligned,
sampling_rate=common_rate,
)
rsa_summary = nk.hrv_rsa(
bio_signals,
bio_signals,
rpeaks=bio_info,
sampling_rate=common_rate,
continuous=False,
)
Summary RSA is a dictionary; continuous=True returns a DataFrame with RSA_P2T and
RSA_Gates in the verified default workflow. Co-record respiration and report its
rate/depth/context; RSA is not a direct, context-free measure of vagal tone.
Complexity returns values plus metadata
Most complexity functions in 0.2.13 return (value, info). The convenience function
also returns two objects:
features, details = nk.complexity(signal) # default which="makowski2022"
sampen, sampen_info = nk.entropy_sample(signal)
dfa, dfa_info = nk.fractal_dfa(signal)
The default convenience selection is not “all measures.” Complexity estimates are sensitive to length, stationarity, normalization, delay, dimension, tolerance, scale, and implementation. Predefine them and run sensitivity/surrogate analyses.
Bundled command-line helpers
All helpers reject URLs, path traversal, and symlinks; bound bytes/rows/channels; refuse
overwrite unless --force; use lazy scientific imports so --help works without
NeuroKit2; never use pickle; and produce deterministic JSON/CSV. Real-data commands
require --deidentified.
| Helper | Purpose |
|---|---|
scripts/generate_synthetic.py |
Dependency-free deterministic CSV fixtures |
scripts/inspect_signal.py |
Bounded CSV/time/gap/flatline inspection |
scripts/ecg_hrv_pipeline.py |
Pinned ECG, quality, peak-correction, HRV workflow |
scripts/eda_pipeline.py |
Explicit cleaning, decomposition, SCR workflow |
scripts/plan_epochs.py |
Sample-exact event, boundary, baseline planner |
scripts/validate_multimodal.py |
Strict units/rates/clocks/alignment schema validator |
Generate a fixture without exposing participant data:
python skills/neurokit2/scripts/generate_synthetic.py \
--output synthetic.csv --root . --duration 30 \
--sampling-rate 250 --seed 42
Security note
No example or helper uses Python eval() or exec(). NeuroKit2 names such as
eeg_*, events_*, and *_eventrelated() are ordinary library calls. If a static
scanner reports an eval/exec pattern based on a substring, inspect the exact line and
record it as a scanner false positive only after confirming no dynamic execution exists.
References
Read only the files needed for the modality or decision:
All bundled Markdown paths below are under references/; this skill has no
templates/ or assets/ reference paths.
| File | Contents |
|---|---|
references/signal_processing.md |
Filters, gaps, resampling, peaks, PSD, schemas |
references/epochs_events.md |
Event indexing, epoch boundaries, baselines |
references/ecg_cardiac.md |
ECG process, quality, delineation, peak correction |
references/hrv.md |
HRV/RSA inputs, duration, ectopy, interpretation |
references/eda.md |
Cleaning, decomposition, SCR detection |
references/emg.md |
EMG cleaning, amplitude, activation |
references/eog.md |
EOG polarity, MNE default, blink features |
references/eeg.md |
EEG/MNE helpers, power, QC, microstates |
references/ppg.md |
PPG methods, quality semantics, PRV limitations |
references/rsp.md |
Respiration polarity, rate, RRV/RVT/RAV |
references/bio_module.md |
Multimodal alignment and bio_* schemas |
references/complexity.md |
Tuple returns, parameter sensitivity, RQA |
Primary sources checked 2026-07-23
04 同仓库更多 Skills
zarr-python
Chunked N-D arrays for cloud storage (Zarr-Python 3). Compressed arrays, parallel I/O, S3/GCS via fsspec, NumPy/Dask/Xarray compatible, for large-scale scientific computing pipelines.
video-use
Edit any video by conversation. Transcribe, cut, color grade, generate overlay animations, burn subtitles — for talking heads, montages, tutorials, travel, interviews. No presets, no menus. Ask questions, confirm the plan, execute, iterate, persist. Production-correctness rules are hard; everything else is artistic freedom.
venue-templates
Prepare journal manuscripts, conference papers, research posters, and grant documents using venue-specific formatting guidance and bundled LaTeX scaffolds. Use when selecting an official template, checking current page or anonymity rules, adapting academic writing to a venue, or inspecting a submission PDF.
vaex
Use this skill for processing and analyzing large tabular datasets (billions of rows) that exceed available RAM. Vaex excels at out-of-core DataFrame operations, lazy evaluation, fast aggregations, efficient visualization of big data, and machine learning on large datasets. Apply when users need to work with large CSV/HDF5/Arrow/Parquet files, perform fast statistics on massive datasets, create visualizations of big data, or build ML pipelines that do not fit in memory.
usfiscaldata
Query the U.S. Treasury Fiscal Data REST API for federal financial data. No API key required. Use for national debt (Debt to the Penny), Daily Treasury Statements, Monthly Treasury Statements, Treasury securities auctions, interest rates, foreign exchange rates, savings bonds, or U.S. government revenue and spending statistics.
uncertainty-and-units
Track physical units and propagate measurement uncertainty in scientific calculations using pint and uncertainties. Use for unit conversion and dimensional checking, GUM uncertainty budgets, Type A and Type B evaluation, coverage factors and expanded uncertainty, Monte Carlo propagation, significant-figure and plus-minus reporting, error propagation through curve fits, CODATA constants, auditing Python code for stripped units or broken uncertainty propagation, and order-of-magnitude plausibility checks using dimensionless groups (Reynolds, Peclet, Damkohler, Knudsen, Biot, Womersley), characteristic scales such as diffusion time or Debye length, and observed magnitude ranges. Trigger on "is this number physically reasonable", "sanity check these units", "what regime is this flow in", or a result that looks off by orders of magnitude.