MRG: Expand ~ in _check_fname()

doc/changes/latest.inc

@@ -191,6 +191,10 @@ Enhancements
 
 - Add :func:`mne.preprocessing.ieeg.project_sensors_onto_brain` to project ECoG sensors onto the pial surface to compensate for brain shift (:gh:`9800` by `Alex Rockhill`_)
 
+- All functions for reading and writing files should now automatically handle ``~`` (the tilde character) and expand it to the user's home directory. Should you come across any function that doesn't do it, please do let us know! (:gh:`9613` by `Richard Höchenberger`_)
+
+- All functions accepting a FreeSurfer subjects directory via a ``subjects_dir`` parameter can now consume :py:class:`pathlib.Path` objects too (used to be only strings) (:gh:`9613` by `Richard Höchenberger`_)
+
 Bugs
 ~~~~
 - Fix bug in :meth:`mne.io.Raw.pick` and related functions when parameter list contains channels which are not in info instance (:gh:`9708` **by new contributor** |Evgeny Goldstein|_)

mne/cov.py

@@ -38,7 +38,7 @@
                     warn, copy_function_doc_to_method_doc, _pl,
                     _undo_scaling_cov, _scaled_array, _validate_type,
                     _check_option, eigh, fill_doc, _on_missing,
-                    _check_on_missing)
+                    _check_on_missing, _check_fname)
 from . import viz
 
 from .fixes import (BaseEstimator, EmpiricalCovariance, _logdet,
@@ -153,7 +153,8 @@ def save(self, fname):
         """
         check_fname(fname, 'covariance', ('-cov.fif', '-cov.fif.gz',
                                           '_cov.fif', '_cov.fif.gz'))
-
+        # TODO: Add `overwrite` param to method signature
+        fname = _check_fname(fname=fname, overwrite=True)
         fid = start_file(fname)
 
         try:
@@ -384,6 +385,7 @@ def read_cov(fname, verbose=None):
     """
     check_fname(fname, 'covariance', ('-cov.fif', '-cov.fif.gz',
                                       '_cov.fif', '_cov.fif.gz'))
+    fname = _check_fname(fname=fname, must_exist=True, overwrite='read')
     f, tree = fiff_open(fname)[:2]
     with f as fid:
         return Covariance(**_read_cov(fid, tree, FIFF.FIFFV_MNE_NOISE_COV,

mne/epochs.py

@@ -59,7 +59,8 @@
                     _check_combine, ShiftTimeMixin, _build_data_frame,
                     _check_pandas_index_arguments, _convert_times,
                     _scale_dataframe_data, _check_time_format, object_size,
-                    _on_missing, _validate_type, _ensure_events)
+                    _on_missing, _validate_type, _ensure_events,
+                    _path_like)
 from .utils.docs import fill_doc
 from .data.html_templates import epochs_template
 
@@ -1738,8 +1739,8 @@ def save(self, fname, split_size='2GB', fmt='single', overwrite=False,
         Parameters
         ----------
         fname : str
-            The name of the file, which should end with -epo.fif or
-            -epo.fif.gz.
+            The name of the file, which should end with ``-epo.fif`` or
+            ``-epo.fif.gz``.
         split_size : str | int
             Large raw files are automatically split into multiple pieces. This
             parameter specifies the maximum size of each piece. If the
@@ -1771,8 +1772,8 @@ def save(self, fname, split_size='2GB', fmt='single', overwrite=False,
         check_fname(fname, 'epochs', ('-epo.fif', '-epo.fif.gz',
                                       '_epo.fif', '_epo.fif.gz'))
 
-        # check for file existence
-        _check_fname(fname, overwrite)
+        # check for file existence and expand `~` if present
+        fname = _check_fname(fname=fname, overwrite=overwrite)
 
         split_size_bytes = _get_split_size(split_size)
 
@@ -3059,14 +3060,11 @@ def read_epochs(fname, proj=True, preload=True, verbose=None):
 
     Parameters
     ----------
-    fname : str | file-like
-        The epochs filename to load. Filename should end with -epo.fif or
-        -epo.fif.gz. If a file-like object is provided, preloading must be
-        used.
+    %(epochs_fname)s
     %(proj_epochs)s
     preload : bool
-        If True, read all epochs from disk immediately. If False, epochs will
-        be read on demand.
+        If True, read all epochs from disk immediately. If ``False``, epochs
+        will be read on demand.
     %(verbose)s
 
     Returns
@@ -3100,9 +3098,7 @@ class EpochsFIF(BaseEpochs):
 
     Parameters
     ----------
-    fname : str | file-like
-        The name of the file, which should end with -epo.fif or -epo.fif.gz. If
-        a file-like object is provided, preloading must be used.
+    %(epochs_fname)s
     %(proj_epochs)s
     preload : bool
         If True, read all epochs from disk immediately. If False, epochs will
@@ -3119,9 +3115,13 @@ class EpochsFIF(BaseEpochs):
     @verbose
     def __init__(self, fname, proj=True, preload=True,
                  verbose=None):  # noqa: D102
-        if isinstance(fname, str):
-            check_fname(fname, 'epochs', ('-epo.fif', '-epo.fif.gz',
-                                          '_epo.fif', '_epo.fif.gz'))
+        if _path_like(fname):
+            check_fname(
+                fname=fname, filetype='epochs',
+                endings=('-epo.fif', '-epo.fif.gz', '_epo.fif', '_epo.fif.gz')
+            )
+            fname = _check_fname(fname=fname, must_exist=True,
+                                 overwrite='read')
         elif not preload:
             raise ValueError('preload must be used with file-like objects')
 

mne/evoked.py

@@ -22,7 +22,7 @@
                     fill_doc, _check_option, ShiftTimeMixin, _build_data_frame,
                     _check_pandas_installed, _check_pandas_index_arguments,
                     _convert_times, _scale_dataframe_data, _check_time_format,
-                    _check_preload)
+                    _check_preload, _check_fname)
 from .viz import (plot_evoked, plot_evoked_topomap, plot_evoked_field,
                   plot_evoked_image, plot_evoked_topo)
 from .viz.evoked import plot_evoked_white, plot_evoked_joint
@@ -127,6 +127,7 @@ def __init__(self, fname, condition=None, proj=True,
                  verbose=None):  # noqa: D102
         _validate_type(proj, bool, "'proj'")
         # Read the requested data
+        fname = _check_fname(fname=fname, must_exist=True, overwrite='read')
         self.info, self.nave, self._aspect_kind, self.comment, self.times, \
             self.data, self.baseline = _read_evoked(fname, condition, kind,
                                                     allow_maxshield)
@@ -278,7 +279,7 @@ def apply_baseline(self, baseline=(None, 0), *, verbose=None):
         return self
 
     def save(self, fname):
-        """Save dataset to file.
+        """Save evoked data to a file.
 
         Parameters
         ----------
@@ -295,6 +296,8 @@ def save(self, fname):
             Information on baseline correction will be stored with the data,
             and will be restored when reading again via `mne.read_evokeds`.
         """
+        # TODO: Add `overwrite` param to method signature
+        fname = _check_fname(fname=fname, overwrite=True)
         write_evokeds(fname, self)
 
     def __repr__(self):  # noqa: D105
@@ -1398,6 +1401,8 @@ def _write_evokeds(fname, evoked, check=True, *, on_mismatch='raise'):
     if check:
         check_fname(fname, 'evoked', ('-ave.fif', '-ave.fif.gz',
                                       '_ave.fif', '_ave.fif.gz'))
+    # TODO: Add `overwrite` param to method signature
+    fname = _check_fname(fname=fname, overwrite=True)
 
     if not isinstance(evoked, (list, tuple)):
         evoked = [evoked]

mne/forward/forward.py

@@ -437,7 +437,7 @@ def read_forward_solution(fname, include=(), exclude=(), verbose=None):
     """
     check_fname(fname, 'forward', ('-fwd.fif', '-fwd.fif.gz',
                                    '_fwd.fif', '_fwd.fif.gz'))
-
+    fname = _check_fname(fname=fname, must_exist=True, overwrite='read')
     #   Open the file, create directory
     logger.info('Reading forward solution from %s...' % fname)
     f, tree, _ = fiff_open(fname)
@@ -718,8 +718,8 @@ def write_forward_solution(fname, fwd, overwrite=False, verbose=None):
     Parameters
     ----------
     fname : str
-        File name to save the forward solution to. It should end with -fwd.fif
-        or -fwd.fif.gz.
+        File name to save the forward solution to. It should end with
+        ``-fwd.fif`` or ``-fwd.fif.gz``.
     fwd : Forward
         Forward solution.
     %(overwrite)s
@@ -747,8 +747,8 @@ def write_forward_solution(fname, fwd, overwrite=False, verbose=None):
     check_fname(fname, 'forward', ('-fwd.fif', '-fwd.fif.gz',
                                    '_fwd.fif', '_fwd.fif.gz'))
 
-    # check for file existence
-    _check_fname(fname, overwrite)
+    # check for file existence and expand `~` if present
+    fname = _check_fname(fname, overwrite)
     fid = start_file(fname)
     start_block(fid, FIFF.FIFFB_MNE)
 

mne/io/base.py

@@ -1416,7 +1416,6 @@ def save(self, fname, picks=None, tmin=0, tmax=None, buffer_size_sec=None,
         or all forms of SSS). It is recommended not to concatenate and
         then save raw files for this reason.
         """
-        fname = op.abspath(fname)
         endings = ('raw.fif', 'raw_sss.fif', 'raw_tsss.fif',
                    '_meg.fif', '_eeg.fif', '_ieeg.fif')
         endings += tuple([f'{e}.gz' for e in endings])
@@ -1447,8 +1446,8 @@ def save(self, fname, picks=None, tmin=0, tmax=None, buffer_size_sec=None,
             raise ValueError('Complex data must be saved as "single" or '
                              '"double", not "short"')
 
-        # check for file existence
-        _check_fname(fname, overwrite)
+        # check for file existence and expand `~` if present
+        fname = _check_fname(fname=fname, overwrite=overwrite)
 
         if proj:
             info = deepcopy(self.info)
@@ -2148,6 +2147,9 @@ def _write_raw(fname, raw, info, picks, fmt, data_type, reset_range, start,
         raise RuntimeError('Cannot write raw file with no data: %s -> %s '
                            '(max: %s) requested' % (start, stop, n_times_max))
 
+    # Expand `~` if present
+    fname = _check_fname(fname=fname, overwrite=overwrite)
+
     base, ext = op.splitext(fname)
     if part_idx > 0:
         if split_naming == 'neuromag':
@@ -2181,7 +2183,9 @@ def _write_raw(fname, raw, info, picks, fmt, data_type, reset_range, start,
             raw, info, picks, fid, cals, part_idx, start, stop,
             buffer_size, prev_fname, split_size, use_fname,
             projector, drop_small_buffer, fmt, fname, reserved_fname,
-            data_type, reset_range, split_naming, overwrite)
+            data_type, reset_range, split_naming,
+            overwrite=True  # we've started writing already above
+        )
     if final_fname != use_fname:
         assert split_naming == 'bids'
         logger.info(f'Renaming BIDS split file {op.basename(final_fname)}')

mne/io/eeglab/eeglab.py

@@ -446,6 +446,8 @@ def __init__(self, input_fname, events=None, event_id=None, tmin=0,
                  baseline=None, reject=None, flat=None, reject_tmin=None,
                  reject_tmax=None, eog=(), verbose=None,
                  uint16_codec=None):  # noqa: D102
+        input_fname = _check_fname(fname=input_fname, must_exist=True,
+                                   overwrite='read')
         eeg = _check_load_mat(input_fname, uint16_codec)
 
         if not ((events is None and event_id is None) or
@@ -507,7 +509,6 @@ def __init__(self, input_fname, events=None, event_id=None, tmin=0,
             events = read_events(events)
 
         logger.info('Extracting parameters from %s...' % input_fname)
-        input_fname = op.abspath(input_fname)
         info, eeg_montage, _ = _get_info(eeg, eog=eog)
 
         for key, val in event_id.items():

mne/io/fiff/tests/test_raw_fiff.py

@@ -5,6 +5,7 @@
 # License: BSD-3-Clause
 
 from copy import deepcopy
+from pathlib import Path
 from functools import partial
 from io import BytesIO
 import os
@@ -1786,3 +1787,22 @@ def test_corrupted(tmpdir):
     with pytest.warns(RuntimeWarning, match='.*tag directory.*corrupt.*'):
         raw_bad = read_raw_fif(bad_fname)
     assert_allclose(raw.get_data(), raw_bad.get_data())
+
+
+@testing.requires_testing_data
+def test_expand_user(tmp_path, monkeypatch):
+    """Test that we're expanding `~` before reading and writing."""
+    monkeypatch.setenv('HOME', str(tmp_path))
+    monkeypatch.setenv('USERPROFILE', str(tmp_path))  # Windows
+
+    path_in = Path(fif_fname)
+    path_out = tmp_path / path_in.name
+    path_home = Path('~') / path_in.name
+
+    shutil.copyfile(
+        src=path_in,
+        dst=path_out
+    )
+
+    raw = read_raw_fif(fname=path_home, preload=True)
+    raw.save(fname=path_home, overwrite=True)

mne/io/kit/kit.py

@@ -17,7 +17,7 @@
 
 from ..pick import pick_types
 from ...utils import (verbose, logger, warn, fill_doc, _check_option,
-                      _stamp_to_dt)
+                      _stamp_to_dt, _check_fname)
 from ...transforms import apply_trans, als_ras_trans
 from ..base import BaseRaw
 from ..utils import _mult_cal_one
@@ -386,8 +386,9 @@ def __init__(self, input_fname, events, event_id=None, tmin=0,
         if isinstance(events, str):
             events = read_events(events)
 
+        input_fname = _check_fname(fname=input_fname, must_exist=True,
+                                   overwrite='read')
         logger.info('Extracting KIT Parameters from %s...' % input_fname)
-        input_fname = op.abspath(input_fname)
         self.info, kit_info = get_kit_info(
             input_fname, allow_unknown_format, standardize_names)
         kit_info.update(filename=input_fname)

mne/minimum_norm/inverse.py

@@ -41,9 +41,10 @@
 from ..source_estimate import _make_stc, _get_src_type
 from ..utils import (check_fname, logger, verbose, warn, _validate_type,
                      _check_compensation_grade, _check_option,
-                     _check_depth, _check_src_normal)
+                     _check_depth, _check_src_normal, _check_fname)
 from ..data.html_templates import inverse_operator_template
 
+
 INVERSE_METHODS = ('MNE', 'dSPM', 'sLORETA', 'eLORETA')
 
 
@@ -132,7 +133,7 @@ def read_inverse_operator(fname, verbose=None):
     """
     check_fname(fname, 'inverse operator', ('-inv.fif', '-inv.fif.gz',
                                             '_inv.fif', '_inv.fif.gz'))
-
+    fname = _check_fname(fname=fname, must_exist=True, overwrite='read')
     #
     #   Open the file, create directory
     #
@@ -350,6 +351,8 @@ def write_inverse_operator(fname, inv, verbose=None):
     """
     check_fname(fname, 'inverse operator', ('-inv.fif', '-inv.fif.gz',
                                             '_inv.fif', '_inv.fif.gz'))
+    fname = _check_fname(fname=fname, overwrite=True)
+
     _validate_type(inv, InverseOperator, 'inv')
 
     #

mne/report/report.py

@@ -37,7 +37,7 @@
 from .._freesurfer import _reorient_image, _mri_orientation
 from ..utils import (logger, verbose, get_subjects_dir, warn, _ensure_int,
                      fill_doc, _check_option, _validate_type, _safe_input,
-                     _check_path_like, use_log_level, deprecated)
+                     _path_like, use_log_level, deprecated)
 from ..viz import (plot_events, plot_alignment, plot_cov, plot_projs_topomap,
                    plot_compare_evokeds, set_3d_view, get_3d_backend)
 from ..viz.misc import _plot_mri_contours, _get_bem_plotting_surfaces
@@ -1498,7 +1498,7 @@ def add_figure(self, fig, title, *, caption=None, image_format=None,
             figs = (fig,)
 
         for fig in figs:
-            if _check_path_like(fig):
+            if _path_like(fig):
                 raise TypeError(
                     f'It seems you passed a path to `add_figure`. However, '
                     f'only Matplotlib figures, Mayavi scenes, and NumPy '
@@ -1582,9 +1582,9 @@ def add_figs_to_section(self, figs, captions, section='custom',
         _check_scale(scale)
 
         if (
-            _check_path_like(figs) or
+            _path_like(figs) or
             (hasattr(figs, '__iter__') and
-             any(_check_path_like(f) for f in figs))
+             any(_path_like(f) for f in figs))
         ):
             raise TypeError(
                 'It seems you passed a path to `add_figs_to_section`. '

mne/report/tests/test_report.py

@@ -466,8 +466,9 @@ def test_add_html():
     assert (repr(report))
 
 
+@testing.requires_testing_data
 def test_multiple_figs(tmpdir):
-    """Test adding a slider with a series of figures to mne report."""
+    """Test adding a slider with a series of figures to a Report."""
     tempdir = str(tmpdir)
     report = Report(info_fname=raw_fname,
                     subject='sample', subjects_dir=subjects_dir)