Fix LFP transients; add baseline drift and optional line noise

[cboulay]

Summary

Fixes rare large-amplitude transient artifacts in the LFP output and adds two optional, physiologically-motivated artifact sources (slow baseline drift and mains line noise) to the velocity-encoded ecephys simulator. Also includes a performance pass on the drift generator for low-power (Raspberry Pi) targets.

All new behavior is opt-in or matched to prior defaults where it affects existing pipelines.

Changes

1. Fix LFP transient artifacts (β-stability)
The Kasdin all-pole noise filter degenerates to a pure integrator (y[n] = x[n] + y[n-1], pole on the unit circle) at β = 2. Clipping β to [0, 2] let sustained high velocity pin β at that ceiling, so the filter's state random-walked without bound; a later β change released it as a large transient followed by ringing. Capping β at 1.95 keeps the pole inside the unit circle. In testing this cut the worst-case transient ~30× and removed steady-state drift when velocity saturates.

2. Always-on slow 1/f baseline drift
The output-rate Kasdin filter only holds a 1/f slope down to a corner of a few hundred Hz, so the baseline is flat at rest (no sub-Hz power). New BaselineDrift transformer generates pink (β=1) noise on a low internal grid (drift_fs, default 50 Hz) — where a modest pole count reaches sub-Hz — then interpolates it up and adds it. It's velocity-independent, so slow wander is present even at rest. Wired into Velocity2LFP before mixing, so it appears as a shared low-frequency field drift across channels and its cost scales with n_lfp_sources rather than output_ch.

3. Optional mains line noise with clock drift
New LineNoise transformer adds a 50/60 Hz sinusoid to all channels, with the peak frequency doing a slow bounded random walk (default 0.002 Hz/s, clamped ±1.5 Hz) to emulate recording-clock drift. freq=None is a pass-through (disabled by default). SinGenerator gains matching optional bounded frequency drift via phase accumulation (the no-drift path stays bit-exact); the drift + phase-accumulation core is shared between the two.

4. Performance: fused BaselineDrift kernel
Interpolation, scaling, and the add are fused into a single compiled pass that writes the (n_samples, n_channels) result once (was three passes), with a SIMD-friendly inner loop. ~6× faster at 256 channels; output is statistically identical (same RNG draw order).

Integration notes / defaults

• Line noise is off by default (line_noise_freq=None) — set 50.0 or 60.0 to enable.
• drift_scale default is tuned so drift is ~20% of per-channel LFP std, matching the level before the pre-mix reorder; set 0 to disable.
• These are exposed on VelocityEncoderSettings (drift_scale, line_noise_freq, line_noise_amp, line_noise_drift_rate, line_noise_drift_bound).

Testing

pytest: 138 passed, ruff clean. New coverage: test_baseline_drift.py, test_line_noise.py, SinGenerator drift tests, and a regression test locking in the β<2 stability boundary. Verified continuity/chunk-independence, 1/f spectrum with real sub-Hz power, bounded drift rate/range, and end-to-end VelocityEncoder configuration.

🤖 Generated with Claude Code