mvpure_py.beamformer#

mvpure_py.beamformer.filters_utils#

Computing MVPURE beamformers (MVP_R, MVP_N) weights.

mvpure_py.beamformer.filters_utils.make_mvp_n(Gk: ndarray, bf_numer: ndarray, bf_denom_inv: ndarray, filter_rank: str | int, n_orient: int, N: ndarray) → ndarray[source]#

Implements MVP_R filter defined in Eq. 44 of [1]_.

It is defined as: \({W}^{(r)}_{MVP_N}=P^{(r)}_{G_0}{W}_{LCMV_N}\),

where \(P^{(r)}_{G_0}\) is the orthogonal projection matrix onto subspace spanned by eigenvectors corresponding to the filter_rank number of largest eigenvalues of \(G_0\). \(G_0\) is defined as: \({H}_0^t{N}^{-1}{H}_0\) (eq. 23), where \(H_0\) is lead field matrix and \(N\) is noise covariance matrix.

Parameters:

  • Gk (ndarray, shape (n_sources, n_channels, 1)) – Leadfield transposition.

  • bf_numer (ndarray, shape (n_sources, 1, n_channels)) – bf_numer obtained from mne.beamformer._compute_beamformer._compute_bf_terms function

  • bf_denom_inv (ndarray, shape (n_sources, n_orient, n_orient)) – inversion of bf_denom obtained from mne.beamformer._compute_beamformer._compute_bf_terms function

  • filter_rank (int) – Defines number of eigenvectors corresponding to the largest eigenvalues of matrix S to take under consideration.

  • n_orient (int) – number of dipole orientations defined at each source point in case of using MVPURE should be equal to 1

  • N (array-like) – Noise covariance matrix

Returns:

W – Beamformer weights for ‘MVP_N’.

Return type:

ndarray, shape (n_sources, n_channels)

References

mvpure_py.beamformer.filters_utils.make_mvp_r(Gk: ndarray, bf_numer: ndarray, bf_denom_inv: ndarray, filter_rank: str | int, n_orient: int, R: ndarray) → ndarray[source]#

Implements MVP_R filter defined in Eq. 43 of [1]_.

It is defined as: \({W}^{(r)}_{MVP_R}=P^{(r)}_{S_0}{W}_{LCMV_R}\),

where \(P^{(r)}_{S_0}\) is the orthogonal projection matrix onto subspace spanned by eigenvectors corresponding to the filter_rank number of largest eigenvalues of \(S_0\). \(S_0\) is defined as: \({H}_0^t{R}^{-1}{H}_0\) (eq. 24), where \(H_0\) is the leadfield matrix and \(R\) is the data covariance matrix.

Parameters:

  • Gk (ndarray, shape (n_sources, n_channels, 1)) – Leadfield transposition.

  • bf_numer (ndarray, shape (n_sources, 1, n_channels)) – bf_numer obtained from mne.beamformer._compute_beamformer._compute_bf_terms function

  • bf_denom_inv (ndarray, shape (n_sources, n_orient, n_orient)) – inversion of bf_denom obtained from mne.beamformer._compute_beamformer._compute_bf_terms function

  • filter_rank (int) – Defines number of eigenvectors corresponding to the largest eigenvalues of matrix S to take under consideration.

  • n_orient (int) – number of dipole orientations defined at each source point in case of using MV-PURE should be equal to 1

  • R (array-like) – Data covariance matrix

Returns:

W – Beamformer weights for ‘MVP_R’.

Return type:

ndarray, shape (n_sources, n_channels)

References

mvpure_py.beamformer.mvp_filter#

Computing MVPURE beamformers. Based on mne.beamformer._lcmv.py (mne-tools/mne-python)

mvpure_py.beamformer.mvp_filter.apply_filter(evoked: Evoked, filters: Beamformer, verbose=None)[source]#

Apply MVPURE beamformer weights on evoked data.

Parameters:

  • evoked (mne.Evoked) – Evoked data to invert.

  • filters (mne.beamformer.Beamformer) – MVPURE spatial filter (beamformer weights) returned from make_filter().

Returns:

mne.SourceEstimate

Return type:

Source time courses

mvpure_py.beamformer.mvp_filter.apply_filter_cov(data_cov: Covariance, filters: Beamformer, verbose=None)[source]#

Apply MVPURE beamformer weights to a data covariance matrix to estimate source power.

Parameters:

  • data_cov (mne.Covariance) – Data covariance matrix.

  • filters (mne.beamformer.Beamformer) – MVPURE spatial filter (beamformer weights) returned from make_filter().

Returns:

mne.SourceEstimate

Return type:

Source power.

mvpure_py.beamformer.mvp_filter.apply_filter_epochs(epochs: Epochs, filters: Beamformer, return_generator=False, verbose=None)[source]#

Apply MVPURE beamformer weights on single trial data.

Parameters:

  • epochs (mne.Epochs) – Single trial epochs.

  • filters (mne.beamformer.Beamformer) – MVPURE spatial filter (beamformer weights) returned from make_filter().

  • return_generator (bool) – Return a generator object instead of a list. This allows iterating over the stcs without having to keep them all in memory.

Returns:

The source estimated for all epochs

Return type:

list | generator of mne.SourceEstimate

mvpure_py.beamformer.mvp_filter.apply_filter_raw(raw: Raw, filters: Beamformer, start=None, stop=None, verbose=None)[source]#

Apply MVPURE beamformer weights on raw data.

Parameters:

  • raw (mne.io.Raw) – Raw data.

  • filters (mne.beamformer.Beamformer) – MVPURE spatial filter (beamformer weights) returned from make_filter().

  • start (int) – Index of first time sample.

  • stop (int) – Index of first time sample not to include

Returns:

mne.SourceEstimate

Return type:

Source time courses.

mvpure_py.beamformer.mvp_filter.make_filter(info, forward, data_cov, reg=0.05, noise_cov=None, label=None, pick_ori=None, rank='info', weight_norm='unit-noise-gain-invariant', reduce_rank=False, depth=None, inversion='matrix', verbose=None, mvpure_params: dict = None)[source]#

Compute spatial filter from MVPURE package. Based on mne.beamformer.make_lcmv() function with additional parameter mvpure_params that specifies MVPURE-specific parameters: - ‘filter_type’ (with options MVP_R and MVP_N. If None, MVP_R will be used) - ‘filter_rank’ (as integer lower or equal to number of sources or ‘full’; if None ‘full’ will be used)

mvpure_params = {

‘filter_type’: str, ‘filter_rank’: str | int

}

Parameters:

  • info – Specifies the channels to include. Bad channels (in info['bads']) are not used.

  • forward (mne.Forward) – Forward operator.

  • data_cov (mne.Covariance) – Data covariance instance.

  • reg (float) – The regularization for the whitened data covariance.

  • noise_cov (mne.Covariance) – Noise covariance instance.

  • label (mne.Label) – Restricts the solution to a given label.

  • pick_ori – The source orientation to compute the beamformer in.

  • rank (dict | None | 'full' | 'info') – See compute_rank.

  • weight_norm (None | 'unit-noise-gain' | 'nai') – The weight normalization scheme to use.

  • reduce_rank (bool) – Whether to reduce the rank by one during computation of the filter.

  • depth

  • inversion ('matrix' | 'single') – The inversion scheme to compute the weights.

  • verbose (bool | str | int | None) – Control verbostiy of the loggin output. If None, use the default verbostiy level.

  • mvpure_params (dict) –

    Dictionary with MVPURE-py specific parameters. mvpure_params = {

    ’filter_type’: str, ‘filter_rank’: str | int

    } - ‘filter_type’ (with options MVP_R and MVP_N. If None, MVP_R will be used) - ‘filter_rank’ (as integer lower or equal to number of sources or ‘full’; if None ‘full’ will be used)

Returns:

Dictionary containing filter weights from MVPURE beamformer. Contains the same set of keys as mne.Beamformer.

Return type:

mne.Beamformer

mvpure_py.beamformer.mvpure_utils#

Functions specific to MVPURE beamformers.

mvpure_py.beamformer.mvpure_utils.get_G_proj_matrix(H: ndarray, N: ndarray, filter_rank: int | str) → tuple[ndarray, int][source]#

Compute the orthogonal projection matrix onto subspace spanned by eigenvectors corresponding to the filter_rank number of largest eigenvalues of \(G\).

\(G\) is defined as \({H}^t{N}^{-1}{H}\) (eq. 20 in [1]_), where \(H\) is the leadfield matrix

and \(N\) is the noise covariance matrix.

Given projection matrix is used during computing MVP_N filter (beamformer.filters_utils.make_mvp_n).
Parameters:

  • H (array-like) – Leadfield matrix.

  • N (array-like) – Noise covariance matrix

  • filter_rank (int | str) –

    • If int: Defines number of largest eigenvalues of matrix S to use calculating orthogonal projection matrix.

    • If full, it is equal to number of sources.

Returns:

  • proj_matrix (array-like) – Projection matrix onto \(G\) subspace

  • filter_rank (int) – Rank of the used filter

References

mvpure_py.beamformer.mvpure_utils.get_S_proj_matrix(H: ndarray, R: ndarray, filter_rank: int | str) → tuple[ndarray, int][source]#

Compute the orthogonal projection matrix onto subspace spanned by eigenvectors corresponding to the filter_rank number of largest eigenvalues of \(S\).

\(S\) is defined as \({H}^t{R}^{-1}{H}\) (eq. 21 in [1]_), where \(H\) is the leadfield matrix

and \(R\) is the data covariance matrix.

Given projection matrix is used during computing MVP_R filter (beamformer.filters_utils.make_mvp_r).
Parameters:

  • H (array-like) – Leadfield matrix.

  • R (array-like) – Data covariance matrix

  • filter_rank (int | str) –

    • If int: Defines number of largest eigenvalues of matrix S to use calculating orthogonal projection matrix.

    • If full, it is equal to number of sources.

Returns:

  • proj_matrix (array-like) – Projection matrix onto \(S\) subspace

  • filter_rank (int) – Rank of the used filter

References

Module contents#