AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

neurokit2

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.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--neurokit2 at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 13

references/epochs_events.md

Events and epochs

Checked 2026-10-01 against NeuroKit2 0.2.13 stable source/runtime and the live Events and Epochs API pages.

Event coordinate contract

Choose one canonical representation before analysis:

  • absolute time with a named clock and unit;
  • zero-based sample index on a named stream; and
  • event duration and condition/label metadata.

events_find() uses zero-based sample positions. Its start_at, end_at, duration_min, duration_max, and inter_min arguments are sample counts, not seconds.

events = nk.events_find(
    trigger,
    threshold=0.5,
    threshold_keep="above",
    duration_min=2,
    inter_min=5,
    event_conditions=["A", "B", "A"],
)

Stable signature:

events_find(
  event_channel, threshold="auto", threshold_keep="above",
  start_at=0, end_at=None, duration_min=1, duration_max=None,
  inter_min=0, discard_first=0, discard_last=0,
  event_labels=None, event_conditions=None
)

The default return is a dict containing onset, duration, and label; optional conditions use the singular key condition. Multi-channel input can add events_channel and generates conditions from the digital combination.

Do not infer trigger semantics from amplitude alone. Verify polarity, threshold, debouncing, pulse width, dropped triggers, device latency, and whether simultaneous digital inputs are encoded as expected.

Build events explicitly when possible

events = nk.events_create(
    event_onsets=[1000, 2500, 4000],
    event_durations=[100, 100, 100],
    event_labels=["1", "2", "3"],
    event_conditions=["A", "B", "A"],
)

Labels must be unique. Keep experimental trial IDs outside participant-identifying names.

epochs_create() semantics in 0.2.13

epochs_create(
  data, events=None, sampling_rate=1000,
  epochs_start=0, epochs_end="from_events",
  event_labels=None, event_conditions=None,
  baseline_correction=False
)
  • epochs_start and epochs_end are seconds relative to each event.
  • The data slice is [start_sample, end_sample) (end-exclusive).
  • Each epoch is a DataFrame in a dict keyed by label.
  • The original sample coordinate is stored in Index.
  • The DataFrame index is rebuilt with numpy.linspace(..., endpoint=True), so the displayed last index equals epochs_end even though the end sample is excluded.
  • Label and optional Condition are added as columns.
  • Events near a boundary are padded by internal buffers. Floating columns receive NaN; integer columns can receive zero because of dtype preservation.

The pinned probe for one signal, -0.2 to 0.5 s at 100 Hz, produced 70 rows with an index from exactly -0.2 through 0.5. Do not derive sample count from that floating index. Use Index, the known sampling rate, and explicit half-open bounds.

Boundary policy

Decide before analysis:

  • drop: remove incomplete trials and report condition-wise counts;
  • pad: retain them with an explicit validity mask; or
  • error: stop and repair event/window definitions.

Do not let NaN padding or integer zero padding silently become a physiological baseline. The dependency-free planner reports affected trials:

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

For events supplied in seconds, use --event-unit seconds; the planner rejects onsets/windows that do not map exactly to samples.

Baseline correction

baseline_correction=True subtracts the mean from epoch start through t=0 (inclusive in the rebuilt time index). If the epoch starts after zero, it uses the epoch start. The operation is applied broadly to numeric columns present at that point, including marker/index columns.

Prefer selective, manual correction:

epochs = nk.epochs_create(
    processed,
    events,
    sampling_rate=100,
    epochs_start=-0.2,
    epochs_end=0.8,
    baseline_correction=False,
)

amplitude_columns = ["EDA_Phasic"]
onsets_by_label = dict(zip(events["label"], events["onset"]))
for label, epoch in epochs.items():
    relative_samples = epoch["Index"] - onsets_by_label[label]
    baseline = epoch.loc[(relative_samples >= -20) & (relative_samples < 0), amplitude_columns]
    if len(baseline) != 20 or baseline.isna().any().any():
        raise ValueError("Incomplete or missing baseline; apply the trial exclusion policy")
    epoch.loc[:, amplitude_columns] = (
        epoch.loc[:, amplitude_columns] - baseline.mean()
    )

This uses original sample coordinates rather than the stretched floating time index. Prespecify baseline interval and estimand. Baseline subtraction is not universally appropriate for rates, binary peaks, phase, quality, or absolute tonic levels. Reject/flag a trial if its baseline has missing data or artifact rather than quietly using fewer samples.

Conversions

epochs_to_df() stacks epochs and adds a Time column; the stable probe observed Signal, Index, Label, Condition, and Time.

epochs_to_array() does not take a column argument in 0.2.13. Equal-length, single-signal epochs produced shape (time, epochs) in the pinned probe. Multiple signal columns add an intermediate dimension. Unequal epochs are not supported.

epochs_average() signature is:

epochs_average(epochs, which=None, indices=["mean", "std", "ci"], show=False)

For which="Signal", the pinned schema contained Time, Signal_Mean, Signal_SD, Signal_CI_low, and Signal_CI_high (plus a reset-index column). This is not a universal event-related feature schema.

Signal-specific analysis

Functions such as ecg_eventrelated(), eda_eventrelated(), rsp_eventrelated(), ppg_eventrelated(), emg_eventrelated(), and eog_eventrelated() inspect available processed columns. Their output changes when quality, phase, amplitude, condition, or trend columns are absent.

Use explicit dispatch:

ecg_features = nk.ecg_analyze(
    epochs, sampling_rate=100, method="event-related"
)

method="auto" chooses event-related analysis when mean duration is under 10 seconds. That software threshold is not scientific justification for a window or analysis.

Trial QC and statistics

Before averaging:

  1. inspect trigger detection against the raw marker channel;
  2. quantify boundary padding and missing baseline/post-event samples;
  3. apply modality-specific artifact rules without looking at condition outcomes;
  4. report retained trials per participant and condition;
  5. avoid threshold tuning on the same effects being tested; and
  6. model participant/trial hierarchy rather than treating epochs as independent.

There is no universal minimum number of trials or universal epoch window. Determine both from the expected response, acquisition, study design, reliability, and power analysis.

Sources checked 2026-10-01