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/rsp.md

Respiration

Checked 2026-10-01 against NeuroKit2 0.2.13 stable runtime/source, the official RSP API/examples, and cardiorespiratory interpretation guidance.

Acquisition contract and polarity

Record sensor type (belt, airflow, capnography, impedance, derived proxy), placement, gain/range, physical unit, native rate, clock, hardware filters, calibration, and annotations for speech, cough, sigh, breath hold, swallowing, movement, and detachment.

A belt/impedance amplitude is not tidal volume unless calibrated and validated. Different devices have opposite polarity. NeuroKit2's documented convention labels:

  • RSP_Peaks: exhalation onsets;
  • RSP_Troughs: inhalation onsets; and
  • RSP_Phase: 1 inspiration, 0 expiration.

Verify these labels against the actual device and a known breath. Invert or relabel explicitly before interpretation if needed.

Stable high-level pipeline

signals, info = nk.rsp_process(
    rsp,
    sampling_rate=50,
    method="khodadad2018",
    method_rvt="harrison2021",
)

Pinned default columns:

RSP_Raw, RSP_Clean, RSP_Amplitude, RSP_Rate, RSP_RVT,
RSP_Phase, RSP_Phase_Completion,
RSP_Symmetry_PeakTrough, RSP_Symmetry_RiseDecay,
RSP_Peaks, RSP_Troughs

info contained RSP_Peaks, RSP_Troughs, and sampling_rate. This is a default schema observation, not a universal contract.

Cleaning and extrema

clean = nk.rsp_clean(rsp, sampling_rate=50, method="khodadad2018")
markers, extrema = nk.rsp_peaks(
    clean,
    sampling_rate=50,
    method="khodadad2018",
)

Stable peak methods include khodadad2018, biosppy, scipy, and schafer2008. rsp_fixpeaks() is currently documented as a placeholder that does not correct respiration extrema.

Validate extrema during irregular breathing, pauses, speech, motion, and changing amplitude. A smooth sinusoidal simulation is not enough.

Rate, amplitude, and phase signatures

These functions do not all accept the same peak object:

rate = nk.rsp_rate(
    clean,
    troughs=extrema["RSP_Troughs"],
    sampling_rate=50,
    method="trough",
)
amplitude = nk.rsp_amplitude(
    clean,
    peaks=extrema["RSP_Peaks"],
    troughs=extrema["RSP_Troughs"],
)
phase = nk.rsp_phase(
    extrema["RSP_Peaks"],
    troughs=extrema["RSP_Troughs"],
    desired_length=len(clean),
)
  • rsp_rate() takes the cleaned signal first; method="trough" uses inhalation onsets, while method="xcorr" estimates a windowed principal rate.
  • rsp_amplitude() returns a same-length interpolated amplitude series.
  • rsp_phase() takes peaks/troughs, not the cleaned signal, and returns a DataFrame with phase and completion.

Rates are breaths/minute. Amplitude remains in the sensor's arbitrary/calibrated unit. Phase accuracy depends on extrema and polarity.

RRV and RAV

rrv = nk.rsp_rrv(
    signals["RSP_Rate"],
    troughs=info["RSP_Troughs"],
    sampling_rate=50,
)
rav = nk.rsp_rav(
    signals["RSP_Amplitude"],
    peaks=info,
)

The pinned rsp_rrv() output had 20 columns spanning interval, frequency, Poincaré, and entropy metrics (RRV_RMSSD through RRV_SampEn). The pinned RAV output had RAV_Mean, RAV_SD, RAV_RMSSD, and RAV_CVSD.

Do not interpret RRV/RAV from only a few breaths. Choose duration from the lowest frequency and nonlinear metric being estimated, and report breath count, usable duration, irregular-breath exclusions, and sensitivity. There is no universal “higher is healthier” interpretation.

Respiratory volume per time

Direct stable signature:

rsp_rvt(
  rsp_signal, sampling_rate=1000, method="power2020",
  boundaries=[2.0, 0.033333...], iterations=10, ...
)

Direct rsp_rvt() defaults to power2020, while rsp_process() defaults its method_rvt to harrison2021. Other stable option: birn2006.

rvt = nk.rsp_rvt(
    clean,
    sampling_rate=50,
    method="harrison2021",
)

RVT is a derived proxy/regressor. It is not calibrated respiratory volume or minute ventilation. For fMRI nuisance modeling, match the cited definition, acquisition, lag/convolution, resampling, and scanner preprocessing; do not treat one method as interchangeable with another.

Missing data and artifacts

Respiration signals commonly contain nonstationary physiology. Do not automatically classify sighs, pauses, speech, coughing, or swallowing as noise. Annotate them according to the research question.

  • Segment long gaps/detachment.
  • Do not interpolate across apnea-like pauses or speech and then compute rate.
  • Preserve raw/clean/extrema overlays.
  • Track filter and window edge validity.
  • Quantify missing breaths and altered intervals after exclusions.
  • Verify belt slippage and baseline drift separately from breathing depth.

Event and interval analysis

epochs = nk.epochs_create(
    signals,
    events,
    sampling_rate=50,
    epochs_start=-1,
    epochs_end=8,
    baseline_correction=False,
)
event_features = nk.rsp_eventrelated(epochs)
interval_features = nk.rsp_intervalrelated(signals, sampling_rate=50)

Event-related features are conditional and include rate/amplitude baselines and post-event summaries, phase/completion at onset, and RVT fields when present. Interval analysis can append RRV/RAV and inspiration/expiration duration features. Inspect the runtime schema.

Baseline subtraction is usually inappropriate for binary phase/peak columns. Prespecify which continuous features, if any, are baseline corrected.

RSA and alignment

For RSA, ECG and respiration need a shared clock and verified lag/drift:

rsa = nk.hrv_rsa(
    ecg_signals,
    rsp_signals,
    rpeaks=ecg_info,
    sampling_rate=common_rate,
    continuous=False,
)

Measure and report respiration; spontaneous or paced breathing changes the estimand. RSA can reflect cardiac vagal modulation under suitable conditions but is confounded by respiratory parameters, activity, posture, age, and adrenergic influence.

Interpretation boundary

Use this module for respiratory time-series research. It is not a validated system for apnea detection, capnography, tidal-volume measurement, respiratory diagnosis, biofeedback safety, patient/driver monitoring, or ventilatory control.

Sources checked 2026-10-01