mne_rt.tools.AdaptiveLMSFilter

class mne_rt.tools.AdaptiveLMSFilter(ref_ch_idx: int = 0, n_taps: int = 5, mu: float = 0.01)

Bases: object

Adaptive LMS filter for real-time EOG / ECG artifact removal.

Implements the Widrow–Hoff Least Mean Squares algorithm [1] to regress out a reference artifact channel (e.g. a frontal EOG electrode or an ECG lead) from all other M/EEG channels. Filter weights are updated online — no calibration baseline is required.

Parameters:

ref_ch_idxint, default 0

Index of the reference (artifact) channel in the data array.

n_tapsint, default 5

Number of tapped-delay filter coefficients (filter order). Larger values capture longer temporal autocorrelation in the artifact but increase computation.

mufloat, default 0.01

LMS step size (learning rate). Must satisfy \(0 < \mu < 2 / (n_{\mathrm{taps}} \cdot P_{\mathrm{ref}})\), where \(P_{\mathrm{ref}}\) is the reference-channel power. Values between 0.001 and 0.05 are typically stable.

Attributes:

weights_ndarray, shape (n_channels, n_taps) or None

Current filter weights. None until the first call to transform(). Weights persist across successive chunk calls to enable online adaptation.

Raises:

ValueError

If mu <= 0 or n_taps < 1.

Notes

No fit() call is required — the filter adapts from the first sample. Use artifact_correction="lms" in RTStream to enable during recording, or call transform() directly.

See Adaptive LMS filter for the full mathematical background.

References

[1]

Bernard Widrow and Marcian E Hoff. Adaptive switching circuits. In Neurocomputing: foundations of research, pages 123–134. 1988.

Examples

Apply to a single data chunk:

>>> filt = AdaptiveLMSFilter(ref_ch_idx=0, mu=0.01)
>>> clean = filt.transform(data)   # data: (n_channels, n_times)

Maintain weight state across consecutive real-time chunks:

>>> filt = AdaptiveLMSFilter()
>>> for chunk in stream:
...     clean_chunk = filt.transform(chunk)

__init__(ref_ch_idx: int = 0, n_taps: int = 5, mu: float = 0.01) → None

Methods

__init__([ref_ch_idx, n_taps, mu])
fit([raw_info])	No-op: LMS requires no calibration baseline.
reset()	Reset filter weights to zero (restart adaptation).
transform(data)	Apply the adaptive LMS filter to a data chunk.

fit(raw_info=None, **kwargs) → AdaptiveLMSFilter

No-op: LMS requires no calibration baseline.

Provided for API consistency with other artifact correctors. Returns self.

transform(data: ndarray) → ndarray

Apply the adaptive LMS filter to a data chunk.

The reference channel (ref_ch_idx) drives artifact cancellation for all other channels. Filter weights are updated in-place so that successive calls continue adapting rather than restarting from zero.

Parameters:

datandarray, shape (n_channels, n_times)

Raw M/EEG data chunk.

Returns:

cleanedndarray, shape (n_channels, n_times)

Artifact-attenuated data (reference channel is passed through unchanged).

reset() → None

Reset filter weights to zero (restart adaptation).