mne_rt.tools.RTMaxwellFilter

class mne_rt.tools.RTMaxwellFilter(int_order: int = 8, ext_order: int = 3, origin: str | tuple = 'auto', st_duration: float | None = None, st_correlation: float = 0.98, st_update_interval: int = 1, calibration: str | None = None, cross_talk: str | None = None, coord_frame: str = 'head', regularize: str | None = 'in', mag_scale: float = 100.0)

Bases: object

Real-time Maxwell filtering (SSS / tSSS) for streaming MEG data.

Pre-computes the Signal Space Separation (SSS) projection matrix [1] once from sensor geometry, then applies it as a single matrix multiply per incoming chunk — zero added latency, numerically equivalent to offline MNE. Temporal SSS (tSSS) [2] can optionally run on a rolling buffer to remove interference that leaks into the internal subspace.

See RTMaxwellFilter — Real-Time SSS / tSSS for the full mathematical background.

Parameters:

int_orderint, default 8

Internal spherical-harmonic expansion order. \(L_{\mathrm{in}} = 8\) → \((L+1)^2-1 = 80\) moments (MNE default, adequate for all standard MEG systems).

ext_orderint, default 3

External expansion order (3 → 16 external moments).

originarray_like of shape (3,) | “auto”, default “auto”

SSS expansion origin in metres (head frame). "auto" fits a sphere to the head digitisation; falls back to (0, 0, 0.04) m when digitisation is absent.

st_durationfloat | None, default None

tSSS temporal buffer in seconds. None → spatial SSS only. Typical values: 10 s for persistent shielding leakage; 1–4 s for moving subjects.

st_correlationfloat, default 0.98

Minimum inside–outside correlation for tSSS suppression. Lower values are more aggressive.

st_update_intervalint, default 1

Apply tSSS every N incoming chunks. Increase to reduce CPU load when winsize is small; SSS is used between updates.

calibrationstr | None, default None

Fine-calibration .dat file (Elekta/MEGIN). Corrects sensor position and orientation errors; typically improves noise floor by 10–20 %.

cross_talkstr | None, default None

Cross-talk compensation .fif file. Compensates flux leakage between adjacent sensors.

coord_frame{“head”, “meg”}, default “head”

Coordinate frame for the spherical-harmonic expansion.

regularize{“in”, None}, default “in”

Internal-moment Tikhonov regularisation passed to MNE.

mag_scalefloat, default 100.0

Magnetometer/gradiometer balance factor.

Raises:

ImportError

If MNE-Python is not installed.

ValueError

If no MEG channels are found in the supplied info.

RuntimeError

If transform() is called before fit().

See also

mne.preprocessing.compute_maxwell_basis

Underlying SSS basis function.

mne.preprocessing.maxwell_filter

Full offline Maxwell filtering.

mne_rt.RTStream.fit_maxwell

Fit from a connected MEG session.

Notes

No baseline recording is required. The SSS operator depends only on sensor geometry, not on brain signal statistics. Simply call connect_to_lsl() then fit_maxwell().

References

[1]

Samu Taulu, Matti Kajola, and Juha Simola. Suppression of interference and artifacts by the signal space separation method. Brain topography, 16(4):269–275, 2004.

[2]

Samu Taulu and Juha Simola. Spatiotemporal signal space separation method for rejecting nearby interference in meg measurements. Physics in Medicine & Biology, 51(7):1759–1768, 2006.

Examples

SSS-only (fastest, no latency):

>>> rt_mf = RTMaxwellFilter()
>>> rt_mf.fit(raw.info)
>>> clean = rt_mf.transform(meg_chunk)

tSSS with fine calibration and empty room:

>>> rt_mf = RTMaxwellFilter(st_duration=10.0, calibration="sss_cal.dat")
>>> rt_mf.fit(raw.info, empty_room_raw=er_raw)
>>> clean = rt_mf.transform(meg_chunk)

Added in version 1.0.0.

__init__(int_order: int = 8, ext_order: int = 3, origin: str | tuple = 'auto', st_duration: float | None = None, st_correlation: float = 0.98, st_update_interval: int = 1, calibration: str | None = None, cross_talk: str | None = None, coord_frame: str = 'head', regularize: str | None = 'in', mag_scale: float = 100.0) → None

Methods

__init__([int_order, ext_order, origin, ...])
fit(info[, empty_room_raw])	Pre-compute the SSS projection operator from MEG sensor geometry.
transform(data)	Apply Maxwell filtering to a streaming MEG window.

Attributes

mode	Operating mode: "sss" or "tsss".
sss_projector	Cached SSS matrix, shape (n_meg_all, n_meg_good).

fit(info, empty_room_raw=None) → RTMaxwellFilter

Pre-compute the SSS projection operator from MEG sensor geometry.

No data is required — the operator depends only on sensor positions. An optional empty-room recording adds noise-informed regularisation.

Parameters:

infomne.Info

MEG measurement info with sensor positions and the device-to-head transform (dev_head_t).

empty_room_rawmne.io.Raw | None, default None

Empty-room recording in the same coordinate frame. When given, the operator is extracted via system identification so that noise-informed regularisation is built into the cached matrix (see class docstring). None uses geometric regularisation only via compute_maxwell_basis().

Returns:

selfRTMaxwellFilter

transform(data: ndarray) → ndarray

Apply Maxwell filtering to a streaming MEG window.

Parameters:

datandarray, shape (n_channels, n_samples)

Raw MEG window. Non-MEG channels are passed through unchanged.

Returns:

cleanndarray, shape (n_channels, n_samples)

SSS- or tSSS-cleaned data.

Raises:

RuntimeError

If fit() has not been called.

property sss_projector: ndarray

Cached SSS matrix, shape (n_meg_all, n_meg_good).

Maps good-channel input to the SSS-reconstructed output for all MEG channels, interpolating bad sensors from surrounding ones.

property mode: str

Operating mode: "sss" or "tsss".