Repository: mne-tools/mne-python

Issue:
rename compute_raw_data_covariance to compute_raw_covariance
any objection to rename compute_raw_data_covariance to compute_raw_covariance ?

the _data is not consistent. See eg compute_raw_psd etc...

Discussion:

Patch:
diff --git a/doc/manual/cookbook.rst b/doc/manual/cookbook.rst
index ac96a2780..17a256d13 100644
--- a/doc/manual/cookbook.rst
+++ b/doc/manual/cookbook.rst
@@ -347,9 +347,9 @@ ways:
 - Employ empty room data (collected without the subject) to
   calculate the full noise covariance matrix. This is recommended
   for analyzing ongoing spontaneous activity. This can be done using
-  :func:`mne.compute_raw_data_covariance` as::
+  :func:`mne.compute_raw_covariance` as::
 
-      >>> cov = mne.compute_raw_data_covariance(raw_erm)
+      >>> cov = mne.compute_raw_covariance(raw_erm)
 
 - Employ a section of continuous raw data collected in the presence
   of the subject to calculate the full noise covariance matrix. This
@@ -360,7 +360,7 @@ ways:
   (``*> 200 s``) segment of data with epileptic spikes present provided
   that the spikes occur infrequently and that the segment is apparently
   stationary with respect to background brain activity. This can also
-  use :func:`mne.compute_raw_data_covariance`.
+  use :func:`mne.compute_raw_covariance`.
 
 See :ref:`covariance` for more information.
 
diff --git a/doc/python_reference.rst b/doc/python_reference.rst
index e700b9131..4a9df6655 100644
--- a/doc/python_reference.rst
+++ b/doc/python_reference.rst
@@ -512,7 +512,7 @@ Covariance
    :template: function.rst
 
    compute_covariance
-   compute_raw_data_covariance
+   compute_raw_covariance
    make_ad_hoc_cov
    read_cov
    write_cov
diff --git a/examples/preprocessing/plot_estimate_covariance_matrix_raw.py b/examples/preprocessing/plot_estimate_covariance_matrix_raw.py
index a0d799cc0..efafce8e8 100644
--- a/examples/preprocessing/plot_estimate_covariance_matrix_raw.py
+++ b/examples/preprocessing/plot_estimate_covariance_matrix_raw.py
@@ -29,7 +29,7 @@ picks = mne.pick_types(raw.info, meg=True, eeg=True, stim=False, eog=True,
 reject = dict(eeg=80e-6, eog=150e-6)
 
 # Compute the covariance from the raw data
-cov = mne.compute_raw_data_covariance(raw, picks=picks, reject=reject)
+cov = mne.compute_raw_covariance(raw, picks=picks, reject=reject)
 print(cov)
 
 ###############################################################################
diff --git a/examples/preprocessing/plot_xdawn_denoising.py b/examples/preprocessing/plot_xdawn_denoising.py
index b861a7cd0..76b7ce824 100644
--- a/examples/preprocessing/plot_xdawn_denoising.py
+++ b/examples/preprocessing/plot_xdawn_denoising.py
@@ -31,7 +31,7 @@ efficient sensor selection in a P300 BCI. In Signal Processing Conference,
 # License: BSD (3-clause)
 
 
-from mne import (io, compute_raw_data_covariance, read_events, pick_types,
+from mne import (io, compute_raw_covariance, read_events, pick_types,
                  Epochs)
 from mne.datasets import sample
 from mne.preprocessing import Xdawn
@@ -65,7 +65,7 @@ epochs = Epochs(raw, events, event_id, tmin, tmax, proj=False,
 plot_epochs_image(epochs['vis_r'], picks=[230], vmin=-500, vmax=500)
 
 # Estimates signal covariance
-signal_cov = compute_raw_data_covariance(raw, picks=picks)
+signal_cov = compute_raw_covariance(raw, picks=picks)
 
 # Xdawn instance
 xd = Xdawn(n_components=2, signal_cov=signal_cov)
diff --git a/mne/__init__.py b/mne/__init__.py
index 43e82ce21..19cc4a46c 100644
--- a/mne/__init__.py
+++ b/mne/__init__.py
@@ -36,7 +36,7 @@ from .bem import (make_sphere_model, make_bem_model, make_bem_solution,
                   read_bem_solution, write_bem_solution)
 from .cov import (read_cov, write_cov, Covariance,
                   compute_covariance, compute_raw_data_covariance,
-                  whiten_evoked, make_ad_hoc_cov)
+                  compute_raw_covariance, whiten_evoked, make_ad_hoc_cov)
 from .event import (read_events, write_events, find_events, merge_events,
                     pick_events, make_fixed_length_events, concatenate_events,
                     find_stim_steps)
diff --git a/mne/cov.py b/mne/cov.py
index 0cd17ab27..bbf7fff5e 100644
--- a/mne/cov.py
+++ b/mne/cov.py
@@ -33,6 +33,7 @@ from .defaults import _handle_default
 from .epochs import _is_good
 from .utils import (check_fname, logger, verbose, estimate_rank,
                     _compute_row_norms, check_sklearn_version, _time_mask)
+from .utils import deprecated
 
 from .externals.six.moves import zip
 from .externals.six import string_types
@@ -100,7 +101,7 @@ class Covariance(dict):
     See Also
     --------
     compute_covariance
-    compute_raw_data_covariance
+    compute_raw_covariance
     make_ad_hoc_cov
     read_cov
     """
@@ -275,7 +276,7 @@ def read_cov(fname, verbose=None):
 
     See Also
     --------
-    write_cov, compute_covariance, compute_raw_data_covariance
+    write_cov, compute_covariance, compute_raw_covariance
     """
     check_fname(fname, 'covariance', ('-cov.fif', '-cov.fif.gz'))
     f, tree = fiff_open(fname)[:2]
@@ -338,10 +339,20 @@ def _check_n_samples(n_samples, n_chan):
         logger.warning(text)
 
 
+@deprecated('"compute_raw_data_covariance" is deprecated and will be '
+            'removed in MNE-0.11. Please use compute_raw_covariance instead')
 @verbose
 def compute_raw_data_covariance(raw, tmin=None, tmax=None, tstep=0.2,
                                 reject=None, flat=None, picks=None,
                                 verbose=None):
+    return compute_raw_covariance(raw, tmin, tmax, tstep,
+                                  reject, flat, picks, verbose)
+
+
+@verbose
+def compute_raw_covariance(raw, tmin=None, tmax=None, tstep=0.2,
+                           reject=None, flat=None, picks=None,
+                           verbose=None):
     """Estimate noise covariance matrix from a continuous segment of raw data.
 
     It is typically useful to estimate a noise covariance
@@ -557,7 +568,7 @@ def compute_covariance(epochs, keep_sample_mean=True, tmin=None, tmax=None,
 
     See Also
     --------
-    compute_raw_data_covariance : Estimate noise covariance from raw data
+    compute_raw_covariance : Estimate noise covariance from raw data
 
     References
     ----------


Test patch:
diff --git a/mne/beamformer/tests/test_lcmv.py b/mne/beamformer/tests/test_lcmv.py
index b9435b236..d92c60a11 100644
--- a/mne/beamformer/tests/test_lcmv.py
+++ b/mne/beamformer/tests/test_lcmv.py
@@ -205,7 +205,7 @@ def test_lcmv_raw():
     picks = mne.pick_types(raw.info, meg=True, exclude='bads',
                            selection=left_temporal_channels)
 
-    data_cov = mne.compute_raw_data_covariance(raw, tmin=tmin, tmax=tmax)
+    data_cov = mne.compute_raw_covariance(raw, tmin=tmin, tmax=tmax)
 
     stc = lcmv_raw(raw, forward, noise_cov, data_cov, reg=0.01, label=label,
                    start=start, stop=stop, picks=picks)
diff --git a/mne/preprocessing/tests/test_maxwell.py b/mne/preprocessing/tests/test_maxwell.py
index 118f74aa9..c7f07ff0a 100644
--- a/mne/preprocessing/tests/test_maxwell.py
+++ b/mne/preprocessing/tests/test_maxwell.py
@@ -9,7 +9,7 @@ from numpy.testing import (assert_equal, assert_allclose,
                            assert_array_almost_equal)
 from nose.tools import assert_true, assert_raises
 
-from mne import compute_raw_data_covariance, pick_types
+from mne import compute_raw_covariance, pick_types
 from mne.cov import _estimate_rank_meeg_cov
 from mne.datasets import testing
 from mne.forward._make_forward import _prep_meg_channels
@@ -142,8 +142,8 @@ def test_maxwell_filter_additional():
                     rtol=1e-6, atol=1e-20)
 
     # Test rank of covariance matrices for raw and SSS processed data
-    cov_raw = compute_raw_data_covariance(raw)
-    cov_sss = compute_raw_data_covariance(raw_sss)
+    cov_raw = compute_raw_covariance(raw)
+    cov_sss = compute_raw_covariance(raw_sss)
 
     scalings = None
     cov_raw_rank = _estimate_rank_meeg_cov(cov_raw['data'], raw.info, scalings)
diff --git a/mne/preprocessing/tests/test_xdawn.py b/mne/preprocessing/tests/test_xdawn.py
index 3be444350..453ead003 100644
--- a/mne/preprocessing/tests/test_xdawn.py
+++ b/mne/preprocessing/tests/test_xdawn.py
@@ -7,7 +7,7 @@ import os.path as op
 from nose.tools import (assert_equal, assert_raises)
 from numpy.testing import assert_array_equal
 from mne import (io, Epochs, read_events, pick_types,
-                 compute_raw_data_covariance)
+                 compute_raw_covariance)
 from mne.utils import requires_sklearn, run_tests_if_main
 from mne.preprocessing.xdawn import Xdawn
 
@@ -56,7 +56,7 @@ def test_xdawn_fit():
 
     # ========== with signal cov provided ====================
     # provide covariance object
-    signal_cov = compute_raw_data_covariance(raw, picks=picks)
+    signal_cov = compute_raw_covariance(raw, picks=picks)
     xd = Xdawn(n_components=2, correct_overlap=False,
                signal_cov=signal_cov, reg=None)
     xd.fit(epochs)
diff --git a/mne/tests/test_cov.py b/mne/tests/test_cov.py
index 3f9fc1dd2..6619b047c 100644
--- a/mne/tests/test_cov.py
+++ b/mne/tests/test_cov.py
@@ -18,7 +18,7 @@ from mne.cov import (regularize, whiten_evoked, _estimate_rank_meeg_cov,
                      _undo_scaling_cov)
 
 from mne import (read_cov, write_cov, Epochs, merge_events,
-                 find_events, compute_raw_data_covariance,
+                 find_events, compute_raw_covariance,
                  compute_covariance, read_evokeds, compute_proj_raw,
                  pick_channels_cov, pick_channels, pick_types, pick_info,
                  make_ad_hoc_cov)
@@ -98,7 +98,7 @@ def test_cov_estimation_on_raw_segment():
     """
     tempdir = _TempDir()
     raw = Raw(raw_fname, preload=False)
-    cov = compute_raw_data_covariance(raw)
+    cov = compute_raw_covariance(raw)
     cov_mne = read_cov(erm_cov_fname)
     assert_true(cov_mne.ch_names == cov.ch_names)
     assert_true(linalg.norm(cov.data - cov_mne.data, ord='fro') /
@@ -113,7 +113,7 @@ def test_cov_estimation_on_raw_segment():
 
     # test with a subset of channels
     picks = pick_channels(raw.ch_names, include=raw.ch_names[:5])
-    cov = compute_raw_data_covariance(raw, picks=picks)
+    cov = compute_raw_covariance(raw, picks=picks)
     assert_true(cov_mne.ch_names[:5] == cov.ch_names)
     assert_true(linalg.norm(cov.data - cov_mne.data[picks][:, picks],
                 ord='fro') / linalg.norm(cov.data, ord='fro') < 1e-4)
@@ -121,7 +121,7 @@ def test_cov_estimation_on_raw_segment():
     raw_2 = raw.crop(0, 1)
     with warnings.catch_warnings(record=True) as w:
         warnings.simplefilter('always')
-        cov = compute_raw_data_covariance(raw_2)
+        cov = compute_raw_covariance(raw_2)
     assert_true(len(w) == 1)
 
 
@@ -264,12 +264,12 @@ def test_rank():
     raw_sss = Raw(hp_fif_fname)
     raw_sss.add_proj(compute_proj_raw(raw_sss))
 
-    cov_sample = compute_raw_data_covariance(raw_sample)
-    cov_sample_proj = compute_raw_data_covariance(
+    cov_sample = compute_raw_covariance(raw_sample)
+    cov_sample_proj = compute_raw_covariance(
         raw_sample.copy().apply_proj())
 
-    cov_sss = compute_raw_data_covariance(raw_sss)
-    cov_sss_proj = compute_raw_data_covariance(
+    cov_sss = compute_raw_covariance(raw_sss)
+    cov_sss_proj = compute_raw_covariance(
         raw_sss.copy().apply_proj())
 
     picks_all_sample = pick_types(raw_sample.info, meg=True, eeg=True)