Time-frequency in Source Space

[DiGyt]

Reference issue

This is the main PR for the GSoC TFR in Source Space Project (See: Issue #6290 ).

What does this implement/fix?

This PR will allow SourceEstimates or lists/generators of SourceEstimates to be passed into time_frequency functions. This means that the functions tfr_morlet, tfr_multitaper and tfr_stockwell will accept all types of SourceEstimates, and compute the correct time-frequency representation of source level data. It should work for all possible arguments of the respective functions (except n_jobs, which is ignored for morlet/multitaper, if a list is passed).

Additional information

Note that the PR #6543 will be further maintained within this pull, as the SourceTFR class and changes in time_frequency/tfr often depend on each other.

There are also some things that still should be implemented:

• economic computation, if stcs with a (kernel, sens_data) data field is passed
• economic computation of lists for tfr_stockwell
• frequency plotting in source space.

[DiGyt]

Is #6674 taking over this one?
Sorry #6673

@massich
No, I just opened #6673 and #6672 up as draft PRs, to be merged after this one. I think this pull should really be the priority, and the other stuff can be added later.

[DiGyt]

@agramfort
I tried to migrate the source_tfr.py module from mne/ to mne/time_frequency as you mentioned in #6673 (comment) (I also think that this idea makes a lot of sense). However this is causing a very nasty circular import reference, if we include in in time_frequency.__init__ and I'm not sure how to handle it in the best manner.
I thought, as you also would like to factorize everything with _BaseSourceEstimate ( #6673 (comment) ), we might just add the SourceTFR class to source_estimate.py, in order to keep everything together. But obviously, it would also make sense to keep SourceTFR in mne/time_frequency.

However, @agramfort @massich
The SourceTFR class does currently allow the possibility of storing data in the (kernel, sensor_data) form. But for now, this option is not even used, as the full tfr source time course is computed inside the time_frequency functions (in order to cope with the nonlinear steps that need to be performed after np.dot(kernel, sensor_data) ). So at the moment, the question is if we want to maintain the unused (kernel, sensor_data) representation for SourceTFRs.
If we do, I think it makes sense to make SourceTFR inherit stuff from _BaseSourceEstimate, and add it to the mne/source_estimate.py file as mentioned above. If we don't want to maintain this functionality, there will be less stuff to inherit from _BaseSourceEstimate, and therefore it would eventually be better to keep it a separate class.

So 2 questions, where i'd like to hear your opinions:

1. Should we maintain the functionality of SourceTFRs supporting (kernel, sensor_data) type data?
2. Should we add SourceTFR to mne/source_estimate.py or try to put it in mne/time_frequency/source_tfr.py?

[DiGyt]

Closed: See Issue #6290