to_data_frame API change (mne-tools#10925)

* finally do promised API change

* fix tests

* changelog

Author: drammock

doc/changes/latest.inc

@@ -148,7 +148,7 @@ Bugs
 - Fix bug in coregistration GUI that prevented it from starting up if only a high-resolution head model was available (:gh:`10543` by `Richard Höchenberger`_)
 
 - Fix bug with :class:`mne.Epochs.add_reference_channels` where attributes were not updated properly so subsequent `~mne.Epochs.pick_types` calls were broken (:gh:`10912` by `Eric Larson`_)
-- 
+-
 - Fix bug in the :class:`mne.viz.Brain` tool bar that prevented the buttons to call the corresponding feature (:gh:`10560` by `Guillaume Favelier`_)
 
 - Fix issue with saving epochs once :func:`~mne.preprocessing.compute_current_source_density` has been used if a rejection threshold was used first (:gh:`10619` by `Alex Rockhill`_ and `Richard Höchenberger`_)
@@ -201,3 +201,5 @@ API and behavior changes
 - For :func:`mne.viz.plot_topomap`, :func:`mne.viz.plot_evoked_topomap`, :func:`mne.viz.plot_arrowmap`, :func:`mne.viz.plot_ica_components`, :meth:`mne.Covariance.plot_topomap`, :meth:`mne.Evoked.plot_topomap`, :meth:`mne.Evoked.animate_topomap`, :meth:`mne.decoding.CSP.plot_patterns`, :meth:`mne.Projection.plot_topomap` and :meth:`mne.preprocessing.ICA.plot_components` the topomap image interpolation was previously a cubic interpolation but now can be ``'linear'`` and ``'nearest'`` as well. Unless ``image_interp='nearest'`` is passed mne uses a subsequent matplotlib bilinear interpolation to make the interpolated image smoother. Previously, ``'image_interp'`` controlled this second interpolation step and, for the first interpolation, the only option was cubic. To simplify, ``image_interp`` is now responsible for the main interpolation and the subsequent matplotlib image interpolation is bilinear but can be changed afterward using ``im.set_interpolation`` (:gh:`10617` by `Alex Rockhill`_)
 
 - The FLASH BEM surface generation via :func:`mne.bem.make_flash_bem` or the :ref:`mne flash_bem` command has now been clarified in terms of expected inputs. In :func:`mne.bem.convert_flash_mris` the ``convert`` parameter is now deprecated and the ``flash5`` and ``flash30`` now accept list of file names or nibabel images. One breaking change is that now the flash files are looked for as mef05_*.mgz and mef30_*.mgz in mri/flash folder (:gh:`10715` by `Alex Gramfort`_)
+
+- The ``to_data_frame`` methods for :meth:`Raw <mne.io.Raw.to_data_frame>`, :meth:`Epochs <mne.Epochs.to_data_frame>`, :meth:`Evoked <mne.Evoked.to_data_frame>`, :meth:`SourceEstimate <mne.SourceEstimate.to_data_frame>`, :meth:`EpochsTFR <mne.time_frequency.EpochsTFR.to_data_frame>`, and :meth:`AverageTFR <mne.time_frequency.AverageTFR.to_data_frame>` all now have default ``time_format=None`` (keep time in seconds) instead of ``time_format='ms'`` (convert time to milliseconds) (:gh:`10925` by `Daniel McCloy`_)

mne/epochs.py

@@ -2119,7 +2119,7 @@ def equalize_event_counts(self, event_ids=None, method='mintime'):
     @verbose
     def to_data_frame(self, picks=None, index=None,
                       scalings=None, copy=True, long_format=False,
-                      time_format='ms', *, verbose=None):
+                      time_format=None, *, verbose=None):
         """Export data in tabular structure as a pandas DataFrame.
 
         Channels are converted to columns in the DataFrame. By default,

mne/evoked.py

@@ -811,7 +811,7 @@ def get_peak(self, ch_type=None, tmin=None, tmax=None,
     @verbose
     def to_data_frame(self, picks=None, index=None,
                       scalings=None, copy=True, long_format=False,
-                      time_format='ms', *, verbose=None):
+                      time_format=None, *, verbose=None):
         """Export data in tabular structure as a pandas DataFrame.
 
         Channels are converted to columns in the DataFrame. By default,

mne/io/base.py

@@ -1902,7 +1902,7 @@ def _get_buffer_size(self, buffer_size_sec=None):
     @verbose
     def to_data_frame(self, picks=None, index=None,
                       scalings=None, copy=True, start=None, stop=None,
-                      long_format=False, time_format='ms', *,
+                      long_format=False, time_format=None, *,
                       verbose=None):
         """Export data in tabular structure as a pandas DataFrame.
 

mne/io/edf/tests/test_edf.py

@@ -276,7 +276,7 @@ def test_to_data_frame(fname):
     _, times = raw[0, :10]
     df = raw.to_data_frame(index='time')
     assert (df.columns == raw.ch_names).all()
-    assert_array_equal(np.round(times * 1e3), df.index.values[:10])
+    assert_array_equal(times, df.index.values[:10])
     df = raw.to_data_frame(index=None, scalings={'eeg': 1e13})
     assert 'time' in df.columns
     assert_array_equal(df.values[:, 1], raw._data[0] * 1e13)

mne/io/fiff/tests/test_raw_fiff.py

@@ -1284,10 +1284,8 @@ def test_to_data_frame():
     """Test raw Pandas exporter."""
     from pandas import Timedelta
     raw = read_raw_fif(test_fif_fname).crop(0, 1).load_data()
-    _, times = raw[0, :10]
     df = raw.to_data_frame(index='time')
     assert ((df.columns == raw.ch_names).all())
-    assert_array_equal(np.round(times * 1e3), df.index.values[:10])
     df = raw.to_data_frame(index=None)
     assert ('time' in df.columns)
     assert_array_equal(df.values[:, 1], raw._data[0] * 1e13)
@@ -1311,13 +1309,27 @@ def test_to_data_frame():
 @pytest.mark.parametrize('time_format', (None, 'ms', 'timedelta', 'datetime'))
 def test_to_data_frame_time_format(time_format):
     """Test time conversion in epochs Pandas exporter."""
-    from pandas import Timedelta, Timestamp
+    from pandas import Timedelta, Timestamp, to_timedelta
     raw = read_raw_fif(test_fif_fname, preload=True)
     # test time_format
     df = raw.to_data_frame(time_format=time_format)
     dtypes = {None: np.float64, 'ms': np.int64, 'timedelta': Timedelta,
               'datetime': Timestamp}
     assert isinstance(df['time'].iloc[0], dtypes[time_format])
+    # test values
+    _, times = raw[0, :10]
+    offset = 0.
+    if time_format == 'datetime':
+        times += raw.first_time
+        offset = raw.info['meas_date']
+    elif time_format == 'timedelta':
+        offset = Timedelta(0.)
+    funcs = {None: lambda x: x,
+             'ms': lambda x: np.rint(x * 1e3).astype(int),  # s → ms
+             'timedelta': partial(to_timedelta, unit='s'),
+             'datetime': partial(to_timedelta, unit='s')
+             }
+    assert_array_equal(funcs[time_format](times) + offset, df['time'][:10])
 
 
 def test_add_channels():

mne/source_estimate.py

@@ -1202,7 +1202,7 @@ def transform(self, func, idx=None, tmin=None, tmax=None, copy=False):
 
     @verbose
     def to_data_frame(self, index=None, scalings=None,
-                      long_format=False, time_format='ms', *,
+                      long_format=False, time_format=None, *,
                       verbose=None):
         """Export data in tabular structure as a pandas DataFrame.
 

mne/time_frequency/tests/test_tfr.py

@@ -1062,8 +1062,8 @@ def test_to_data_frame():
     assert_array_equal(df.values[:, 0],
                        data[:, 0, :, :].reshape(1, -1).squeeze())
     # compare arbitrary observation:
-    assert df.loc[('he', slice(None), freqs[1], times[2] * srate),
-                  ch_names[3]].iloc[0] == data[1, 3, 1, 2]
+    assert (df.loc[('he', slice(None), freqs[1], times[2]), ch_names[3]].iat[0]
+            == data[1, 3, 1, 2])
 
     # Check also for AverageTFR:
     tfr = tfr.average()
@@ -1092,8 +1092,7 @@ def test_to_data_frame():
     assert_array_equal(df.values[:, 0],
                        data[0, :, :].reshape(1, -1).squeeze())
     # compare arbitrary observation:
-    assert df.loc[(freqs[1], times[2] * srate), ch_names[3]] == \
-        data[3, 1, 2]
+    assert df.loc[(freqs[1], times[2]), ch_names[3]] == data[3, 1, 2]
 
 
 @requires_pandas

mne/time_frequency/tfr.py

@@ -1034,7 +1034,7 @@ def save(self, fname, overwrite=False, *, verbose=None):
 
     @verbose
     def to_data_frame(self, picks=None, index=None, long_format=False,
-                      time_format='ms', *, verbose=None):
+                      time_format=None, *, verbose=None):
         """Export data in tabular structure as a pandas DataFrame.
 
         Channels are converted to columns in the DataFrame. By default,

mne/utils/docs.py

@@ -3223,9 +3223,8 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
     remain as float values in seconds. If ``'ms'``, time values will be rounded
     to the nearest millisecond and converted to integers. If ``'timedelta'``,
     time values will be converted to :class:`pandas.Timedelta` values. {}
-    Default is ``'ms'`` in version 0.22, and will change to ``None`` in
-    version 0.23.
-"""  # XXX make sure we deal with this deprecation in 0.23
+    Default is ``None``.
+"""
 
 docdict['time_format_df'] = _time_format_df_base.format('')