MRG: Add argument overwrite to export for raws and epochs to match save.

doc/changes/latest.inc

@@ -38,6 +38,8 @@ Bugs
 
 - Fix bug in :func:`mne.make_forward_solution` where sensor-sphere geometry check was incorrect (:gh:`9968` by `Eric Larson`_)
 
+- Add argument ``overwrite`` to :func:`mne.export.export_raw`, :func:`mne.export.export_epochs`, :func:`mne.export.export_evokeds` and :func:`mne.export.export_evokeds_mff` (:gh:`9975` by `Mathieu Scheltienne`_)
+
 - :func:`mne.gui.coregistration` and the ``mne coreg`` command didn't respect the ``inspect`` parameter (:gh:`9972` by `Richard Höchenberger`_)
 
 API changes

mne/epochs.py

@@ -1914,7 +1914,7 @@ def save(self, fname, split_size='2GB', fmt='single', overwrite=False,
                         split_naming, overwrite)
 
     @verbose
-    def export(self, fname, fmt='auto', verbose=None):
+    def export(self, fname, fmt='auto', *, overwrite=False, verbose=None):
         """Export Epochs to external formats.
 
         Supported formats: EEGLAB (set, uses :mod:`eeglabio`)
@@ -1924,14 +1924,17 @@ def export(self, fname, fmt='auto', verbose=None):
         ----------
         %(export_params_fname)s
         %(export_params_fmt)s
+        %(overwrite)s
+
+            .. versionadded:: 0.24.1
         %(verbose)s
 
         Notes
         -----
         %(export_eeglab_note)s
         """
         from .export import export_epochs
-        export_epochs(fname, self, fmt, verbose)
+        export_epochs(fname, self, fmt, overwrite=overwrite, verbose=verbose)
 
     def equalize_event_counts(self, event_ids=None, method='mintime'):
         """Equalize the number of trials in each condition.

mne/export/_egimff.py

@@ -3,17 +3,21 @@
 #
 # License: BSD-3-Clause
 
+import os
+import shutil
 import datetime
+import os.path as op
 
 import numpy as np
 
 from ..io.egi.egimff import _import_mffpy
 from ..io.pick import pick_types, pick_channels
-from ..utils import verbose
+from ..utils import verbose, _check_fname
 
 
 @verbose
-def export_evokeds_mff(fname, evoked, history=None, *, verbose=None):
+def export_evokeds_mff(fname, evoked, history=None, *, overwrite=False,
+                       verbose=None):
     """Export evoked dataset to MFF.
 
     Parameters
@@ -28,6 +32,9 @@ def export_evokeds_mff(fname, evoked, history=None, *, verbose=None):
         history.xml. This must adhere to the format described in
         mffpy.xml_files.History.content. If None, no history.xml will be
         written.
+    %(overwrite)s
+
+        .. versionadded:: 0.24.1
     %(verbose)s
 
     Notes
@@ -48,6 +55,11 @@ def export_evokeds_mff(fname, evoked, history=None, *, verbose=None):
     sampling_rate = int(info['sfreq'])
 
     # Initialize writer
+    # Future changes: conditions based on version or mffpy requirement if
+    # https://github.com/BEL-Public/mffpy/pull/92 is merged and released.
+    fname = _check_fname(fname, overwrite=overwrite)
+    if op.exists(fname):
+        os.remove(fname) if op.isfile(fname) else shutil.rmtree(fname)
     writer = mffpy.Writer(fname)
     current_time = pytz.utc.localize(datetime.datetime.utcnow())
     writer.addxml('fileInfo', recordTime=current_time)

mne/export/_export.py

@@ -6,12 +6,12 @@
 import os.path as op
 
 from ._egimff import export_evokeds_mff
-from ..utils import verbose, logger, _validate_type
+from ..utils import verbose, logger, _validate_type, _check_fname
 
 
 @verbose
 def export_raw(fname, raw, fmt='auto', physical_range='auto',
-               add_ch_type=False, verbose=None):
+               add_ch_type=False, *, overwrite=False, verbose=None):
     """Export Raw to external formats.
 
     Supported formats:
@@ -27,13 +27,17 @@ def export_raw(fname, raw, fmt='auto', physical_range='auto',
     %(export_params_fmt)s
     %(export_params_physical_range)s
     %(export_params_add_ch_type)s
+    %(overwrite)s
+
+        .. versionadded:: 0.24.1
     %(verbose)s
 
     Notes
     -----
     %(export_eeglab_note)s
     %(export_edf_note)s
     """
+    fname = _check_fname(fname, overwrite=overwrite)
     supported_export_formats = {  # format : extensions
         'eeglab': ('set',),
         'edf': ('edf',),
@@ -52,7 +56,7 @@ def export_raw(fname, raw, fmt='auto', physical_range='auto',
 
 
 @verbose
-def export_epochs(fname, epochs, fmt='auto', verbose=None):
+def export_epochs(fname, epochs, fmt='auto', *, overwrite=False, verbose=None):
     """Export Epochs to external formats.
 
     Supported formats: EEGLAB (set, uses :mod:`eeglabio`)
@@ -64,12 +68,16 @@ def export_epochs(fname, epochs, fmt='auto', verbose=None):
     epochs : instance of Epochs
         The epochs to export.
     %(export_params_fmt)s
+    %(overwrite)s
+
+        .. versionadded:: 0.24.1
     %(verbose)s
 
     Notes
     -----
     %(export_eeglab_note)s
     """
+    fname = _check_fname(fname, overwrite=overwrite)
     supported_export_formats = {
         'eeglab': ('set',),
         'edf': ('edf',),
@@ -87,7 +95,8 @@ def export_epochs(fname, epochs, fmt='auto', verbose=None):
 
 
 @verbose
-def export_evokeds(fname, evoked, fmt='auto', verbose=None):
+def export_evokeds(fname, evoked, fmt='auto', *, overwrite=False,
+                   verbose=None):
     """Export evoked dataset to external formats.
 
     This function is a wrapper for format-specific export functions. The export
@@ -109,6 +118,9 @@ def export_evokeds(fname, evoked, fmt='auto', verbose=None):
         Format of the export. Defaults to ``'auto'``, which will infer the
         format from the filename extension. See supported formats above for
         more information.
+    %(overwrite)s
+
+        .. versionadded:: 0.24.1
     %(verbose)s
 
     See Also
@@ -120,6 +132,7 @@ def export_evokeds(fname, evoked, fmt='auto', verbose=None):
     -----
     .. versionadded:: 0.24
     """
+    fname = _check_fname(fname, overwrite=overwrite)
     supported_export_formats = {
         'mff': ('mff',),
         'eeglab': ('set',),
@@ -134,7 +147,7 @@ def export_evokeds(fname, evoked, fmt='auto', verbose=None):
     logger.info(f'Exporting evoked dataset to {fname}...')
 
     if fmt == 'mff':
-        export_evokeds_mff(fname, evoked)
+        export_evokeds_mff(fname, evoked, overwrite=overwrite)
     elif fmt == 'eeglab':
         raise NotImplementedError('Export to EEGLAB not implemented.')
     elif fmt == 'edf':

mne/export/tests/test_export.py

@@ -51,6 +51,14 @@ def test_export_raw_eeglab(tmp_path):
     assert_allclose(raw.times, raw_read.times)
     assert_allclose(raw.get_data(), raw_read.get_data())
 
+    # test overwrite
+    with pytest.raises(FileExistsError, match='Destination file exists'):
+        raw.export(temp_fname, overwrite=False)
+    raw.export(temp_fname, overwrite=True)
+
+    # test pathlib.Path files
+    raw.export(Path(temp_fname), overwrite=True)
+
 
 @pytest.mark.skipif(not _check_edflib_installed(strict=False),
                     reason='edflib-python not installed')
@@ -78,7 +86,7 @@ def test_double_export_edf(tmp_path):
 
     # export again
     raw_read.load_data()
-    raw_read.export(temp_fname, add_ch_type=True)
+    raw_read.export(temp_fname, add_ch_type=True, overwrite=True)
     raw_read = read_raw_edf(temp_fname, preload=True)
 
     # stim channel should be dropped
@@ -180,28 +188,28 @@ def test_rawarray_edf(tmp_path):
     raw_bad.rename_channels({'1': 'abcdefghijklmnopqrstuvwxyz'})
     with pytest.raises(RuntimeError, match='Signal label'), \
             pytest.warns(RuntimeWarning, match='Data has a non-integer'):
-        raw_bad.export(temp_fname)
+        raw_bad.export(temp_fname, overwrite=True)
 
     # include bad birthday that is non-EDF compliant
     bad_info = info.copy()
     bad_info['subject_info']['birthday'] = (1700, 1, 20)
     raw = RawArray(data, bad_info)
     with pytest.raises(RuntimeError, match='Setting patient birth date'):
-        raw.export(temp_fname)
+        raw.export(temp_fname, overwrite=True)
 
     # include bad measurement date that is non-EDF compliant
     raw = RawArray(data, info)
     meas_date = datetime(year=1984, month=1, day=1, tzinfo=timezone.utc)
     raw.set_meas_date(meas_date)
     with pytest.raises(RuntimeError, match='Setting start date time'):
-        raw.export(temp_fname)
+        raw.export(temp_fname, overwrite=True)
 
     # test that warning is raised if there are non-voltage based channels
     raw = RawArray(data, info)
     with pytest.warns(RuntimeWarning, match='The unit'):
         raw.set_channel_types({'9': 'hbr'})
     with pytest.warns(RuntimeWarning, match='Non-voltage channels'):
-        raw.export(temp_fname)
+        raw.export(temp_fname, overwrite=True)
 
     # data should match up to the non-accepted channel
     raw_read = read_raw_edf(temp_fname, preload=True)
@@ -313,6 +321,14 @@ def test_export_epochs_eeglab(tmp_path, preload):
     assert_allclose(epochs.times, epochs_read.times)
     assert_allclose(epochs.get_data(), epochs_read.get_data())
 
+    # test overwrite
+    with pytest.raises(FileExistsError, match='Destination file exists'):
+        epochs.export(temp_fname, overwrite=False)
+    epochs.export(temp_fname, overwrite=True)
+
+    # test pathlib.Path files
+    epochs.export(Path(temp_fname), overwrite=True)
+
 
 @requires_version('mffpy', '0.5.7')
 @testing.requires_testing_data
@@ -355,6 +371,20 @@ def test_export_evokeds_to_mff(tmp_path, fmt, do_history):
         assert ave_exported.comment == ave.comment
         assert_allclose(ave_exported.times, ave.times)
 
+    # test overwrite
+    with pytest.raises(FileExistsError, match='Destination file exists'):
+        if do_history:
+            export_evokeds_mff(export_fname, evoked, history=history,
+                               overwrite=False)
+        else:
+            export_evokeds(export_fname, evoked, overwrite=False)
+
+    if do_history:
+        export_evokeds_mff(export_fname, evoked, history=history,
+                           overwrite=True)
+    else:
+        export_evokeds(export_fname, evoked, overwrite=True)
+
 
 @requires_version('mffpy', '0.5.7')
 @testing.requires_testing_data

mne/io/base.py

@@ -1478,7 +1478,7 @@ def save(self, fname, picks=None, tmin=0, tmax=None, buffer_size_sec=None,
 
     @verbose
     def export(self, fname, fmt='auto', physical_range='auto',
-               add_ch_type=False, verbose=None):
+               add_ch_type=False, *, overwrite=False, verbose=None):
         """Export Raw to external formats.
 
         Supported formats: EEGLAB (set, uses :mod:`eeglabio`)
@@ -1490,6 +1490,9 @@ def export(self, fname, fmt='auto', physical_range='auto',
         %(export_params_fmt)s
         %(export_params_physical_range)s
         %(export_params_add_ch_type)s
+        %(overwrite)s
+
+            .. versionadded:: 0.24.1
         %(verbose)s
 
         Notes
@@ -1499,7 +1502,8 @@ def export(self, fname, fmt='auto', physical_range='auto',
         """
         from ..export import export_raw
         export_raw(fname, self, fmt, physical_range=physical_range,
-                   add_ch_type=add_ch_type, verbose=verbose)
+                   add_ch_type=add_ch_type, overwrite=overwrite,
+                   verbose=verbose)
 
     def _tmin_tmax_to_start_stop(self, tmin, tmax):
         start = int(np.floor(tmin * self.info['sfreq']))