API: Return Path in data_path (mne-tools#10348)

* WIP: Return Path in data_path * FIX: Bugs * FIX: Tests * FIX: Examples [circle full] * FIX: Test * FIX: Fixes [circle full] * FIX: Last but not least [circle full]
rbruna · Feb 16, 2022 · 5fd9ca6 · 5fd9ca6
1 parent d2d6ec1
commit 5fd9ca6
Show file tree

Hide file tree

Showing 113 changed files with 455 additions and 344 deletions.
diff --git a/doc/_includes/memory.rst b/doc/_includes/memory.rst
@@ -20,7 +20,7 @@ raw reading functions. For example::
     from mne import io
     from mne.datasets import sample
     data_path = sample.data_path()
-    raw_fname = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw.fif'
+    raw_fname = data_path / 'MEG' / 'sample' / 'sample_audvis_filt-0-40_raw.fif'
     raw = io.read_raw_fif(raw_fname, preload=False)
 
 .. note:: Filtering, resampling and dropping or selecting channels does not

diff --git a/doc/changes/latest.inc b/doc/changes/latest.inc
@@ -209,6 +209,8 @@ API changes
 ~~~~~~~~~~~
 - ``mne.Info.pick_channels`` has been deprecated. Use ``inst.pick_channels`` to pick channels from :class:`~mne.io.Raw`, :class:`~mne.Epochs`, and :class:`~mne.Evoked`. Use :func:`mne.pick_info` to pick channels from :class:`mne.Info` (:gh:`10039` by `Mathieu Scheltienne`_)
 
+- All :func:`data_path <mne.datasets.sample.data_path>` functions now return :class:`python:pathlib.Path` objects rather than strings. Support for string concatenation with plus (``+``) is thus deprecated and will be removed in 1.2, use the forward-slash ``/`` operator instead (:gh:`10348` by `Eric Larson`_)
+
 - Argument ``event_list`` has been deprecated in favor of ``events`` in :func:`mne.write_events` (:gh:`10056` by `Mathieu Scheltienne`_)
 
 - ``mne.preprocessing.annotate_flat`` has been deprecated in favor of :func`mne.preprocessing.annotate_amplitude`, that covers both minimum and maximum peak-to-peak variation. (:gh:`10143` by `Mathieu Scheltienne`_)

diff --git a/doc/conf.py b/doc/conf.py
@@ -170,6 +170,7 @@
     'iterator': ':term:`iterator <python:iterator>`',
     'path-like': ':term:`path-like`',
     'array-like': ':term:`array-like`',
+    'Path': ':class:`python:pathlib.Path`',
     # Matplotlib
     'colormap': ':doc:`colormap <matplotlib:tutorials/colors/colormaps>`',
     'color': ':doc:`color <matplotlib:api/colors_api>`',

diff --git a/examples/datasets/brainstorm_data.py b/examples/datasets/brainstorm_data.py
@@ -30,7 +30,7 @@
 
 data_path = bst_raw.data_path()
 
-raw_path = (data_path + '/MEG/bst_raw/' +
+raw_path = (data_path / 'MEG' / 'bst_raw' /
             'subj001_somatosensory_20111109_01_AUX-f.ds')
 # Here we crop to half the length to save memory
 raw = read_raw_ctf(raw_path).crop(0, 180).load_data()

diff --git a/examples/datasets/spm_faces_dataset_sgskip.py b/examples/datasets/spm_faces_dataset_sgskip.py
@@ -35,12 +35,13 @@
 print(__doc__)
 
 data_path = spm_face.data_path()
-subjects_dir = data_path + '/subjects'
+subjects_dir = data_path / 'subjects'
+spm_path = data_path / 'MEG' / 'spm'
 
 # %%
 # Load and filter data, set up epochs
 
-raw_fname = data_path + '/MEG/spm/SPM_CTF_MEG_example_faces%d_3D.ds'
+raw_fname = spm_path / 'SPM_CTF_MEG_example_faces%d_3D.ds'
 
 raw = io.read_raw_ctf(raw_fname % 1, preload=True)  # Take first run
 # Here to save memory and time we'll downsample heavily -- this is not
@@ -97,8 +98,7 @@
 
 # The transformation here was aligned using the dig-montage. It's included in
 # the spm_faces dataset and is named SPM_dig_montage.fif.
-trans_fname = data_path + ('/MEG/spm/SPM_CTF_MEG_example_faces1_3D_'
-                           'raw-trans.fif')
+trans_fname = spm_path / 'SPM_CTF_MEG_example_faces1_3D_raw-trans.fif'
 
 maps = mne.make_field_map(evoked[0], trans_fname, subject='spm',
                           subjects_dir=subjects_dir, n_jobs=1)
@@ -113,8 +113,8 @@
 # %%
 # Compute forward model
 
-src = data_path + '/subjects/spm/bem/spm-oct-6-src.fif'
-bem = data_path + '/subjects/spm/bem/spm-5120-5120-5120-bem-sol.fif'
+src = subjects_dir / 'spm' / 'bem' / 'spm-oct-6-src.fif'
+bem = subjects_dir / 'spm' / 'bem' / 'spm-5120-5120-5120-bem-sol.fif'
 forward = mne.make_forward_solution(contrast.info, trans_fname, src, bem)
 
 # %%

diff --git a/examples/decoding/decoding_spatio_temporal_source.py b/examples/decoding/decoding_spatio_temporal_source.py
@@ -37,16 +37,17 @@
 print(__doc__)
 
 data_path = mne.datasets.sample.data_path()
-fname_fwd = data_path + 'MEG/sample/sample_audvis-meg-oct-6-fwd.fif'
-fname_evoked = data_path + '/MEG/sample/sample_audvis-ave.fif'
-subjects_dir = data_path + '/subjects'
+meg_path = data_path / 'MEG' / 'sample'
+fname_fwd = meg_path / 'sample_audvis-meg-oct-6-fwd.fif'
+fname_evoked = meg_path / 'sample_audvis-ave.fif'
+subjects_dir = data_path / 'subjects'
 
 # %%
 # Set parameters
-raw_fname = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw.fif'
-event_fname = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw-eve.fif'
-fname_cov = data_path + '/MEG/sample/sample_audvis-cov.fif'
-fname_inv = data_path + '/MEG/sample/sample_audvis-meg-oct-6-meg-inv.fif'
+raw_fname = meg_path / 'sample_audvis_filt-0-40_raw.fif'
+event_fname = meg_path / 'sample_audvis_filt-0-40_raw-eve.fif'
+fname_cov = meg_path / 'sample_audvis-cov.fif'
+fname_inv = meg_path / 'sample_audvis-meg-oct-6-meg-inv.fif'
 
 tmin, tmax = -0.2, 0.8
 event_id = dict(aud_r=2, vis_r=4)  # load contra-lateral conditions

diff --git a/examples/decoding/decoding_spoc_CMC.py b/examples/decoding/decoding_spoc_CMC.py
@@ -36,7 +36,7 @@
 from sklearn.model_selection import KFold, cross_val_predict
 
 # Define parameters
-fname = data_path() + '/SubjectCMC.ds'
+fname = data_path() / 'SubjectCMC.ds'
 raw = mne.io.read_raw_ctf(fname)
 raw.crop(50., 200.)  # crop for memory purposes
 

diff --git a/examples/decoding/decoding_time_generalization_conditions.py b/examples/decoding/decoding_time_generalization_conditions.py
@@ -32,8 +32,9 @@
 # Preprocess data
 data_path = sample.data_path()
 # Load and filter data, set up epochs
-raw_fname = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw.fif'
-events_fname = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw-eve.fif'
+meg_path = data_path / 'MEG' / 'sample'
+raw_fname = meg_path / 'sample_audvis_filt-0-40_raw.fif'
+events_fname = meg_path / 'sample_audvis_filt-0-40_raw-eve.fif'
 raw = mne.io.read_raw_fif(raw_fname, preload=True)
 picks = mne.pick_types(raw.info, meg=True, exclude='bads')  # Pick MEG channels
 raw.filter(1., 30., fir_design='firwin')  # Band pass filtering signals

diff --git a/examples/decoding/decoding_unsupervised_spatial_filter.py b/examples/decoding/decoding_unsupervised_spatial_filter.py
@@ -30,8 +30,9 @@
 data_path = sample.data_path()
 
 # Load and filter data, set up epochs
-raw_fname = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw.fif'
-event_fname = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw-eve.fif'
+meg_path = data_path / 'MEG' / 'sample'
+raw_fname = meg_path / 'sample_audvis_filt-0-40_raw.fif'
+event_fname = meg_path / 'sample_audvis_filt-0-40_raw-eve.fif'
 tmin, tmax = -0.1, 0.3
 event_id = dict(aud_l=1, aud_r=2, vis_l=3, vis_r=4)
 

diff --git a/examples/decoding/decoding_xdawn_eeg.py b/examples/decoding/decoding_xdawn_eeg.py
@@ -37,8 +37,9 @@
 
 # %%
 # Set parameters and read data
-raw_fname = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw.fif'
-event_fname = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw-eve.fif'
+meg_path = data_path / 'MEG' / 'sample'
+raw_fname = meg_path / 'sample_audvis_filt-0-40_raw.fif'
+event_fname = meg_path / 'sample_audvis_filt-0-40_raw-eve.fif'
 tmin, tmax = -0.1, 0.3
 event_id = {'Auditory/Left': 1, 'Auditory/Right': 2,
             'Visual/Left': 3, 'Visual/Right': 4}

diff --git a/examples/decoding/ems_filtering.py b/examples/decoding/ems_filtering.py
@@ -39,8 +39,9 @@
 data_path = sample.data_path()
 
 # Preprocess the data
-raw_fname = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw.fif'
-event_fname = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw-eve.fif'
+meg_path = data_path / 'MEG' / 'sample'
+raw_fname = meg_path / 'sample_audvis_filt-0-40_raw.fif'
+event_fname = meg_path / 'sample_audvis_filt-0-40_raw-eve.fif'
 event_ids = {'AudL': 1, 'VisL': 3}
 
 # Read data and create epochs

diff --git a/examples/decoding/linear_model_patterns.py b/examples/decoding/linear_model_patterns.py
@@ -38,12 +38,12 @@
 print(__doc__)
 
 data_path = sample.data_path()
-sample_path = data_path + '/MEG/sample'
+sample_path = data_path / 'MEG' / 'sample'
 
 # %%
 # Set parameters
-raw_fname = sample_path + '/sample_audvis_filt-0-40_raw.fif'
-event_fname = sample_path + '/sample_audvis_filt-0-40_raw-eve.fif'
+raw_fname = sample_path / 'sample_audvis_filt-0-40_raw.fif'
+event_fname = sample_path / 'sample_audvis_filt-0-40_raw-eve.fif'
 tmin, tmax = -0.1, 0.4
 event_id = dict(aud_l=1, vis_l=3)
 

diff --git a/examples/decoding/ssd_spatial_filters.py b/examples/decoding/ssd_spatial_filters.py
@@ -26,7 +26,7 @@
 
 # %%
 # Define parameters
-fname = data_path() + '/SubjectCMC.ds'
+fname = data_path() / 'SubjectCMC.ds'
 
 # Prepare data
 raw = mne.io.read_raw_ctf(fname)

diff --git a/examples/forward/forward_sensitivity_maps.py b/examples/forward/forward_sensitivity_maps.py
@@ -28,10 +28,9 @@
 print(__doc__)
 
 data_path = sample.data_path()
-
-fwd_fname = data_path + '/MEG/sample/sample_audvis-meg-eeg-oct-6-fwd.fif'
-
-subjects_dir = data_path + '/subjects'
+meg_path = data_path / 'MEG' / 'sample'
+fwd_fname = meg_path / 'sample_audvis-meg-eeg-oct-6-fwd.fif'
+subjects_dir = data_path / 'subjects'
 
 # Read the forward solutions with surface orientation
 fwd = mne.read_forward_solution(fwd_fname)

diff --git a/examples/inverse/compute_mne_inverse_epochs_in_label.py b/examples/inverse/compute_mne_inverse_epochs_in_label.py
@@ -23,11 +23,12 @@
 print(__doc__)
 
 data_path = sample.data_path()
-fname_inv = data_path + '/MEG/sample/sample_audvis-meg-oct-6-meg-inv.fif'
-fname_raw = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw.fif'
-fname_event = data_path + '/MEG/sample/sample_audvis_filt-0-40_raw-eve.fif'
+meg_path = data_path / 'MEG' / 'sample'
+fname_inv = meg_path / 'sample_audvis-meg-oct-6-meg-inv.fif'
+fname_raw = meg_path / 'sample_audvis_filt-0-40_raw.fif'
+fname_event = meg_path / 'sample_audvis_filt-0-40_raw-eve.fif'
 label_name = 'Aud-lh'
-fname_label = data_path + '/MEG/sample/labels/%s.label' % label_name
+fname_label = meg_path / 'labels' / f'{label_name}.label'
 
 event_id, tmin, tmax = 1, -0.2, 0.5
 

diff --git a/examples/inverse/compute_mne_inverse_raw_in_label.py b/examples/inverse/compute_mne_inverse_raw_in_label.py
@@ -25,10 +25,11 @@
 print(__doc__)
 
 data_path = sample.data_path()
-fname_inv = data_path + '/MEG/sample/sample_audvis-meg-oct-6-meg-inv.fif'
-fname_raw = data_path + '/MEG/sample/sample_audvis_raw.fif'
+fname_inv = (
+    data_path / 'MEG' / 'sample' / 'sample_audvis-meg-oct-6-meg-inv.fif')
+fname_raw = data_path / 'MEG' / 'sample' / 'sample_audvis_raw.fif'
 label_name = 'Aud-lh'
-fname_label = data_path + '/MEG/sample/labels/%s.label' % label_name
+fname_label = data_path / 'MEG' / 'sample' / 'labels' / f'{label_name}.label'
 
 snr = 1.0  # use smaller SNR for raw data
 lambda2 = 1.0 / snr ** 2

diff --git a/examples/inverse/compute_mne_inverse_volume.py b/examples/inverse/compute_mne_inverse_volume.py
@@ -24,8 +24,9 @@
 print(__doc__)
 
 data_path = sample.data_path()
-fname_inv = data_path + '/MEG/sample/sample_audvis-meg-vol-7-meg-inv.fif'
-fname_evoked = data_path + '/MEG/sample/sample_audvis-ave.fif'
+meg_path = data_path / 'MEG' / 'sample'
+fname_inv = meg_path / 'sample_audvis-meg-vol-7-meg-inv.fif'
+fname_evoked = meg_path / 'sample_audvis-ave.fif'
 
 snr = 3.0
 lambda2 = 1.0 / snr ** 2
@@ -47,9 +48,9 @@
 # Save it as a nifti file
 # nib.save(img, 'mne_%s_inverse.nii.gz' % method)
 
-t1_fname = data_path + '/subjects/sample/mri/T1.mgz'
+t1_fname = data_path / 'subjects' / 'sample' / 'mri' / 'T1.mgz'
 
 # %%
 # Plot with nilearn:
-plot_stat_map(index_img(img, 61), t1_fname, threshold=8.,
+plot_stat_map(index_img(img, 61), str(t1_fname), threshold=8.,
               title='%s (t=%.1f s.)' % (method, stc.times[61]))
diff --git a/examples/inverse/custom_inverse_solver.py b/examples/inverse/custom_inverse_solver.py
@@ -28,10 +28,11 @@
 
 
 data_path = sample.data_path()
-fwd_fname = data_path + '/MEG/sample/sample_audvis-meg-eeg-oct-6-fwd.fif'
-ave_fname = data_path + '/MEG/sample/sample_audvis-ave.fif'
-cov_fname = data_path + '/MEG/sample/sample_audvis-shrunk-cov.fif'
-subjects_dir = data_path + '/subjects'
+meg_path = data_path / 'MEG' / 'sample'
+fwd_fname = meg_path / 'sample_audvis-meg-eeg-oct-6-fwd.fif'
+ave_fname = meg_path / 'sample_audvis-ave.fif'
+cov_fname = meg_path / 'sample_audvis-shrunk-cov.fif'
+subjects_dir = data_path / 'subjects'
 condition = 'Left Auditory'
 
 # Read noise covariance matrix

diff --git a/examples/inverse/gamma_map_inverse.py b/examples/inverse/gamma_map_inverse.py
@@ -23,10 +23,11 @@
 print(__doc__)
 
 data_path = sample.data_path()
-subjects_dir = data_path + '/subjects'
-fwd_fname = data_path + '/MEG/sample/sample_audvis-meg-eeg-oct-6-fwd.fif'
-evoked_fname = data_path + '/MEG/sample/sample_audvis-ave.fif'
-cov_fname = data_path + '/MEG/sample/sample_audvis-cov.fif'
+subjects_dir = data_path / 'subjects'
+meg_path = data_path / 'MEG' / 'sample'
+fwd_fname = meg_path / 'sample_audvis-meg-eeg-oct-6-fwd.fif'
+evoked_fname = meg_path / 'sample_audvis-ave.fif'
+cov_fname = meg_path / 'sample_audvis-cov.fif'
 
 # Read the evoked response and crop it
 condition = 'Left visual'

diff --git a/examples/inverse/label_activation_from_stc.py b/examples/inverse/label_activation_from_stc.py
@@ -15,35 +15,33 @@
 
 # %%
 
-import os
-
 import mne
 from mne.datasets import sample
 import matplotlib.pyplot as plt
 
 print(__doc__)
 
 data_path = sample.data_path()
-os.environ['SUBJECTS_DIR'] = data_path + '/subjects'
-meg_path = data_path + '/MEG/sample'
+subjects_dir = data_path / 'subjects'
+meg_path = data_path / 'MEG' / 'sample'
 
 # load the stc
-stc = mne.read_source_estimate(meg_path + '/sample_audvis-meg')
+stc = mne.read_source_estimate(meg_path / 'sample_audvis-meg')
 
 # load the labels
-aud_lh = mne.read_label(meg_path + '/labels/Aud-lh.label')
-aud_rh = mne.read_label(meg_path + '/labels/Aud-rh.label')
+aud_lh = mne.read_label(meg_path / 'labels' / 'Aud-lh.label')
+aud_rh = mne.read_label(meg_path / 'labels' / 'Aud-rh.label')
 
 # extract the time course for different labels from the stc
 stc_lh = stc.in_label(aud_lh)
 stc_rh = stc.in_label(aud_rh)
 stc_bh = stc.in_label(aud_lh + aud_rh)
 
 # calculate center of mass and transform to mni coordinates
-vtx, _, t_lh = stc_lh.center_of_mass('sample')
-mni_lh = mne.vertex_to_mni(vtx, 0, 'sample')[0]
-vtx, _, t_rh = stc_rh.center_of_mass('sample')
-mni_rh = mne.vertex_to_mni(vtx, 1, 'sample')[0]
+vtx, _, t_lh = stc_lh.center_of_mass('sample', subjects_dir=subjects_dir)
+mni_lh = mne.vertex_to_mni(vtx, 0, 'sample', subjects_dir=subjects_dir)[0]
+vtx, _, t_rh = stc_rh.center_of_mass('sample', subjects_dir=subjects_dir)
+mni_rh = mne.vertex_to_mni(vtx, 1, 'sample', subjects_dir=subjects_dir)[0]
 
 # plot the activation
 plt.figure()

diff --git a/examples/inverse/label_from_stc.py b/examples/inverse/label_from_stc.py
@@ -26,9 +26,10 @@
 print(__doc__)
 
 data_path = sample.data_path()
-fname_inv = data_path + '/MEG/sample/sample_audvis-meg-oct-6-meg-inv.fif'
-fname_evoked = data_path + '/MEG/sample/sample_audvis-ave.fif'
-subjects_dir = data_path + '/subjects'
+fname_inv = (
+    data_path / 'MEG' / 'sample' / 'sample_audvis-meg-oct-6-meg-inv.fif')
+fname_evoked = data_path / 'MEG' / 'sample' / 'sample_audvis-ave.fif'
+subjects_dir = data_path / 'subjects'
 subject = 'sample'
 
 snr = 3.0

diff --git a/examples/inverse/label_source_activations.py b/examples/inverse/label_source_activations.py
@@ -27,9 +27,10 @@
 
 data_path = sample.data_path()
 label = 'Aud-lh'
-label_fname = data_path + '/MEG/sample/labels/%s.label' % label
-fname_inv = data_path + '/MEG/sample/sample_audvis-meg-oct-6-meg-inv.fif'
-fname_evoked = data_path + '/MEG/sample/sample_audvis-ave.fif'
+meg_path = data_path / 'MEG' / 'sample'
+label_fname = meg_path / 'labels' / f'{label}.label'
+fname_inv = meg_path / 'sample_audvis-meg-oct-6-meg-inv.fif'
+fname_evoked = meg_path / 'sample_audvis-ave.fif'
 
 snr = 3.0
 lambda2 = 1.0 / snr ** 2

diff --git a/examples/inverse/mixed_norm_inverse.py b/examples/inverse/mixed_norm_inverse.py
@@ -29,10 +29,11 @@
 print(__doc__)
 
 data_path = sample.data_path()
-fwd_fname = data_path + '/MEG/sample/sample_audvis-meg-eeg-oct-6-fwd.fif'
-ave_fname = data_path + '/MEG/sample/sample_audvis-ave.fif'
-cov_fname = data_path + '/MEG/sample/sample_audvis-shrunk-cov.fif'
-subjects_dir = data_path + '/subjects'
+meg_path = data_path / 'MEG' / 'sample'
+fwd_fname = meg_path / 'sample_audvis-meg-eeg-oct-6-fwd.fif'
+ave_fname = meg_path / 'sample_audvis-ave.fif'
+cov_fname = meg_path / 'sample_audvis-shrunk-cov.fif'
+subjects_dir = data_path / 'subjects'
 
 # Read noise covariance matrix
 cov = mne.read_cov(cov_fname)
@@ -115,7 +116,8 @@
                                  subject_to='fsaverage', spacing=None,
                                  sparse=True, subjects_dir=subjects_dir)
 stc_fsaverage = morph.apply(stc)
-src_fsaverage_fname = subjects_dir + '/fsaverage/bem/fsaverage-ico-5-src.fif'
+src_fsaverage_fname = (
+    subjects_dir / 'fsaverage' / 'bem' / 'fsaverage-ico-5-src.fif')
 src_fsaverage = mne.read_source_spaces(src_fsaverage_fname)
 
 plot_sparse_source_estimates(src_fsaverage, stc_fsaverage, bgcolor=(1, 1, 1),