"""Dynamic Imaging of Coherent Sources (DICS).""" # Authors: The MNE-Python contributors. # License: BSD-3-Clause # Copyright the MNE-Python contributors. import numpy as np from .._fiff.pick import pick_channels, pick_info from ..channels import equalize_channels from ..forward import _subject_from_forward from ..minimum_norm.inverse import _check_depth, _check_reference, combine_xyz from ..rank import compute_rank from ..source_estimate import _get_src_type, _make_stc from ..time_frequency import EpochsTFR from ..time_frequency.tfr import _check_tfr_complex from ..utils import ( _check_channels_spatial_filter, _check_one_ch_type, _check_option, _check_rank, _validate_type, logger, verbose, warn, ) from ._compute_beamformer import ( Beamformer, _check_src_type, _compute_beamformer, _compute_power, _prepare_beamformer_input, _proj_whiten_data, ) @verbose def make_dics( info, forward, csd, reg=0.05, noise_csd=None, label=None, pick_ori=None, rank=None, weight_norm=None, reduce_rank=False, depth=1.0, real_filter=True, inversion="matrix", verbose=None, ): """Compute a Dynamic Imaging of Coherent Sources (DICS) spatial filter. This is a beamformer filter that can be used to estimate the source power at a specific frequency range :footcite:`GrossEtAl2001`. It does this by constructing a spatial filter for each source point. The computation of these filters is very similar to those of the LCMV beamformer (:func:`make_lcmv`), but instead of operating on a covariance matrix, the CSD matrix is used. When applying these filters to a CSD matrix (see :func:`apply_dics_csd`), the source power can be estimated for each source point. Parameters ---------- %(info_not_none)s forward : instance of Forward Forward operator. csd : instance of CrossSpectralDensity The data cross-spectral density (CSD) matrices. A source estimate is performed for each frequency or frequency-bin defined in the CSD object. reg : float The regularization to apply to the cross-spectral density before computing the inverse. noise_csd : instance of CrossSpectralDensity | None Noise cross-spectral density (CSD) matrices. If provided, whitening will be done. The noise CSDs need to have been computed for the same frequencies as the data CSDs. Providing noise CSDs is mandatory if you mix sensor types, e.g. gradiometers with magnetometers or EEG with MEG. .. versionadded:: 0.20 label : Label | None Restricts the solution to a given label. %(pick_ori_bf)s %(rank_none)s .. versionadded:: 0.17 %(weight_norm)s Defaults to ``None``, in which case no normalization is performed. %(reduce_rank)s %(depth)s real_filter : bool If ``True``, take only the real part of the cross-spectral-density matrices to compute real filters. .. versionchanged:: 0.23 Version 0.23 an earlier used ``real_filter=False`` as the default, as of version 0.24 ``True`` is the default. %(inversion_bf)s .. versionchanged:: 0.21 Default changed to ``'matrix'``. %(verbose)s Returns ------- filters : instance of Beamformer Dictionary containing filter weights from DICS beamformer. Contains the following keys: 'kind' : str The type of beamformer, in this case 'DICS'. 'weights' : ndarray, shape (n_frequencies, n_weights) For each frequency, the filter weights of the beamformer. 'csd' : instance of CrossSpectralDensity The data cross-spectral density matrices used to compute the beamformer. 'ch_names' : list of str Channels used to compute the beamformer. 'proj' : ndarray, shape (n_channels, n_channels) Projections used to compute the beamformer. 'vertices' : list of ndarray Vertices for which the filter weights were computed. 'n_sources' : int Number of source location for which the filter weight were computed. 'subject' : str The subject ID. 'pick-ori' : None | 'max-power' | 'normal' | 'vector' The orientation in which the beamformer filters were computed. 'inversion' : 'single' | 'matrix' Whether the spatial filters were computed for each dipole separately or jointly for all dipoles at each vertex using a matrix inversion. 'weight_norm' : None | 'unit-noise-gain' The normalization of the weights. 'src_type' : str Type of source space. 'source_nn' : ndarray, shape (n_sources, 3) For each source location, the surface normal. 'is_free_ori' : bool Whether the filter was computed in a fixed direction (pick_ori='max-power', pick_ori='normal') or not. 'whitener' : None | ndarray, shape (n_channels, n_channels) Whitening matrix, provided if whitening was applied to the covariance matrix and leadfield during computation of the beamformer weights. 'max-power-ori' : ndarray, shape (n_sources, 3) | None When pick_ori='max-power', this fields contains the estimated direction of maximum power at each source location. See Also -------- apply_dics_csd Notes ----- The original reference is :footcite:`GrossEtAl2001`. See :footcite:`vanVlietEtAl2018` for a tutorial style paper on the topic. The DICS beamformer is very similar to the LCMV (:func:`make_lcmv`) beamformer and many of the parameters are shared. However, :func:`make_dics` and :func:`make_lcmv` currently have different defaults for these parameters, which were settled on separately through extensive practical use case testing (but not necessarily exhaustive parameter space searching), and it remains to be seen how functionally interchangeable they could be. The default setting reproduce the DICS beamformer as described in :footcite:`vanVlietEtAl2018`:: inversion='single', weight_norm=None, depth=1. To use the :func:`make_lcmv` defaults, use:: inversion='matrix', weight_norm='unit-noise-gain-invariant', depth=None For more information about ``real_filter``, see the supplemental information from :footcite:`HippEtAl2011`. References ---------- .. footbibliography:: """ # noqa: E501 rank = _check_rank(rank) _check_option("pick_ori", pick_ori, [None, "vector", "normal", "max-power"]) _check_option("inversion", inversion, ["single", "matrix"]) _validate_type(weight_norm, (str, None), "weight_norm") frequencies = [np.mean(freq_bin) for freq_bin in csd.frequencies] n_freqs = len(frequencies) _, _, allow_mismatch = _check_one_ch_type("dics", info, forward, csd, noise_csd) # remove bads so that equalize_channels only keeps all good info = pick_info(info, pick_channels(info["ch_names"], [], info["bads"])) info, forward, csd = equalize_channels([info, forward, csd]) csd, noise_csd = _prepare_noise_csd(csd, noise_csd, real_filter) depth = _check_depth(depth, "depth_sparse") if inversion == "single": depth["combine_xyz"] = False ( is_free_ori, info, proj, vertices, G, whitener, nn, orient_std, ) = _prepare_beamformer_input( info, forward, label, pick_ori, noise_cov=noise_csd, rank=rank, pca=False, **depth, ) # Compute ranks csd_int_rank = [] if not allow_mismatch: noise_rank = compute_rank(noise_csd, info=info, rank=rank) for i in range(len(frequencies)): csd_rank = compute_rank( csd.get_data(index=i, as_cov=True), info=info, rank=rank ) if not allow_mismatch: for key in csd_rank: if key not in noise_rank or csd_rank[key] != noise_rank[key]: raise ValueError( f"{key} data rank ({csd_rank[key]}) did not match the noise " f"rank ({noise_rank.get(key, None)})" ) csd_int_rank.append(sum(csd_rank.values())) del noise_csd ch_names = list(info["ch_names"]) logger.info("Computing DICS spatial filters...") Ws = [] max_oris = [] for i, freq in enumerate(frequencies): if n_freqs > 1: logger.info( " computing DICS spatial filter at " f"{round(freq, 2)} Hz ({i + 1}/{n_freqs})" ) Cm = csd.get_data(index=i) # XXX: Weird that real_filter happens *before* whitening, which could # make things complex again...? if real_filter: Cm = Cm.real # compute spatial filter n_orient = 3 if is_free_ori else 1 W, max_power_ori = _compute_beamformer( G, Cm, reg, n_orient, weight_norm, pick_ori, reduce_rank, rank=csd_int_rank[i], inversion=inversion, nn=nn, orient_std=orient_std, whitener=whitener, ) Ws.append(W) max_oris.append(max_power_ori) Ws = np.array(Ws) if pick_ori == "max-power": max_oris = np.array(max_oris) else: max_oris = None src_type = _get_src_type(forward["src"], vertices) subject = _subject_from_forward(forward) is_free_ori = is_free_ori if pick_ori in [None, "vector"] else False n_sources = np.sum([len(v) for v in vertices]) filters = Beamformer( kind="DICS", weights=Ws, csd=csd, ch_names=ch_names, proj=proj, vertices=vertices, n_sources=n_sources, subject=subject, pick_ori=pick_ori, inversion=inversion, weight_norm=weight_norm, src_type=src_type, source_nn=forward["source_nn"].copy(), is_free_ori=is_free_ori, whitener=whitener, max_power_ori=max_oris, ) return filters def _prepare_noise_csd(csd, noise_csd, real_filter): if noise_csd is not None: csd, noise_csd = equalize_channels([csd, noise_csd]) # Use the same noise CSD for all frequencies if len(noise_csd.frequencies) > 1: noise_csd = noise_csd.mean() noise_csd = noise_csd.get_data(as_cov=True) if real_filter: noise_csd["data"] = noise_csd["data"].real return csd, noise_csd def _apply_dics(data, filters, info, tmin, tfr=False): """Apply DICS spatial filter to data for source reconstruction.""" if isinstance(data, np.ndarray) and data.ndim == (2 + tfr): data = [data] one_epoch = True else: one_epoch = False Ws = filters["weights"] one_freq = len(Ws) == 1 subject = filters["subject"] # compatibility with 0.16, add src_type as None if not present: filters, warn_text = _check_src_type(filters) for i, M in enumerate(data): if not one_epoch: logger.info(f"Processing epoch : {i + 1}") # Apply SSPs if not tfr: # save computation, only compute once M_w = _proj_whiten_data(M, info["projs"], filters) stcs = [] for j, W in enumerate(Ws): if tfr: # must compute for each frequency M_w = _proj_whiten_data(M[:, j], info["projs"], filters) # project to source space using beamformer weights sol = np.dot(W, M_w) if filters["is_free_ori"] and filters["pick_ori"] != "vector": logger.info("combining the current components...") sol = combine_xyz(sol) tstep = 1.0 / info["sfreq"] stcs.append( _make_stc( sol, vertices=filters["vertices"], src_type=filters["src_type"], tmin=tmin, tstep=tstep, subject=subject, vector=(filters["pick_ori"] == "vector"), source_nn=filters["source_nn"], warn_text=warn_text, ) ) if one_freq: yield stcs[0] else: yield stcs logger.info("[done]") @verbose def apply_dics(evoked, filters, verbose=None): """Apply Dynamic Imaging of Coherent Sources (DICS) beamformer weights. Apply Dynamic Imaging of Coherent Sources (DICS) beamformer weights on evoked data. .. warning:: The result of this function is meant as an intermediate step for further processing (such as computing connectivity). If you are interested in estimating source time courses, use an LCMV beamformer (:func:`make_lcmv`, :func:`apply_lcmv`) instead. If you are interested in estimating spectral power at the source level, use :func:`apply_dics_csd`. .. warning:: This implementation has not been heavily tested so please report any issues or suggestions. Parameters ---------- evoked : Evoked Evoked data to apply the DICS beamformer weights to. filters : instance of Beamformer DICS spatial filter (beamformer weights) Filter weights returned from :func:`make_dics`. %(verbose)s Returns ------- stc : SourceEstimate | VolSourceEstimate | list Source time courses. If the DICS beamformer has been computed for more than one frequency, a list is returned containing for each frequency the corresponding time courses. See Also -------- apply_dics_epochs apply_dics_tfr_epochs apply_dics_csd """ # noqa: E501 _check_reference(evoked) info = evoked.info data = evoked.data tmin = evoked.times[0] sel = _check_channels_spatial_filter(evoked.ch_names, filters) data = data[sel] stc = _apply_dics(data=data, filters=filters, info=info, tmin=tmin) return next(stc) @verbose def apply_dics_epochs(epochs, filters, return_generator=False, verbose=None): """Apply Dynamic Imaging of Coherent Sources (DICS) beamformer weights. Apply Dynamic Imaging of Coherent Sources (DICS) beamformer weights on single trial data. .. warning:: The result of this function is meant as an intermediate step for further processing (such as computing connectivity). If you are interested in estimating source time courses, use an LCMV beamformer (:func:`make_lcmv`, :func:`apply_lcmv`) instead. If you are interested in estimating spectral power at the source level, use :func:`apply_dics_csd`. .. warning:: This implementation has not been heavily tested so please report any issue or suggestions. Parameters ---------- epochs : Epochs Single trial epochs. filters : instance of Beamformer DICS spatial filter (beamformer weights) Filter weights returned from :func:`make_dics`. The DICS filters must have been computed for a single frequency only. 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. %(verbose)s Returns ------- stc: list | generator of (SourceEstimate | VolSourceEstimate) The source estimates for all epochs. See Also -------- apply_dics apply_dics_tfr_epochs apply_dics_csd """ _check_reference(epochs) if len(filters["weights"]) > 1: raise ValueError( "This function only works on DICS beamformer weights that have " "been computed for a single frequency. When calling make_dics(), " "make sure to use a CSD object with only a single frequency (or " "frequency-bin) defined." ) info = epochs.info tmin = epochs.times[0] sel = _check_channels_spatial_filter(epochs.ch_names, filters) data = epochs.get_data(sel) stcs = _apply_dics(data=data, filters=filters, info=info, tmin=tmin) if not return_generator: stcs = list(stcs) return stcs @verbose def apply_dics_tfr_epochs(epochs_tfr, filters, return_generator=False, verbose=None): """Apply Dynamic Imaging of Coherent Sources (DICS) beamformer weights. Apply Dynamic Imaging of Coherent Sources (DICS) beamformer weights on single trial time-frequency data. Parameters ---------- epochs_tfr : EpochsTFR Single trial time-frequency epochs. filters : instance of Beamformer DICS spatial filter (beamformer weights) Filter weights returned from :func:`make_dics`. 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. %(verbose)s Returns ------- stcs : list of list of (SourceEstimate | VectorSourceEstimate | VolSourceEstimate) The source estimates for all epochs (outside list) and for all frequencies (inside list). See Also -------- apply_dics apply_dics_epochs apply_dics_csd """ # noqa E501 _validate_type(epochs_tfr, EpochsTFR) _check_tfr_complex(epochs_tfr) if filters["pick_ori"] == "vector": warn( "Using a vector solution to compute power will lead to " "inaccurate directions (only in the first quadrent) " "because power is a strictly positive (squared) metric. " "Using singular value decomposition (SVD) to determine " "the direction is not yet supported in MNE." ) sel = _check_channels_spatial_filter(epochs_tfr.ch_names, filters) data = epochs_tfr.data[:, sel, :, :] stcs = _apply_dics(data, filters, epochs_tfr.info, epochs_tfr.tmin, tfr=True) if not return_generator: stcs = [[stc for stc in tfr_stcs] for tfr_stcs in stcs] return stcs @verbose def apply_dics_csd(csd, filters, verbose=None): """Apply Dynamic Imaging of Coherent Sources (DICS) beamformer weights. Apply a previously computed DICS beamformer to a cross-spectral density (CSD) object to estimate source power in time and frequency windows specified in the CSD object :footcite:`GrossEtAl2001`. .. note:: Only power can computed from the cross-spectral density, not complex phase-amplitude, so vector DICS filters will be converted to scalar source estimates since power is strictly positive and so 3D directions cannot be combined meaningfully (the direction would be confined to the positive quadrant). Parameters ---------- csd : instance of CrossSpectralDensity The data cross-spectral density (CSD) matrices. A source estimate is performed for each frequency or frequency-bin defined in the CSD object. filters : instance of Beamformer DICS spatial filter (beamformer weights) Filter weights returned from `make_dics`. %(verbose)s Returns ------- stc : SourceEstimate Source power with frequency instead of time. frequencies : list of float The frequencies for which the source power has been computed. If the data CSD object defines frequency-bins instead of exact frequencies, the mean of each bin is returned. See Also -------- apply_dics apply_dics_epochs apply_dics_tfr_epochs References ---------- .. footbibliography:: """ # noqa: E501 ch_names = filters["ch_names"] vertices = filters["vertices"] n_orient = 3 if filters["is_free_ori"] else 1 subject = filters["subject"] whitener = filters["whitener"] n_sources = filters["n_sources"] # If CSD is summed over multiple frequencies, take the average frequency frequencies = [np.mean(dfreq) for dfreq in csd.frequencies] n_freqs = len(frequencies) source_power = np.zeros((n_sources, len(csd.frequencies))) # Ensure the CSD is in the same order as the weights csd_picks = [csd.ch_names.index(ch) for ch in ch_names] logger.info("Computing DICS source power...") for i, freq in enumerate(frequencies): if n_freqs > 1: logger.info( " applying DICS spatial filter at " f"{round(freq, 2)} Hz ({i + 1}/{n_freqs})" ) Cm = csd.get_data(index=i) Cm = Cm[csd_picks, :][:, csd_picks] W = filters["weights"][i] # Whiten the CSD Cm = np.dot(whitener, np.dot(Cm, whitener.conj().T)) source_power[:, i] = _compute_power(Cm, W, n_orient) logger.info("[done]") # compatibility with 0.16, add src_type as None if not present: filters, warn_text = _check_src_type(filters) return ( _make_stc( source_power, vertices=vertices, src_type=filters["src_type"], tmin=0.0, tstep=1.0, subject=subject, warn_text=warn_text, ), frequencies, )