mne_rt.SourceModel#

class mne_rt.SourceModel(*, src, atlas: str, subject: str = 'fsaverage', subjects_dir=None, filters=None, inverse=None, inverse_method: str = 'dSPM', info=None, lambda2: float = 0.1111111111111111, pick_ori: str | None = 'normal')[source]#

Bases: object

Sensor data → ROI time courses, via one cached linear operator.

Parameters:

srcinstance of SourceSpaces: The source space the inverse/beamformer was built on. Needed to map atlas labels onto source-estimate rows.
atlasstr: Volumetric atlas stem ("aparc+aseg") or surface annotation name ("aparc").
subjectstr: FreeSurfer subject identifier.
subjects_dirpath-like | None: FreeSurfer subjects directory.
filtersinstance of Beamformer | None: Fitted LCMV spatial filter. Required for the fast kernel path.
inverseinstance of InverseOperator | None: Minimum-norm inverse operator.
inverse_methodstr: Minimum-norm method: "MNE", "dSPM", "sLORETA" or "eLORETA".
infoinstance of Info | None: Measurement info, required to build a cached kernel for the minimum-norm path (see source_operator()).
lambda2float: Regularisation for the minimum-norm inverse.
pick_oristr | None: Source orientation. "normal" on a surface source space keeps the solution linear; None on a volume source space yields a magnitude, which is not linear (see Notes).

Notes

Both supported inverses are linear in the sensor data as long as the orientation is fixed, which is what makes the cached kernel exact:

LCMV with pick_ori="max-power" reduces to weights @ whitener.
A minimum-norm operator with pick_ori="normal" is recovered by pushing an identity “recording” through apply_inverse_raw() — the result is the operator matrix, using only public API.

Free-orientation solutions (LCMV with pick_ori=None/"vector", or a minimum-norm estimate on a volume source space) combine three orientations by norm. That is non-linear and discards phase, which would make imaginary coherence meaningless, so those configurations report supports_kernel = False and refuse the kernel rather than silently returning a plausible-looking number.

__init__(*, src, atlas: str, subject: str = 'fsaverage', subjects_dir=None, filters=None, inverse=None, inverse_method: str = 'dSPM', info=None, lambda2: float = 0.1111111111111111, pick_ori: str | None = 'normal') → None[source]#

Methods

`__init__`(*, src, atlas[, subject, ...])
`apply`(data, *[, kernel, ch_picks, ...])	Return ROI time courses `(n_roi, n_times)` for one data window.
`channel_picks`(ch_names)	Row indices selecting/reordering `ch_names` into operator order.
`from_stream`(rt, *[, atlas, method, reg, ...])	Build a `SourceModel` from a session that has recorded a baseline.
`label_operator`(rois, *[, mri_resolution])	Sparse-average matrix mapping source points to ROIs, shape `(n_roi, n_src)`.
`roi_kernel`(rois, *[, mri_resolution])	The full sensor → ROI operator, shape `(n_roi, n_channels)`.
`source_estimate`(data, *[, info, pick_ori])	Source time courses `(n_src, n_times)` via the full MNE route.
`source_operator`()	Linear map from sensor data to source time courses, shape `(n_src, n_ch)`.

Attributes

`channel_names`	Channels the operator expects, in the order its columns are in.
`kind`	`"volume"` or `"surface"`, taken from the source space.
`n_sources`
`supports_kernel`	Whether the fast cached-kernel path is available.

property kind: str#: "volume" or "surface", taken from the source space.

property n_sources: int#

property channel_names: list#

Channels the operator expects, in the order its columns are in.

This is not necessarily the recording’s channel list: building a forward model drops EEG channels with no digitised position, and make_lcmv/make_inverse_operator additionally drop info["bads"]. apply_lcmv_raw() handles this internally by selecting channels from the data; the cached-kernel path must do the same, or a single bad channel makes every kernel @ data fail on a shape mismatch — and a same-count reordering would silently produce wrong ROI time courses.

channel_picks(ch_names: Sequence[str]) → ndarray[source]#: Row indices selecting/reordering ch_names into operator order.

property supports_kernel: bool#

Whether the fast cached-kernel path is available.

True when the source estimate is a linear function of the sensor data: an LCMV beamformer with a fixed orientation, or a minimum-norm operator with pick_ori="normal". Free-orientation solutions combine three orientations by norm and are excluded.

source_operator() → ndarray[source]#

Linear map from sensor data to source time courses, shape (n_src, n_ch).

For LCMV this mirrors what apply_lcmv_raw() does internally: whiten (or project) the data, then apply the beamformer weights.

For a minimum-norm operator it recovers the same matrix by pushing an identity “recording” through apply_inverse_raw() — the columns of the result are the response to a unit signal on each channel, i.e. the operator itself. This uses only public API and is exact for "MNE" and to floating-point for the noise-normalised methods.

label_operator(rois: Sequence[ROI], *, mri_resolution: bool = True) → ndarray[source]#

Sparse-average matrix mapping source points to ROIs, shape (n_roi, n_src).

Equivalent to extract_label_time_course() with mode="mean" (volume) or "mean_flip" (surface), but built once rather than recomputed every window.

roi_kernel(rois: Sequence[ROI], *, mri_resolution: bool = True) → ndarray[source]#

The full sensor → ROI operator, shape (n_roi, n_channels).

Apply it to a data window with apply(), or simply kernel @ data.

apply(data: ndarray, *, kernel=None, ch_picks=None, label_operator=None, info=None, pick_ori: str | None = None) → ndarray[source]#

Return ROI time courses (n_roi, n_times) for one data window.

Uses kernel when given — one matmul, and the whole point of this class. Otherwise applies the source estimate the slow way and reduces it with label_operator; correct, but ~two orders of magnitude slower and unsuitable for a closed loop.

Note the label reduction is the same matrix either way, so the two paths agree exactly; only the source step differs.

source_estimate(data: ndarray, *, info=None, pick_ori=None) → ndarray[source]#: Source time courses (n_src, n_times) via the full MNE route.

classmethod from_stream(rt, *, atlas: str | None = None, method: str = 'LCMV', reg: float = 0.05, pick_ori: str = 'max-power', weight_norm: str = 'unit-noise-gain') → SourceModel[source]#

Build a SourceModel from a session that has recorded a baseline.

Parameters:

rtinstance of RTStream: Session with src/fwd/data_cov set — i.e. one on which compute_inv_operator() has run, directly or through the first source modality that needed it.
atlasstr | None: Overrides the session’s source_atlas.
methodstr: "LCMV" for the beamformer, or a minimum-norm method name.
reg, pick_ori, weight_norm: Passed to make_lcmv().