{"action":"created","issue":{"url":"https://api.github.com/repos/mne-tools/mne-python/issues/4797","repository_url":"https://api.github.com/repos/mne-tools/mne-python","labels_url":"https://api.github.com/repos/mne-tools/mne-python/issues/4797/labels{/name}","comments_url":"https://api.github.com/repos/mne-tools/mne-python/issues/4797/comments","events_url":"https://api.github.com/repos/mne-tools/mne-python/issues/4797/events","html_url":"https://github.com/mne-tools/mne-python/pull/4797","id":278111588,"number":4797,"title":"[MRG] New implementation for CSD and DICS beamformers","user":{"login":"wmvanvliet","id":428273,"avatar_url":"https://avatars3.githubusercontent.com/u/428273?v=4","gravatar_id":"","url":"https://api.github.com/users/wmvanvliet","html_url":"https://github.com/wmvanvliet","followers_url":"https://api.github.com/users/wmvanvliet/followers","following_url":"https://api.github.com/users/wmvanvliet/following{/other_user}","gists_url":"https://api.github.com/users/wmvanvliet/gists{/gist_id}","starred_url":"https://api.github.com/users/wmvanvliet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/wmvanvliet/subscriptions","organizations_url":"https://api.github.com/users/wmvanvliet/orgs","repos_url":"https://api.github.com/users/wmvanvliet/repos","events_url":"https://api.github.com/users/wmvanvliet/events{/privacy}","received_events_url":"https://api.github.com/users/wmvanvliet/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":64,"created_at":"2017-11-30T13:00:10Z","updated_at":"2018-02-16T13:41:39Z","closed_at":null,"author_association":"CONTRIBUTOR","pull_request":{"url":"https://api.github.com/repos/mne-tools/mne-python/pulls/4797","html_url":"https://github.com/mne-tools/mne-python/pull/4797","diff_url":"https://github.com/mne-tools/mne-python/pull/4797.diff","patch_url":"https://github.com/mne-tools/mne-python/pull/4797.patch"},"body":"This PR will be the first in a series to merge Jan Kujala's 15+ years worth of assembled MATLAB scripts into MNE-Python. He and Joachim Gross invented all-to-all functional connectivity analysis with DICS and published the seminal PNAS 2001 paper on the topic.\r\n\r\nAs part of the Frontiers research topic: \"From raw to publication\", Susanna Aro and myself have been hard at work during the summer to convert the original implementation into Python, clean it up, make it fast, test and document it. You can preview what is to come [here](https://users.aalto.fi/vanvlm1/conpy).\r\n\r\nWithout further ado: The summer of beamforming is proud to present part 1 of the DICS series of PR's!\r\n\r\nNew CSD and DICS beamformer implementations\r\n========================================\r\n\r\nThis PR overhauls the existing CSD matrix computations and DICS beamformer implementations of MNE-Python. These implementations produce an output that is identical to their original, thoroughly battle-tested, MATLAB versions.\r\n\r\nSorry for the massive size of this PR, but we can't change the CSD implementation without breaking all DICS code, so we have to replace both systems at once.\r\n\r\n### New DICS implementation\r\nTaking @britta-wstnr 's implementation in #4430 as basis, we implemented a new `make_dics` function. Notable differences with the original is that it no longer requires a noise-CSD matrix (unit noise is assumed instead, we can in a later PR tackle noise normalization again if need be), and `pick_ori='max-power'` is now supported.\r\n\r\nAlso note that we made an enhancement to `_lcmv._reg_pinv`, namely the `rcond='auto'` mode, to match the original MATLAB implementation. This mode is necessary to make DICS behave properly and may be of some use to LCMV beamformers as well.\r\n\r\n### New CSD implementation\r\n\r\n`CrossSpectralDensity` objects can now contain multiple CSD matrices. Since it is a very common use case to perform DICS power mapping for multiple frequency bands, the intended workflow is:\r\n - Compute the CSD for all desired frequencies once\r\n - Save it to avoid recomputing this beast\r\n - Use `csd.mean()` to average across frequency bands at will\r\n - Feed the CSD object into `dics_source_power` to obtain an STC with the desired frequency bands as the \"time\" dimension.\r\n\r\n`csd_epochs` now by default operates in a new 'cwt_morlet' mode that uses Morlet wavelets to compute cross-spectral density. This matches how it was done in the PNAS 2001 paper. The 'multitaper' and 'fourier' modes have been left in their original state.\r\n\r\nCSD objects have a shiny plotting function to visually verify the result. It can also plot the channel-to-channel coherence (`mode='coh'`) which is useful for debugging your connectivity results (DICS connectivity will come in a later part of this series of PRs).\r\n\r\n### New tutorial\r\n\r\nIn `tutorials/plot_dics.py` the first part of a DICS connectivity analysis tutorial is provided. This part covers using DICS for finding two simulated sources. In the upcoming PR's for connectivity analysis this tutorial will be extended with one-to-all connectivity and finally all-to-all connectivity analysis. (You can preview the entire thing [here](https://users.aalto.fi/~vanvlm1/conpy/auto_examples/plot_simulation.html#sphx-glr-auto-examples-plot-simulation-py).\r\n\r\n### Removal of DICS applied to evoked data example\r\n\r\nApplying a DICS beamformer to raw time-courses does have some practical purpose, but it will not give you spectral source power over time (only `dics_source_power` and `tf_dics` give you that). I'm afraid the current `plot_dics_beamformer.py` example gives users the wrong idea on how to use DICS. We can later add a proper example after deliberation with Jan Kujala.\r\n\r\n### TODO\r\n\r\n - [x] Make leadfield normalization a switch\r\n - [x] Take a look at weight normalization\r\n - [x] Increase test coverage of error paths"},"comment":{"url":"https://api.github.com/repos/mne-tools/mne-python/issues/comments/366237871","html_url":"https://github.com/mne-tools/mne-python/pull/4797#issuecomment-366237871","issue_url":"https://api.github.com/repos/mne-tools/mne-python/issues/4797","id":366237871,"user":{"login":"britta-wstnr","id":20129119,"avatar_url":"https://avatars0.githubusercontent.com/u/20129119?v=4","gravatar_id":"","url":"https://api.github.com/users/britta-wstnr","html_url":"https://github.com/britta-wstnr","followers_url":"https://api.github.com/users/britta-wstnr/followers","following_url":"https://api.github.com/users/britta-wstnr/following{/other_user}","gists_url":"https://api.github.com/users/britta-wstnr/gists{/gist_id}","starred_url":"https://api.github.com/users/britta-wstnr/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/britta-wstnr/subscriptions","organizations_url":"https://api.github.com/users/britta-wstnr/orgs","repos_url":"https://api.github.com/users/britta-wstnr/repos","events_url":"https://api.github.com/users/britta-wstnr/events{/privacy}","received_events_url":"https://api.github.com/users/britta-wstnr/received_events","type":"User","site_admin":false},"created_at":"2018-02-16T13:41:39Z","updated_at":"2018-02-16T13:41:39Z","author_association":"CONTRIBUTOR","body":"I am a bit hesitant about a tutorial with a regularization parameter of ``0.5`` as it is not common practice in beamforming (in fact, it makes the beamformer very MNE-like :smile: ). Especially since it's toy data - is there really no way here to simulate the data such that the beamformer can work with it more easily?"}}
{"actor":{"display_login":"britta-wstnr"}}