yasa.fetch_sample#

yasa.fetch_sample(fname, version='v1', **kwargs)[source]#

Download (i.e., fetch) a single file, if not already downloaded, from the YASA samples dataset on Zenodo.

This function always returns a filename as a Path to the local file. It will first check for a local copy of the file and download it if not found.

The default location to store the file is in a yasa/ folder in the user’s system-dependent cache directory. (pooch.os_cache("yasa")) If you want to download the file to a different location, you can set the YASA_DATA_DIR environment variable to the desired path.

Parameters:

fnamestr: The name of the file to fetch. Must be one of the filenames available in the YASA samples dataset. See the Zenodo repo for available filenames.
versionstr, optional: The version string of the dataset to 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 samples dataset. See the Zenodo repo for available versions.
**kwargsdict: Optional keyword arguments passed to fetch. For example, set progressbar=True to display a progress bar (requires tqdm).

Returns:

fpathpathlib.Path: The Path to the downloaded file.

Examples

>>> import numpy as np
>>> import yasa
>>> # Get path to local hypnogram file (will download if not already present)
>>> fpath = yasa.fetch_sample("night_young_hypno.csv")
>>> print(fpath.exists())
True
>>> # Load the hypnogram
>>> stages_int = np.loadtxt(fpath, skiprows=1, dtype=int)
>>> stages_str = yasa.hypno_int_to_str(stages_int)
>>> hyp = yasa.Hypnogram(stages_str)
>>> print(hyp.hypno.head(3))
Epoch
0    WAKE
1    WAKE
2    WAKE
Name: Stage, dtype: category
Categories (7, object): ['WAKE', 'N1', 'N2', 'N3', 'REM', 'ART', 'UNS']

You can also set the YASA_DATA_DIR environment variable to a custom location.

>>> import os
>>> os.environ["YASA_DATA_DIR"] = "~/Desktop/my_yasa_data"
>>> fpath = yasa.fetch_sample("night_young_hypno.csv")