[ENH] Allow vector DICS source estimates

[alexrockhill]

Part of https://github.com/mne-tools/mne-python/pull/10920.

[alexrockhill]

@wmvanvliet, would you have a minute to review this?

[alexrockhill]

I think the math is correct, but could you remind me what was the reason that we want to mess with applying DICS weights to an Evoked (a plain timecourse, so not a TFR) again? In my universe, DICS weights are applied to TFR's, whereas LCMV weights are applied to timecourses.

We've had this function for a long time, from before @britta-wstnr, @larsoner and I started touching the DICS code in the big beamformer project. We chose to attach the big scary warning label to warn people against applying DICS weights to timecourses and trying to interpret the results.

I don't think this PR has to do with this, it's just computing a vector source estimate from anything (most traditionally being a single time point across frequencies but with a vector solution instead of max power).

[alexrockhill]

Ok to merge?

[larsoner]

Let's do this early in the 1.2 cycle so we can work out any bugs and @wmvanvliet has time to think/respond. We're going to cut 1.1 today I think

[larsoner]

(but @wmvanvliet feel free to merge if you do get to it before we branch 1.1)

[britta-wstnr]

@wmvanvliet and @larsoner, is there a reason why we never supported this before?

One tiny alarm bell that starts to ring in my head is realted to the whole rotationally-invariant business with the unit-noise-gain beamformer. I have no idea how this would translate with a complex filter. (regarding this, BTW, note that we took a position on this in our beamformer paper now, where we advise against the usage of the Sekihara version of the unit-noise-gain vector beamformer and the usage of the not rotationally invariant array-gain beamformer - should I open an issue about this?)

Another thought: what happens with a complex filter and the vector case - can we end up with different phase shifts per orientation for one source? Would that be meaningful / biologically plausible (i.e. would the phase match the alignment of the source)? I don't have an exhaustive overview of how the DICS beamformer is used in the literature - I feel most cases I come across is plain power or connectivity (i.e. using complex filters) but with one orientation. What is your impression, @wmvanvliet ?

Last point: @wmvanvliet I agree that this old apply_dics_evoked function is not good - also mentioned that lately in a dev meeting. Would we want to deprecate?

[alexrockhill]

I'm not sure you could interpret phase in different directions but you could use it to compute power so I think that's the idea.

[britta-wstnr]

I'm not sure you could interpret phase in different directions but you could use it to compute power so I think that's the idea.

But for that you would not need a complex filter :-) so it is not really the question I was wondering about, which is: is there any possible problems with complex-valued vector DICS beamformers.

I can have a look at the FieldTrip code one of the days and see what they do, @larsoner @wmvanvliet

[alexrockhill]

But for that you would not need a complex filter :-) so it is not really the question I was wondering about, which is: is there any possible problems with complex-valued vector DICS beamformers.

I believe @agramfort was saying was that he recommended transforming to source space using complex phase amplitude first and then taking power because of the non-linearity of the power operation.

[britta-wstnr]

I believe @agramfort was saying was that he recommended transforming to source space using complex phase amplitude first and then taking power because of the non-linearity of the power operation.

DICS beamformers are formulate for non-complex filters as well and work well like that. For more info on this, see e.g. the seminal paper by Gross et al. 2001, or the paper I referenced for you on our Discord conversation (Westner, Dalal, Gramfort et al., 2022). If I may quote from the latter: "Application of the complex-valued CSD matrix in Eq. (16) yields a complex-valued spatial filter, which does not have a valid biophysical interpretation."

[alexrockhill]

The failures are unrelated to this PR and have to do with exporting to EEGLAB

[alexrockhill]

Finally had a chance to look at this more in-depth.

Thanks for the review! I just had a quick question above, then I'll implement the changes you suggested.

[alexrockhill]

Ok, I think this should be good now.

[alexrockhill]

Almost there! We just need to expand the test_apply_dics_ori_inv function in the test_dics.py file. We already test a couple of orientations there, you can just add 'vector' to the list. Then on line 398 you want to change to want_norm = 3 if pick_ori in (None, 'vector') else 1

Ah okay, sorry I misunderstood that that was still needed.

[wmvanvliet]

Thanks @alexrockhill!