[MRG] More work on the beamformer code (mne-tools#5447)

* Refactor _create_beamformer function to avoid branching

* ENH: Orient to normal

* More divide by zero fixes

* FIX: Remove now unnecessary comps workaround

* FIX: Naming

* Update whats_new.rst

* FIX: Unify API

* Change rank=False to rank='full' in _reg_pinv

* Fix docstring of default rank for dics

* Actually implement the change from rank=False => rank='full'

* Really actually implement the change from rank=False => rank='full'

* FIX: Deprecation

* FIX: Undo deprecation

* FIX: Spelling

* FIX: Raise

* FIX: No deprecation for LCMV yet

doc/whats_new.rst

@@ -92,6 +92,18 @@ Changelog
 
 - Add :meth:`mne.Report.remove` method to remove existing figures from a report, by `Marijn van Vliet`_
 
+- Add sign to output of max-power orientation for :func:`mne.beamformer.make_dics` by `Eric Larson`_
+
+- Add support for ``pick_ori='max-power'`` when ``weight_norm=None`` in :func:`mne.beamformer.make_lcmv` by `Marijn van Vliet`_
+
+- Add support for ``weight_norm='nai'`` for all ``pick_ori`` options in :func:`mne.beamformer.make_lcmv` by `Marijn van Vliet`_
+
+- Add support for ``weight_norm='nai'`` to :func:`mne.beamformer.make_dics` by `Marijn van Vliet`_
+
+- Add parameter ``rank=None`` to :func:`mne.beamformer.make_dics` by `Marijn van Vliet`_
+
+- Add parameter ``rank='full'`` to :func:`mne.beamformer.make_lcmv``, which can be set to ``None`` to auto-compute the rank of the covariance matrix before regularization by `Marijn van Vliet`_
+
 
 Bug
 ~~~
@@ -185,6 +197,9 @@ Bug
 
 - Fix error in mne coreg when saving with scaled MRI if fiducials haven't been saved by `Ezequiel Mikulan`_
 
+- Fix normalization error in :func:`mne.beamformer.make_lcmv` when ``pick_ori='normal', weight_norm='unit_noise_gain'`` by `Marijn van Vliet`_
+
+- Fix computation of max-power orientation in :func:`mne.beamformer.make_dics` when ``pick_ori='max-power', weight_norm='unit_noise_gain'`` by `Marijn van Vliet`_
 
 API
 ~~~

examples/inverse/plot_lcmv_beamformer.py

@@ -79,33 +79,29 @@
     # data (enabled by passing a noise covariance matrix)
     filters = make_lcmv(evoked.info, forward, data_cov, reg=0.05,
                         noise_cov=noise_cov, pick_ori=pick_ori,
-                        weight_norm='unit-noise-gain')
+                        weight_norm='unit-noise-gain', rank=None)
     print(filters)
     # apply this spatial filter to source-reconstruct the evoked data
     stc = apply_lcmv(evoked, filters, max_ori_out='signed')
 
     # View activation time-series in maximum voxel at 100 ms:
     time_idx = stc.time_as_index(0.1)
-    max_idx = np.argmax(stc.data[:, time_idx])
+    max_idx = np.argmax(np.abs(stc.data[:, time_idx]))
     # we know these are all left hemi, so we can just use vertices[0]
     max_voxs.append(stc.vertices[0][max_idx])
     ax.plot(stc.times, stc.data[max_idx, :], color, label=desc % max_idx)
 
-ax.set(xlabel='Time (ms)', ylabel='LCMV value', ylim=(-0.8, 2.2),
+ax.set(xlabel='Time (ms)', ylabel='LCMV value',
        title='LCMV in maximum voxel')
-ax.legend()
+ax.legend(loc='lower right')
 mne.viz.utils.plt_show()
 
 ###############################################################################
 # We can also look at the spatial distribution
 
-# take absolute value for plotting
-np.abs(stc.data, out=stc.data)
-
 # Plot last stc in the brain in 3D with PySurfer if available
-brain = stc.plot(hemi='lh', subjects_dir=subjects_dir,
-                 initial_time=0.1, time_unit='s')
-brain.show_view('lateral')
+brain = stc.plot(hemi='lh', views='lat', subjects_dir=subjects_dir,
+                 initial_time=0.1, time_unit='s', smoothing_steps=5)
 for color, vertex in zip(colors, max_voxs):
     brain.add_foci([vertex], coords_as_verts=True, scale_factor=0.5,
                    hemi='lh', color=color)

examples/inverse/plot_lcmv_beamformer_volume.py

@@ -1,7 +1,7 @@
 """
-===================================================================
-Compute LCMV inverse solution on evoked data in volume source space
-===================================================================
+====================================================
+Compute LCMV inverse solution in volume source space
+====================================================
 
 Compute LCMV inverse solution on an auditory evoked dataset in a volume source
 space.
@@ -77,7 +77,7 @@
 # of orientation selection and weight normalization are implemented yet.
 filters = make_lcmv(evoked.info, forward, data_cov, reg=0.05,
                     noise_cov=noise_cov, pick_ori='max-power',
-                    weight_norm='nai')
+                    weight_norm='nai', rank=None)
 print(filters)
 
 # You can save these with:

examples/inverse/plot_tf_dics.py

@@ -3,8 +3,7 @@
 Time-frequency beamforming using DICS
 =====================================
 
-Compute DICS source power [1]_ in a grid of time-frequency windows and
-display results.
+Compute DICS source power [1]_ in a grid of time-frequency windows.
 
 References
 ----------

examples/inverse/plot_tf_lcmv.py

@@ -134,7 +134,7 @@
 # space for faster computation, use label=None for full solution
 stcs = tf_lcmv(epochs, forward, noise_covs, tmin, tmax, tstep, win_lengths,
                freq_bins=freq_bins, subtract_evoked=subtract_evoked,
-               reg=data_reg, label=label)
+               reg=data_reg, label=label, rank=None)
 
 # Plotting source spectrogram for source with maximum activity.
 # Note that tmin and tmax are set to display a time range that is smaller than