LeadfieldReadout

LeadfieldReadout#

class brainmass.LeadfieldReadout(lm, y0, cy0, normalize=True, demean=True)#

Trainable leadfield-matrix EEG readout.

Transforms a source-activity vector (e.g. E - I) to EEG sensor space using a leadfield matrix:

\[\mathrm{EEG} = c_{y0}\, (\hat{L}\, x) - y_0 ,\]

where \(\hat{L}\) is the (optionally row-normalised, demeaned) leadfield matrix and x is the source-activity vector.

Parameters:

  • lm (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Leadfield matrix of shape (output_size, node_size). Wrapped in a trainable Param.

  • y0 (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Output bias parameter, subtracted from every channel.

  • cy0 (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Global scaling coefficient applied to the projected activity.

  • normalize (bool) –

    Row-normalisation mode for the leadfield matrix:

    • True or 'l1' (default): scale each row by its L1 norm sum(|w|) so the row’s absolute values sum to one.

    • 'l2': scale each row by its L2 (Euclidean) norm sqrt(sum(w**2)) so each row becomes a unit vector.

    • False: no row normalisation.

    True maps to 'l1' for backward compatibility: the original implementation computed sum(sqrt(w**2)) == sum(|w|) while its comment mislabelled it “L2”. L1 is kept as the default so existing results are unchanged; pass 'l2' to opt into Euclidean row normalisation.

  • demean (bool) – If True, remove the per-channel mean across sensors (columns).

Return type:

Any

See also

brainmass.forward_model.LeadFieldModel

The heavier, unit-aware forward operator.

Notes

Use LeadfieldReadout when you want a lightweight, trainable EEG readout head — the leadfield is a fitted parameter with optional row normalisation / demeaning, and inputs/outputs are plain (unitless) arrays. Use brainmass.forward_model.LeadFieldModel instead when you need a physically faithful forward model: explicit physical units, vertex→region aggregation, and additive measurement noise with a configurable covariance.

__init__(lm, y0, cy0, normalize=True, demean=True)[source]#
Parameters:
normalize_leadfield(lm)[source]#

Row-normalise and/or demean the leadfield matrix.

Applied lazily as the precompute hook of self.lm whenever the parameter value is read.

Parameters:

lm (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Leadfield matrix of shape (output_size, node_size).

Returns:

The leadfield matrix after optional row normalisation ('l1' scales each row by sum(|w|); 'l2' by sqrt(sum(w**2))) and optional per-channel demeaning (demean).

Return type:

Array | ndarray | bool | number | bool | int | float | complex | Quantity

update(x)[source]#

Project source activity to EEG sensor space.

Parameters:

x (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Source-activity array whose last axis has length node_size. Leading axes (batch/time) are mapped over automatically.

Returns:

EEG signals with the last axis replaced by output_size.

Return type:

Array