Fix docstrings by replacing str with path-like and fix double backtic…

…ks for formatting (mne-tools#11499)

Co-authored-by: Richard Höchenberger <[email protected]>

doc/changes/latest.inc

@@ -51,6 +51,7 @@ Bugs
 - Fix configuration folder discovery on Windows, which would fail in certain edge cases; and produce a helpful error message if discovery still fails (:gh:`11441` by `Richard Höchenberger`_)
 - Make :class:`~mne.decoding.SlidingEstimator` and :class:`~mne.decoding.GeneralizingEstimator` respect the ``verbose`` argument. Now with ``verbose=False``, the progress bar is not shown during fitting, scoring, etc. (:gh:`11450` by `Mikołaj Magnuski`_)
 - Fix bug with :func:`mne.gui.locate_ieeg` where Freesurfer ``?h.pial.T1`` was not recognized and suppress excess logging (:gh:`11489` by `Alex Rockhill`_)
+- All functions accepting paths can now correctly handle :class:`~pathlib.Path` as input. Historically, we expected strings (instead of "proper" path objects), and only added :class:`~pathlib.Path` support in a few select places, leading to inconsistent behavior. (:gh:`11473` and :gh:`11499` by `Mathieu Scheltienne`_)
 
 API changes
 ~~~~~~~~~~~

mne/annotations.py

@@ -1146,7 +1146,7 @@ def _read_annotations_csv(fname):
 
     Parameters
     ----------
-    fname : str
+    fname : path-like
         The filename.
 
     Returns
@@ -1181,7 +1181,7 @@ def _read_brainstorm_annotations(fname, orig_time=None):
 
     Parameters
     ----------
-    fname : str
+    fname : path-like
         The filename
     orig_time : float | int | instance of datetime | array of int | None
         A POSIX Timestamp, datetime or an array containing the timestamp as the
@@ -1408,7 +1408,7 @@ def events_from_annotations(raw, event_id="auto",
     ----------
     raw : instance of Raw
         The raw data for which Annotations are defined.
-    event_id : dict | callable | None | 'auto'
+    event_id : dict | callable | None | ``'auto'``
         Can be:
 
         - **dict**: map descriptions (keys) to integer event codes (values).

mne/beamformer/_compute_beamformer.py

@@ -455,7 +455,7 @@ def save(self, fname, overwrite=False, verbose=None):
 
         Parameters
         ----------
-        fname : str
+        fname : path-like
             The filename to use to write the HDF5 data.
             Should end in ``'-lcmv.h5'`` or ``'-dics.h5'``.
         %(overwrite)s
@@ -481,7 +481,7 @@ def read_beamformer(fname):
 
     Parameters
     ----------
-    fname : str
+    fname : path-like
         The filename of the HDF5 file.
 
     Returns

mne/bem.py

@@ -447,7 +447,7 @@ def make_bem_solution(surfs, *, solver='mne', verbose=None):
     surfs : list of dict
         The BEM surfaces to use (from :func:`mne.make_bem_model`).
     solver : str
-        Can be 'mne' (default) to use MNE-Python, or 'openmeeg' to use
+        Can be ``'mne'`` (default) to use MNE-Python, or ``'openmeeg'`` to use
         the :doc:`OpenMEEG <openmeeg:index>` package.
 
         .. versionadded:: 1.2
@@ -975,7 +975,7 @@ def fit_sphere_to_headshape(info, dig_kinds='auto', units='m', verbose=None):
     %(info_not_none)s
     %(dig_kinds)s
     units : str
-        Can be "m" (default) or "mm".
+        Can be ``"m"`` (default) or ``"mm"``.
 
         .. versionadded:: 0.12
     %(verbose)s
@@ -1742,11 +1742,11 @@ def write_bem_surfaces(fname, surfs, overwrite=False, *, verbose=None):
 @verbose
 def write_head_bem(fname, rr, tris, on_defects='raise', overwrite=False,
                    *, verbose=None):
-    """Write a head surface to a fiff file.
+    """Write a head surface to a FIF file.
 
     Parameters
     ----------
-    fname : str
+    fname : path-like
         Filename to write.
     rr : array, shape (n_vertices, 3)
         Coordinate points in the MRI coordinate system.

mne/channels/layout.py

@@ -1068,7 +1068,7 @@ def generate_2d_layout(xy, w=.07, h=.05, pad=.02, ch_names=None,
         one index per channel.
     name : str
         The name of this layout type.
-    bg_image : str | ndarray
+    bg_image : path-like | ndarray
         The image over which sensor axes will be plotted. Either a path to an
         image file, or an array that can be plotted with plt.imshow. If
         provided, xy points will be normalized by the width/height of this

mne/channels/montage.py

@@ -1278,7 +1278,7 @@ def _read_isotrak_elp_points(fname):
 
     Parameters
     ----------
-    fname : str
+    fname : path-like
         The filepath of .elp Polhemus Isotrak file.
 
     Returns
@@ -1308,7 +1308,7 @@ def _read_isotrak_hsp_points(fname):
 
     Parameters
     ----------
-    fname : str
+    fname : path-like
         The filepath of .hsp Polhemus Isotrak file.
 
     Returns

mne/chpi.py

@@ -1130,7 +1130,7 @@ def compute_chpi_locs(info, chpi_amplitudes, t_step_max=1., too_close='raise',
         Maximum time step to use.
     too_close : str
         How to handle HPI positions too close to the sensors,
-        can be 'raise' (default), 'warning', or 'info'.
+        can be ``'raise'`` (default), ``'warning'``, or ``'info'``.
     %(adjust_dig_chpi)s
     %(verbose)s
 

mne/commands/mne_anonymize.py

@@ -27,9 +27,9 @@ def mne_anonymize(fif_fname, out_fname, keep_his, daysback, overwrite):
 
     Parameters
     ----------
-    fif_fname : str
+    fif_fname : path-like
         Raw fif File
-    out_fname : str | None
+    out_fname : path-like | None
         Output file name
         relative paths are saved relative to parent dir of fif_fname
         None will save to parent dir of fif_fname with default prefix

mne/commands/mne_clean_eog_ecg.py

@@ -26,7 +26,7 @@ def clean_ecg_eog(in_fif_fname, out_fif_fname=None, eog=True, ecg=True,
 
     Parameters
     ----------
-    in_fif_fname : str
+    in_fif_fname : path-like
         Raw fif File
     eog_event_fname : str
         name of EOG event file required.

mne/coreg.py

@@ -110,7 +110,7 @@ def coregister_fiducials(info, fiducials, tol=0.01):
     Parameters
     ----------
     %(info_not_none)s
-    fiducials : str | list of dict
+    fiducials : path-like | list of dict
         Fiducials in MRI coordinate space (either path to a ``*-fiducials.fif``
         file or list of fiducials as returned by :func:`read_fiducials`.
 

mne/cov.py

@@ -371,7 +371,7 @@ def read_cov(fname, verbose=None):
 
     Parameters
     ----------
-    fname : str
+    fname : path-like
         The path-like of file containing the covariance matrix. It should end
         with ``-cov.fif`` or ``-cov.fif.gz``.
     %(verbose)s
@@ -1379,8 +1379,9 @@ def write_cov(fname, cov, *, overwrite=False, verbose=None):
 
     Parameters
     ----------
-    fname : str
-        The name of the file. It should end with -cov.fif or -cov.fif.gz.
+    fname : path-like
+        The name of the file. It should end with ``-cov.fif`` or
+        ``-cov.fif.gz``.
     cov : Covariance
         The noise covariance matrix.
     %(overwrite)s

mne/cuda.py

@@ -17,7 +17,7 @@ def get_cuda_memory(kind='available'):
     Parameters
     ----------
     kind : str
-        Can be "available" or "total".
+        Can be ``"available"`` or ``"total"``.
 
     Returns
     -------
@@ -119,7 +119,7 @@ def _setup_cuda_fft_multiply_repeated(n_jobs, h, n_fft,
     Parameters
     ----------
     n_jobs : int | str
-        If n_jobs == 'cuda', the function will attempt to set up for CUDA
+        If ``n_jobs='cuda'``, the function will attempt to set up for CUDA
         FFT multiplication.
     h : array
         The filtering function that will be used repeatedly.

mne/decoding/time_delaying_ridge.py

@@ -238,7 +238,7 @@ class TimeDelayingRidge(BaseEstimator):
     alpha : float
         The ridge (or laplacian) regularization factor.
     reg_type : str | list
-        Can be "ridge" (default) or "laplacian".
+        Can be ``"ridge"`` (default) or ``"laplacian"``.
         Can also be a 2-element list specifying how to regularize in time
         and across adjacent features.
     fit_intercept : bool

mne/dipole.py

@@ -447,7 +447,7 @@ def save(self, fname, verbose=None):
 
         Parameters
         ----------
-        fname : str
+        fname : path-like
             The name of the .fif file. Must end with ``'.fif'`` or
             ``'.fif.gz'`` to make it explicit that the file contains
             dipole information in FIF format.
@@ -1155,9 +1155,9 @@ def fit_dipole(evoked, cov, bem, trans=None, min_dist=5., n_jobs=None,
         The dataset to fit.
     cov : str | instance of Covariance
         The noise covariance.
-    bem : str | instance of ConductorModel
+    bem : path-like | instance of ConductorModel
         The BEM filename (str) or conductor model.
-    trans : str | None
+    trans : path-like | None
         The head<->MRI transform filename. Must be provided unless BEM
         is a sphere model.
     min_dist : float
@@ -1187,8 +1187,9 @@ def fit_dipole(evoked, cov, bem, trans=None, min_dist=5., n_jobs=None,
 
         .. versionadded:: 0.20
     accuracy : str
-        Can be "normal" (default) or "accurate", which gives the most accurate
-        coil definition but is typically not necessary for real-world data.
+        Can be ``"normal"`` (default) or ``"accurate"``, which gives the most
+        accurate coil definition but is typically not necessary for real-world
+        data.
 
         .. versionadded:: 0.24
     tol : float

mne/evoked.py

@@ -292,7 +292,7 @@ def save(self, fname, *, overwrite=False, verbose=None):
 
         Parameters
         ----------
-        fname : str
+        fname : path-like
             The name of the file, which should end with ``-ave.fif(.gz)`` or
             ``_ave.fif(.gz)``.
         %(overwrite)s
@@ -1409,8 +1409,8 @@ def write_evokeds(fname, evoked, *, on_mismatch='raise', overwrite=False,
 
     Parameters
     ----------
-    fname : str
-        The file name, which should end with -ave.fif or -ave.fif.gz.
+    fname : path-like
+        The file name, which should end with ``-ave.fif`` or ``-ave.fif.gz``.
     evoked : Evoked instance, or list of Evoked instances
         The evoked dataset, or list of evoked datasets, to save in one file.
         Note that the measurement info from the first evoked instance is used,

mne/filter.py

@@ -131,19 +131,19 @@ def _overlap_add_filter(x, h, n_fft=None, phase='zero', picks=None,
         Signals to filter.
     h : 1d array
         Filter impulse response (FIR filter coefficients). Must be odd length
-        if phase == 'linear'.
+        if ``phase='linear'``.
     n_fft : int
         Length of the FFT. If None, the best size is determined automatically.
     phase : str
-        If 'zero', the delay for the filter is compensated (and it must be
-        an odd-length symmetric filter). If 'linear', the response is
-        uncompensated. If 'zero-double', the filter is applied in the
+        If ``'zero'``, the delay for the filter is compensated (and it must be
+        an odd-length symmetric filter). If ``'linear'``, the response is
+        uncompensated. If ``'zero-double'``, the filter is applied in the
         forward and reverse directions. If 'minimum', a minimum-phase
         filter will be used.
     picks : list | None
         See calling functions.
     n_jobs : int | str
-        Number of jobs to run in parallel. Can be 'cuda' if ``cupy``
+        Number of jobs to run in parallel. Can be ``'cuda'`` if ``cupy``
         is installed properly.
     copy : bool
         If True, a copy of x, filtered, is returned. Otherwise, it operates

mne/forward/_make_forward.py

@@ -763,7 +763,7 @@ def use_coil_def(fname):
 
     Parameters
     ----------
-    fname : str
+    fname : path-like
         The filename of the coil definition file.
 
     Returns

mne/gui/__init__.py

@@ -59,7 +59,7 @@ def coregistration(tabbed=False, split=True, width=None, inst=None,
         Use a high resolution head surface.
         Default is None, which uses ``MNE_COREG_HEAD_HIGH_RES`` config value
         (which defaults to True).
-    trans : str | None
+    trans : path-like | None
         The transform file to use.
     scrollable : bool
         Make the coregistration panel vertically scrollable (default True).

mne/gui/_coreg.py

@@ -87,7 +87,7 @@ class CoregistrationUI(HasTraits):
         with a different color. Defaults to True.
     sensor_opacity : float
         The opacity of the sensors between 0 and 1. Defaults to 1.0.
-    trans : str
+    trans : path-like
         The path to the Head<->MRI transform FIF file ("-trans.fif").
     size : tuple
         The dimensions (width, height) of the rendering view. The default is

mne/io/_digitization.py

@@ -348,7 +348,7 @@ def _write_dig_points(fname, dig_points):
 
     Parameters
     ----------
-    fname : str
+    fname : path-like
         Path to the file to write. The kind of file to write is determined
         based on the extension: '.txt' for tab separated text file.
     dig_points : numpy.ndarray, shape (n_points, 3)

mne/io/artemis123/artemis123.py

@@ -24,13 +24,13 @@ def read_raw_artemis123(input_fname, preload=False, verbose=None,
 
     Parameters
     ----------
-    input_fname : str
+    input_fname : path-like
         Path to the data file (extension ``.bin``). The header file with the
         same file name stem and an extension ``.txt`` is expected to be found
         in the same directory.
     %(preload)s
     %(verbose)s
-    pos_fname : str or None (default None)
+    pos_fname : path-like | None
         If not None, load digitized head points from this file.
     add_head_trans : bool (default True)
         If True attempt to perform initial head localization. Compute initial

mne/io/base.py

@@ -1786,7 +1786,7 @@ def add_events(self, events, stim_channel=None, replace=False):
         stim_channel : str | None
             Name of the stim channel to add to. If None, the config variable
             'MNE_STIM_CHANNEL' is used. If this is not found, it will default
-            to 'STI 014'.
+            to ``'STI 014'``.
         replace : bool
             If True the old events on the stim channel are removed before
             adding the new ones.

mne/io/besa/besa.py

@@ -10,15 +10,15 @@
 @fill_doc
 @verbose
 def read_evoked_besa(fname, verbose=None):
-    """Reader function for BESA .avr or .mul files.
+    """Reader function for BESA ``.avr`` or ``.mul`` files.
 
-    When a .elp sidecar file is present, it will be used to determine electrode
-    information.
+    When a ``.elp`` sidecar file is present, it will be used to determine
+    electrode information.
 
     Parameters
     ----------
-    fname : str | Path
-        Path to the .avr or .mul file.
+    fname : path-like
+        Path to the ``.avr`` or ``.mul`` file.
     %(verbose)s
 
     Returns

mne/io/boxy/boxy.py

@@ -22,7 +22,7 @@ def read_raw_boxy(fname, preload=False, verbose=None):
 
     Parameters
     ----------
-    fname : str
+    fname : path-like
         Path to the BOXY data file.
     %(preload)s
     %(verbose)s