rename fetch_example --> fetch_sample

notebooks/01_spindles_detection.ipynb

@@ -55,7 +55,7 @@
    ],
    "source": [
     "# Download the data\n",
-    "filepath = yasa.fetch_example('N2_spindles_15sec_200Hz.txt')\n",
+    "filepath = yasa.fetch_sample('N2_spindles_15sec_200Hz.txt')\n",
     "\n",
     "# Load data\n",
     "data = np.loadtxt(filepath)\n",
@@ -405,7 +405,7 @@
     }
    ],
    "source": [
-    "filepath_no_sp = yasa.fetch_example('N3_no-spindles_30sec_100Hz.txt')\n",
+    "filepath_no_sp = yasa.fetch_sample('N3_no-spindles_30sec_100Hz.txt')\n",
     "data_no_sp = np.loadtxt(filepath_no_sp)\n",
     "sf_no_sp = 100\n",
     "times_no_sp = np.arange(data_no_sp.size) / sf_no_sp\n",

notebooks/02_spindles_detection_multi.ipynb

@@ -47,7 +47,7 @@
     "import seaborn as sns\n",
     "\n",
     "# Download the data\n",
-    "filepath = yasa.fetch_example('full_6hrs_100Hz_Cz+Fz+Pz.npz')\n",
+    "filepath = yasa.fetch_sample('full_6hrs_100Hz_Cz+Fz+Pz.npz')\n",
     "\n",
     "# Load data\n",
     "npzfile = np.load(filepath)\n",
@@ -1843,7 +1843,7 @@
     "import mne\n",
     "\n",
     "# Download the raw object\n",
-    "raw_filepath = yasa.fetch_example('sub-02_mne_raw.fif')\n",
+    "raw_filepath = yasa.fetch_sample('sub-02_mne_raw.fif')\n",
     "\n",
     "# Load the raw object\n",
     "raw = mne.io.read_raw_fif(raw_filepath, preload=True, verbose=False)\n",

notebooks/03_spindles_detection_NREM_only.ipynb

@@ -41,7 +41,7 @@
     "import seaborn as sns\n",
     "\n",
     "# Download the data\n",
-    "filepath = yasa.fetch_example('full_6hrs_100Hz_Cz+Fz+Pz.npz')\n",
+    "filepath = yasa.fetch_sample('full_6hrs_100Hz_Cz+Fz+Pz.npz')\n",
     "\n",
     "# Load data\n",
     "npzfile = np.load(filepath)\n",
@@ -81,7 +81,7 @@
     }
    ],
    "source": [
-    "hypno_30s_filepath = yasa.fetch_example('full_6hrs_100Hz_hypno_30s.txt')\n",
+    "hypno_30s_filepath = yasa.fetch_sample('full_6hrs_100Hz_hypno_30s.txt')\n",
     "hypno_30s = np.loadtxt(hypno_30s_filepath)\n",
     "hypno = yasa.hypno_upsample_to_data(hypno=hypno_30s, sf_hypno=(1/30), data=data, sf_data=sf)\n",
     "print(hypno.shape, 'Unique values =', np.unique(hypno))"

notebooks/04_spindles_slow_fast.ipynb

@@ -61,7 +61,7 @@
     }
    ],
    "source": [
-    "filepath = yasa.fetch_example('full_6hrs_100Hz_9channels.npz')\n",
+    "filepath = yasa.fetch_sample('full_6hrs_100Hz_9channels.npz')\n",
     "npzfile = np.load(filepath)\n",
     "data = npzfile.get('data')\n",
     "ch_names = npzfile.get('ch_names')\n",
@@ -102,7 +102,7 @@
     }
    ],
    "source": [
-    "hypno_30s_filepath = yasa.fetch_example('full_6hrs_100Hz_hypno_30s.txt')\n",
+    "hypno_30s_filepath = yasa.fetch_sample('full_6hrs_100Hz_hypno_30s.txt')\n",
     "hypno_30s = np.loadtxt(hypno_30s_filepath)\n",
     "hypno = yasa.hypno_upsample_to_data(hypno=hypno_30s, sf_hypno=(1/30), data=data, sf_data=sf)\n",
     "print(hypno.shape, 'Unique values =', np.unique(hypno))"

notebooks/05_sw_detection.ipynb

@@ -55,8 +55,8 @@
    ],
    "source": [
     "# Download data\n",
-    "data_filepath = yasa.fetch_example('full_6hrs_100Hz_Cz+Fz+Pz.npz')\n",
-    "hypno_filepath = yasa.fetch_example('full_6hrs_100Hz_hypno.npz')\n",
+    "data_filepath = yasa.fetch_sample('full_6hrs_100Hz_Cz+Fz+Pz.npz')\n",
+    "hypno_filepath = yasa.fetch_sample('full_6hrs_100Hz_hypno.npz')\n",
     "\n",
     "# Load data\n",
     "data = np.load(data_filepath).get('data')\n",

notebooks/06_sw_detection_multi.ipynb

@@ -45,8 +45,8 @@
     "import matplotlib.pyplot as plt\n",
     "\n",
     "# Download data\n",
-    "psg_filepath = yasa.fetch_example('full_6hrs_100Hz_Cz+Fz+Pz.npz')\n",
-    "hypno_filepath = yasa.fetch_example('full_6hrs_100Hz_hypno.npz')\n",
+    "psg_filepath = yasa.fetch_sample('full_6hrs_100Hz_Cz+Fz+Pz.npz')\n",
+    "hypno_filepath = yasa.fetch_sample('full_6hrs_100Hz_hypno.npz')\n",
     "\n",
     "# Load data\n",
     "npzfile = np.load(psg_filepath)\n",
@@ -778,7 +778,7 @@
    "outputs": [],
    "source": [
     "# Load the raw object\n",
-    "raw_filepath = yasa.fetch_example('sub-02_mne_raw.fif')\n",
+    "raw_filepath = yasa.fetch_sample('sub-02_mne_raw.fif')\n",
     "raw = mne.io.read_raw_fif(raw_filepath, preload=True, verbose=False)"
    ]
   },

notebooks/07_REMs_detection.ipynb

@@ -54,7 +54,7 @@
    ],
    "source": [
     "# Download the data\n",
-    "filepath = yasa.fetch_example('EOGs_REM_256Hz.npz')\n",
+    "filepath = yasa.fetch_sample('EOGs_REM_256Hz.npz')\n",
     "# Load data\n",
     "npzfile = np.load(filepath)\n",
     "data, sf, chan = npzfile['data'], npzfile['sf'], npzfile['chan']\n",

notebooks/08_bandpower.ipynb

@@ -69,7 +69,7 @@
    ],
    "source": [
     "# Download the data\n",
-    "raw_filepath = yasa.fetch_example('sub-02_mne_raw.fif')\n",
+    "raw_filepath = yasa.fetch_sample('sub-02_mne_raw.fif')\n",
     "\n",
     "# Load data as a MNE Raw file\n",
     "raw = mne.io.read_raw_fif(raw_filepath, preload=True, verbose=0)\n",
@@ -133,7 +133,7 @@
     }
    ],
    "source": [
-    "hypno_filepath = yasa.fetch_example('sub-02_hypno_30s.txt')\n",
+    "hypno_filepath = yasa.fetch_sample('sub-02_hypno_30s.txt')\n",
     "hypno = np.loadtxt(hypno_filepath, dtype=str)\n",
     "hypno"
    ]

notebooks/09_IRASA.ipynb

@@ -54,7 +54,7 @@
    ],
    "source": [
     "# Download the data\n",
-    "raw_filepath = yasa.fetch_example('resting_EO_200Hz_raw.fif')\n",
+    "raw_filepath = yasa.fetch_sample('resting_EO_200Hz_raw.fif')\n",
     "# Load data as a MNE Raw file\n",
     "raw = mne.io.read_raw_fif(raw_filepath, preload=True, verbose=0)\n",
     "\n",

notebooks/10_spectrogram.ipynb

@@ -51,7 +51,7 @@
    ],
    "source": [
     "# Download the EEG data\n",
-    "filepath = yasa.fetch_example('full_6hrs_100Hz_Cz+Fz+Pz.npz')\n",
+    "filepath = yasa.fetch_sample('full_6hrs_100Hz_Cz+Fz+Pz.npz')\n",
     "\n",
     "# Load EEG data\n",
     "npzfile = np.load(filepath)\n",
@@ -146,7 +146,7 @@
     }
    ],
    "source": [
-    "hypno_30s_filepath = yasa.fetch_example('full_6hrs_100Hz_hypno_30s.txt')\n",
+    "hypno_30s_filepath = yasa.fetch_sample('full_6hrs_100Hz_hypno_30s.txt')\n",
     "hypno_30s = np.loadtxt(hypno_30s_filepath)\n",
     "hypno = yasa.hypno_upsample_to_data(hypno=hypno_30s, sf_hypno=(1/30), data=data, sf_data=sf)\n",
     "print(hypno.shape, 'Unique values =', np.unique(hypno))"

notebooks/11_nonlinear_features.ipynb

@@ -38,7 +38,7 @@
     "sns.set_theme(font_scale=1.2)\n",
     "\n",
     "# Download the EEG data\n",
-    "filepath = yasa.fetch_example('full_6hrs_100Hz_Cz+Fz+Pz.npz')\n",
+    "filepath = yasa.fetch_sample('full_6hrs_100Hz_Cz+Fz+Pz.npz')\n",
     "\n",
     "# Load EEG data\n",
     "npzfile = np.load(filepath)\n",
@@ -66,7 +66,7 @@
    ],
    "source": [
     "# Load the hypnogram data\n",
-    "hypno_filepath = yasa.fetch_example('full_6hrs_100Hz_hypno_30s.txt')\n",
+    "hypno_filepath = yasa.fetch_sample('full_6hrs_100Hz_hypno_30s.txt')\n",
     "hypno = np.loadtxt(hypno_filepath).astype(int)\n",
     "print(hypno.shape, 'Unique values =', np.unique(hypno))"
    ]

notebooks/12_SO-sigma_coupling.ipynb

@@ -60,7 +60,7 @@
    ],
    "source": [
     "# Download the EEG data\n",
-    "eeg_filepath = yasa.fetch_example('full_6hrs_100Hz_Cz+Fz+Pz.npz') \n",
+    "eeg_filepath = yasa.fetch_sample('full_6hrs_100Hz_Cz+Fz+Pz.npz') \n",
     "\n",
     "# Load EEG data\n",
     "npzfile = np.load(eeg_filepath)\n",
@@ -95,7 +95,7 @@
    ],
    "source": [
     "# Load the hypnogram data\n",
-    "hypno_filepath = yasa.fetch_example('full_6hrs_100Hz_hypno_30s.txt') \n",
+    "hypno_filepath = yasa.fetch_sample('full_6hrs_100Hz_hypno_30s.txt') \n",
     "hypno = np.loadtxt(hypno_filepath).astype(int)\n",
     "print(hypno.shape, 'Unique values =', np.unique(hypno))\n",
     "\n",

notebooks/13_artifact_rejection.ipynb

@@ -45,8 +45,8 @@
     "sns.set_theme(style='white', font_scale=1.2)\n",
     "\n",
     "# Download the data\n",
-    "eeg_filepath = yasa.fetch_example('full_6hrs_100Hz_9channels.npz')\n",
-    "hypno_filepath = yasa.fetch_example('full_6hrs_100Hz_hypno.npz')\n",
+    "eeg_filepath = yasa.fetch_sample('full_6hrs_100Hz_9channels.npz')\n",
+    "hypno_filepath = yasa.fetch_sample('full_6hrs_100Hz_hypno.npz')\n",
     "\n",
     "# Load data\n",
     "npzfile = np.load(eeg_filepath)\n",

notebooks/14_automatic_sleep_staging.ipynb

@@ -414,7 +414,7 @@
    ],
    "source": [
     "# Let's load a nap recording, directly as an MNE Raw object\n",
-    "raw_filepath = yasa.fetch_example('sub-02_mne_raw.fif')\n",
+    "raw_filepath = yasa.fetch_sample('sub-02_mne_raw.fif')\n",
     "raw = mne.io.read_raw_fif(raw_filepath, preload=True, verbose=False)\n",
     "print('The channels are:', raw.ch_names)\n",
     "print('The sampling frequency is:', raw.info['sfreq'])\n",
@@ -447,7 +447,7 @@
    ],
    "source": [
     "# Let's now load the human-scored hypnogram, where each value represents a 30-sec epoch.\n",
-    "hyp_filepath = yasa.fetch_example('sub-02_hypno_30s.txt')\n",
+    "hyp_filepath = yasa.fetch_sample('sub-02_hypno_30s.txt')\n",
     "hyp = np.loadtxt(hyp_filepath, dtype=str)\n",
     "hyp"
    ]

notebooks/16_EEG-HRV_coupling.ipynb

@@ -41,8 +41,8 @@
    "outputs": [],
    "source": [
     "# Download the data from the YASA example data repository on Zenodo\n",
-    "path_edf = yasa.fetch_example(\"night_young.edf\")\n",
-    "path_hypno = yasa.fetch_example(\"night_young_hypno.csv\")"
+    "path_edf = yasa.fetch_sample(\"night_young.edf\")\n",
+    "path_hypno = yasa.fetch_sample(\"night_young_hypno.csv\")"
    ]
   },
   {

notebooks/20_plot_gallery.ipynb

@@ -35,8 +35,8 @@
     "import matplotlib.pyplot as plt\n",
     "\n",
     "# Download the EEG data and hypnogram\n",
-    "eeg_filepath = yasa.fetch_example('full_6hrs_100Hz_Cz+Fz+Pz.npz')\n",
-    "hypno_filepath = yasa.fetch_example('full_6hrs_100Hz_hypno_30s.txt')\n",
+    "eeg_filepath = yasa.fetch_sample('full_6hrs_100Hz_Cz+Fz+Pz.npz')\n",
+    "hypno_filepath = yasa.fetch_sample('full_6hrs_100Hz_hypno_30s.txt')\n",
     "\n",
     "# Load EEG data\n",
     "npzfile = np.load(eeg_filepath)\n",

src/yasa/fetchers.py

@@ -10,7 +10,7 @@
 import pooch
 
 __all__ = [
-    "fetch_example",
+    "fetch_sample",
 ]
 
 
@@ -59,10 +59,10 @@ def _init_doi_repository(doi, populate_registry=True):
     return repo
 
 
-def fetch_example(fname, version="latest", **kwargs):
+def fetch_sample(fname, version="latest", **kwargs):
     """
     Download (i.e., :py:meth:`~pooch.Pooch.fetch`) a single file -- _if not already downloaded_ --
-    from the YASA examples dataset on `Zenodo <https://doi.org/10.5281/zenodo.14564284>`_.
+    from the YASA samples dataset on `Zenodo <https://doi.org/10.5281/zenodo.14564284>`_.
 
     This function always returns a filename as a :py:class:`~pathlib.Path` to the local file.
     It will first check for a local copy of the file and download it if not found.
@@ -76,13 +76,13 @@ def fetch_example(fname, version="latest", **kwargs):
     ----------
     fname : str
         The name of the file to :py:meth:`~pooch.Pooch.fetch`.
-        Must be one of the filenames available in the YASA examples dataset.
+        Must be one of the filenames available in the YASA samples dataset.
         See the `Zenodo repo <https://doi.org/10.5281/zenodo.14564284>`_ for available filenames.
 
     version : str, optional
         The version string of the dataset to :py:meth:`~pooch.Pooch.fetch`.
         Setting this to ``latest`` (default) is equivalent to setting to the latest version string.
-        Must be one of the versions available for the YASA examples dataset.
+        Must be one of the versions available for the YASA samples dataset.
         See the `Zenodo repo <https://doi.org/10.5281/zenodo.14564284>`_ for available versions.
 
     **kwargs : dict
@@ -99,7 +99,7 @@ def fetch_example(fname, version="latest", **kwargs):
     >>> import numpy as np
     >>> import yasa
     >>> # Get path to local hypnogram file (will download if not already present)
-    >>> fpath = yasa.fetch_example("night_young_hypno.csv")
+    >>> fpath = yasa.fetch_sample("night_young_hypno.csv")
     >>> print(fpath.exists())
     True
     >>> # Load the hypnogram
@@ -118,7 +118,7 @@ def fetch_example(fname, version="latest", **kwargs):
 
     >>> import os
     >>> os.environ["YASA_DATA_DIR"] = "~/Desktop/my_yasa_data"
-    >>> fpath = yasa.fetch_example("night_young_hypno.csv")
+    >>> fpath = yasa.fetch_sample("night_young_hypno.csv")
     """
     repository_dois = {
         "latest": "10.5281/zenodo.14564284",

tests/test_detection.py

@@ -11,7 +11,7 @@
 from mne.filter import filter_data
 
 from yasa.detection import art_detect, compare_detection, rem_detect, spindles_detect, sw_detect
-from yasa.fetchers import fetch_example
+from yasa.fetchers import fetch_sample
 from yasa.hypno import hypno_str_to_int, hypno_upsample_to_data
 
 ##############################################################################
@@ -22,18 +22,18 @@
 sf = 100
 
 # 1) Single channel, we take one every other point to keep a sf of 100 Hz
-data_fp = fetch_example("N2_spindles_15sec_200Hz.txt")
+data_fp = fetch_sample("N2_spindles_15sec_200Hz.txt")
 data = np.loadtxt(data_fp)[::2]
 data_sigma = filter_data(data, sf, 12, 15, method="fir", verbose=0)
 
 # Load an extract of N3 sleep without any spindle
-data_n3_fp = fetch_example("N3_no-spindles_30sec_100Hz.txt")
+data_n3_fp = fetch_sample("N3_no-spindles_30sec_100Hz.txt")
 data_n3 = np.loadtxt(data_n3_fp)
 
 # 2) Multi-channel
 # Load a full recording and its hypnogram
-data_full_fp = fetch_example("full_6hrs_100Hz_Cz+Fz+Pz.npz")
-hypno_full_fp = fetch_example("full_6hrs_100Hz_hypno.npz")
+data_full_fp = fetch_sample("full_6hrs_100Hz_Cz+Fz+Pz.npz")
+hypno_full_fp = fetch_sample("full_6hrs_100Hz_hypno.npz")
 data_full = np.load(data_full_fp).get("data")
 chan_full = np.load(data_full_fp).get("chan")
 hypno_full = np.load(hypno_full_fp).get("hypno")
@@ -47,11 +47,11 @@
 hypno_sw = hypno_full[666000:672000]
 
 # MNE Raw
-data_mne_fp = fetch_example("sub-02_mne_raw.fif")
+data_mne_fp = fetch_sample("sub-02_mne_raw.fif")
 data_mne = mne.io.read_raw_fif(data_mne_fp, preload=True, verbose=0)
 data_mne.pick("eeg")
 data_mne_single = data_mne.copy().pick(["F3"])
-hypno_mne_fp = fetch_example("sub-02_hypno_30s.txt")
+hypno_mne_fp = fetch_sample("sub-02_hypno_30s.txt")
 hypno_mne = np.loadtxt(hypno_mne_fp, dtype=str)
 hypno_mne = hypno_str_to_int(hypno_mne)
 hypno_mne = hypno_upsample_to_data(hypno=hypno_mne, sf_hypno=(1 / 30), data=data_mne)
@@ -321,7 +321,7 @@ def test_sw_detect(self):
 
     def test_rem_detect(self):
         """Test function REM detect"""
-        file_rem_fp = fetch_example("EOGs_REM_256Hz.npz")
+        file_rem_fp = fetch_sample("EOGs_REM_256Hz.npz")
         file_rem = np.load(file_rem_fp)
         data_rem = file_rem["data"]
         loc, roc = data_rem[0, :], data_rem[1, :]
@@ -372,10 +372,10 @@ def test_rem_detect(self):
 
     def test_art_detect(self):
         """Test function art_detect"""
-        file_9_fp = fetch_example("full_6hrs_100Hz_9channels.npz")
+        file_9_fp = fetch_sample("full_6hrs_100Hz_9channels.npz")
         file_9 = np.load(file_9_fp)
         data_9 = file_9.get("data")
-        hypno_9_fp = fetch_example("full_6hrs_100Hz_hypno.npz")
+        hypno_9_fp = fetch_sample("full_6hrs_100Hz_hypno.npz")
         hypno_9 = np.load(hypno_9_fp).get("hypno")  # noqa
         # For the sake of the example, let's add some flat data at the end
         data_9 = np.concatenate((data_9, np.zeros((data_9.shape[0], 20000))), axis=1)

tests/test_fetchers.py

@@ -44,6 +44,6 @@ def test_examples_download(self):
         """Test the download of a single arbitrary file from the examples repo"""
         with TemporaryDirectory() as tempdir:
             os.environ["YASA_DATA_DIR"] = tempdir
-            fp = fetchers.fetch_example(SMALL_SAMPLE_FILE)
+            fp = fetchers.fetch_sample(SMALL_SAMPLE_FILE)
             assert fp.exists()
             assert fp.is_file()

tests/test_heart.py

@@ -4,11 +4,11 @@
 
 import numpy as np
 
-from yasa.fetchers import fetch_example
+from yasa.fetchers import fetch_sample
 from yasa.heart import hrv_stage
 
 # Load data
-ecg_filepath = fetch_example("ECG_8hrs_200Hz.npz")
+ecg_filepath = fetch_sample("ECG_8hrs_200Hz.npz")
 ecg_file = np.load(ecg_filepath)
 data = ecg_file["data"]
 sf = int(ecg_file["sf"])