@pikaa-ai/pikaa 0.3.23 → 0.3.25

package/skills/neurokit2/SKILL.md

@@ -1,323 +0,0 @@
----
-name: neurokit2
-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.
-license: MIT
-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.
-allowed-tools: Read Write Edit Bash Glob
-metadata:
-  version: "1.1"
-  skill-author: K-Dense Inc.
----
-
-# 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 tag `v0.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
-
-```bash
-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:
-
-1. signal identity and sensor/channel configuration;
-2. native sampling rate in Hz and physical unit (or explicitly `arbitrary_unit`);
-3. clock, timestamp origin, drift correction, and synchronization evidence;
-4. polarity/orientation and acquisition-side filters/gain;
-5. missing samples, discontinuities, saturation, flatlines, motion, and annotations;
-6. whether event onsets are zero-based sample indices or seconds;
-7. planned preprocessing order, methods, parameters, exclusions, and outputs; and
-8. 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
-
-```bash
-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:
-
-1. preserve immutable raw signal and annotations;
-2. verify time base, units, polarity, clipping, gaps, and artifacts;
-3. segment at long gaps; only interpolate short gaps under a declared policy;
-4. apply modality-specific cleaning at the native sampling rate;
-5. detect peaks/onsets or decompose components;
-6. inspect quality outputs and raw overlays;
-7. correct peaks only with logged categories and sensitivity checks;
-8. derive rates/features;
-9. align continuous modalities on a declared common time grid; and
-10. 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.
-
-```python
-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.
-
-```python
-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:
-
-```bash
-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:
-
-```python
-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`.
-
-```bash
-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.
-
-```python
-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:
-
-```bash
-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:
-
-```bash
-python skills/neurokit2/scripts/validate_multimodal.py \
-  --manifest streams.json --root . --deidentified
-```
-
-After independent modality QC and alignment:
-
-```python
-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:
-
-```python
-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:
-
-```bash
-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
-
-- [PyPI 0.2.13](https://pypi.org/project/neurokit2/)
-- [Official documentation](https://neuropsychology.github.io/NeuroKit/)
-- [API index](https://neuropsychology.github.io/NeuroKit/functions/index.html)
-- [GitHub releases](https://github.com/neuropsychology/NeuroKit/releases)
-- [Makowski et al. (2021), NeuroKit2](https://doi.org/10.3758/s13428-020-01516-y)
-- [Pham et al. (2021), HRV tutorial](https://doi.org/10.3390/s21123998)
-- [Makowski et al. (2022), complexity comparison](https://doi.org/10.3390/e24081036)
-- [SPR guideline index](https://sprweb.org/guidelines-papers)
-- [Quigley et al. (2024), HR/HRV guidelines](https://doi.org/10.1111/psyp.14604)