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. Default is "v1". 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)
>>> hyp = yasa.Hypnogram.from_integers(stages_int)
>>> hyp.hypno.head(3).tolist()
['WAKE', 'WAKE', 'WAKE']

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")