General signal processing

Checked 2026-10-01 against NeuroKit2 0.2.13, its stable wheel, tagged source, and the live signal API page (0.2.13.dev214).

Start with a signal contract

For every channel retain:

• sensor/channel identity and physical unit;
• native sampling rate and timestamps;
• polarity, gain, acquisition filters, and ADC range;
• missing/discontinuous intervals and artifact annotations;
• expected physiological bandwidth; and
• the exact NeuroKit2 function, method, parameters, and package version.

signal_sanitize() does not clean artifacts or interpolate missing values. In 0.2.13 it resets an indexed pandas Series to a default index.

Safe preprocessing order

1. Preserve the original samples and time axis.
2. Check timestamp order, rate, clipping, flatlines, non-finite values, and gaps.
3. Split at long gaps. Interpolate only short, prespecified gaps and retain a mask.
4. Remove offsets/trends only when justified.
5. Apply a modality/method-specific filter at the native rate.
6. Trim or flag filter transients.
7. Detect/correct peaks or derive features.
8. Resample continuous outputs only when alignment or modeling requires it.

Do not use a filter to “fix” clipping, sensor detachment, dropped packets, or motion. Do not interpolate event markers, quality flags, or peak indicator vectors as continuous amplitudes.

Verified 0.2.13 interfaces

Never unpack signal_psd() into (psd, frequencies) in 0.2.13:

psd = nk.signal_psd(
    signal,
    sampling_rate=250,
    method="welch",
    normalize=False,
    show=False,
)
frequency_hz = psd["Frequency"]
power = psd["Power"]

normalize=True scales by maximum PSD power. It is not physical calibration. Use normalize=False when absolute spectral units are required and derive those units from the acquisition and estimator.

Filtering and resampling

Cutoffs are in Hz and must lie below Nyquist. Report:

• filter family and implementation (butterworth, FIR, Savitzky–Golay, powerline);
• order, low/high cutoff, notch frequency, and whether processing is zero phase;
• padding/edge handling and samples discarded; and
• source and target sampling rates plus resampling method.

Example:

filtered = nk.signal_filter(
    signal,
    sampling_rate=250,
    lowcut=0.5,
    highcut=40,
    method="butterworth",
    order=2,
)
resampled = nk.signal_resample(
    filtered,
    sampling_rate=250,
    desired_sampling_rate=100,
    method="poly",
)

Downsampling requires anti-alias filtering. In 0.2.13 the default interpolation method uses spline interpolation (scipy.ndimage.zoom), not an anti-alias low-pass filter. Use a suitable explicit filter before decimation or a validated filtered resampler such as poly; check attenuation above the new Nyquist frequency. Resampling cannot recover timing precision or bandwidth absent from the acquisition. For multimodal data, preserve native processing and timestamps first; choose a common grid only after clock alignment.

Missing data

Forward/backward fill can create artificial constant segments. Generic interpolation can create smooth but fictional morphology and peaks. Record:

• count and maximum run of missing samples;
• gap durations in seconds;
• whether each gap was segmented, excluded, padded, or interpolated;
• interpolation method and maximum allowed gap; and
• whether downstream quality and uncertainty include the imputed mask.

Most modality pipelines may warn and internally forward-fill some missing samples. That convenience is not a study-level missing-data policy.

Peak correction

info, corrected = nk.signal_fixpeaks(
    peaks,
    sampling_rate=250,
    method="Kubios",
    iterative=True,
)

The Kubios/Lipponen–Tarvainen path is intended for ECG/PPG beats. method="neurokit" supports explicit interval limits and can be used more generically. Always retain raw and corrected peaks, counts by artifact category, affected time ranges, and results with and without correction. Do not call corrected beat intervals “normal-to-normal” unless the study actually identifies non-sinus/ectopic beats.

Quality and reproducibility

Useful QC is multimodal and method-specific:

• raw/clean overlays and filter-edge review;
• missing, flatline, clipping, and saturation fractions;
• peak/onset overlays and interval distributions;
• quality values with their method-specific direction and scale;
• sensitivity to plausible filter/detector settings; and
• synthetic fixtures plus labeled empirical validation data.

The bundled inspector is dependency-free:

python skills/neurokit2/scripts/inspect_signal.py \
  --input signal.csv --root . --deidentified \
  --columns ECG --time-column time_s --units ECG=mV

Sources checked 2026-10-01

• Official signal API
• Stable v0.2.13 source tag
• NeuroKit2 main paper
• Lipponen & Tarvainen (2019), peak correction