Ruview/v2/crates/ruv-neural/ruv-neural-signal

ruv-neural-signal

Signal processing: filtering, spectral analysis, connectivity metrics, and artifact rejection for neural time series data.

Overview

ruv-neural-signal provides a complete digital signal processing pipeline for multi-channel neural magnetic field and electrophysiology data. It covers IIR filtering in second-order sections form, FFT-based spectral analysis, Hilbert transform for instantaneous phase extraction, artifact detection and rejection, cross-channel connectivity metrics, and a configurable multi-stage preprocessing pipeline.

Features

• IIR Filters (filter): Butterworth bandpass, highpass, lowpass, and notch filters in SOS (second-order sections) form for numerical stability
• Spectral analysis (spectral): Welch PSD estimation, STFT, band power extraction, spectral entropy, and peak frequency detection
• Hilbert transform (hilbert): FFT-based analytic signal for instantaneous phase and amplitude envelope computation
• Artifact detection (artifact): Eye blink, muscle artifact, and cardiac artifact detection with configurable rejection
• Connectivity metrics (connectivity): Phase locking value (PLV), coherence, imaginary coherence, amplitude envelope correlation (AEC), and all-pairs computation for connectivity matrix construction
• Preprocessing pipeline (preprocessing): Configurable multi-stage pipeline chaining filters, artifact rejection, and re-referencing

Usage

use ruv_neural_signal::{
    BandpassFilter, PreprocessingPipeline, SignalProcessor,
    compute_psd, band_power, hilbert_transform, instantaneous_phase,
    compute_all_pairs, ConnectivityMetric,
};
use ruv_neural_core::FrequencyBand;

// Apply a bandpass filter (8-13 Hz alpha band)
let filter = BandpassFilter::new(8.0, 13.0, 1000.0, 4).unwrap();
let filtered = filter.apply(&raw_signal);

// Compute power spectral density (Welch method)
let psd = compute_psd(&signal, 1000.0, 256, 128);
let alpha_power = band_power(&psd, 1000.0, 8.0, 13.0);

// Extract instantaneous phase via Hilbert transform
let analytic = hilbert_transform(&signal);
let phases = instantaneous_phase(&analytic);

// Compute all-pairs connectivity matrix
let connectivity_matrix = compute_all_pairs(
    &multi_channel_data,
    ConnectivityMetric::PhaseLockingValue,
);

// Run full preprocessing pipeline
let pipeline = PreprocessingPipeline::default();
let clean_data = pipeline.process(&raw_data).unwrap();

API Reference

Module	Key Types / Functions
filter	BandpassFilter, HighpassFilter, LowpassFilter, NotchFilter, SignalProcessor
spectral	compute_psd, compute_stft, band_power, spectral_entropy, peak_frequency
hilbert	hilbert_transform, instantaneous_phase, instantaneous_amplitude
artifact	detect_eye_blinks, detect_muscle_artifact, detect_cardiac, reject_artifacts
connectivity	phase_locking_value, coherence, imaginary_coherence, amplitude_envelope_correlation, compute_all_pairs
preprocessing	PreprocessingPipeline

Feature Flags

Feature	Default	Description
std	Yes	Standard library support
simd	No	SIMD-accelerated filter kernels

Integration

Depends on ruv-neural-core for MultiChannelTimeSeries and FrequencyBand types. Feeds processed data into ruv-neural-graph for connectivity graph construction. Uses rustfft for FFT operations and ndarray for matrix computations.

License

MIT OR Apache-2.0