diff --git a/doc/api/datasets.rst b/doc/api/datasets.rst index 87730fbd717..e19bf7f8dfb 100644 --- a/doc/api/datasets.rst +++ b/doc/api/datasets.rst @@ -30,6 +30,7 @@ Datasets hf_sef.data_path kiloword.data_path limo.load_data + lite_data.data_path misc.data_path mtrf.data_path multimodal.data_path diff --git a/doc/changes/dev/14128.newfeature.rst b/doc/changes/dev/14128.newfeature.rst new file mode 100644 index 00000000000..8fd9a438326 --- /dev/null +++ b/doc/changes/dev/14128.newfeature.rst @@ -0,0 +1 @@ +Add the :func:`mne.datasets.lite_data.data_path` fetcher for the curated data subset used by the browser documentation, by `Natneal B`_. diff --git a/doc/documentation/datasets.rst b/doc/documentation/datasets.rst index 2ec98664e74..3dbf0d7a794 100644 --- a/doc/documentation/datasets.rst +++ b/doc/documentation/datasets.rst @@ -541,6 +541,29 @@ the people in the scene were unrecognizable. * :ref:`tut-eyetrack-heatmap` +.. _lite-data: + +JupyterLite data +================ +:func:`mne.datasets.lite_data.data_path` + +A small curated archive holding the data files needed to run the tutorials and +examples in the browser, taken from the ``sample``, ``kiloword``, ``erp_core``, +``mtrf`` and ``eegbci`` datasets. The files are unchanged and keep the same +checksums as the full datasets. It extracts to ``MNE-lite-data/``, keeping each +file under its original dataset folder (``MNE-sample-data/``, +``MNE-kiloword-data/``, ...). + +Those datasets ship as separate multi-GB archives, so without this the +documentation build would download several gigabytes to serve a handful of +files. + +The ``somato`` dataset is not included, so the somatosensory tutorials and +examples are not available in the browser. + +This exists for the documentation build; for analysis, use the individual +dataset fetchers above. + References ========== diff --git a/mne/datasets/__init__.pyi b/mne/datasets/__init__.pyi index 2f69a1027e5..f1a6db8b581 100644 --- a/mne/datasets/__init__.pyi +++ b/mne/datasets/__init__.pyi @@ -19,6 +19,7 @@ __all__ = [ "hf_sef", "kiloword", "limo", + "lite_data", "misc", "mtrf", "multimodal", @@ -48,6 +49,7 @@ from . import ( hf_sef, kiloword, limo, + lite_data, misc, mtrf, multimodal, diff --git a/mne/datasets/config.py b/mne/datasets/config.py index 5599c20e5d4..293c29bcbb3 100644 --- a/mne/datasets/config.py +++ b/mne/datasets/config.py @@ -209,6 +209,16 @@ config_key="MNE_DATASETS_SAMPLE_PATH", ) +# Curated subset of sample (plus a few files from kiloword/erp_core/mtrf/eegbci) +# used by the JupyterLite browser docs; see mne/datasets/lite_data/. +MNE_DATASETS["lite_data"] = dict( + archive_name="MNE-lite-data.tar.gz", + hash="md5:5f9c4fffed32e79bc2bc2061bf22ce99", + url="https://osf.io/download/a8qbx", + folder_name="MNE-lite-data", + config_key="MNE_DATASETS_LITE_DATA_PATH", +) + MNE_DATASETS["somato"] = dict( archive_name="MNE-somato-data.tar.gz", hash="md5:9a191907b326b9402341ee7a0d1240d8", diff --git a/mne/datasets/lite_data/__init__.py b/mne/datasets/lite_data/__init__.py new file mode 100644 index 00000000000..eff22a4ce84 --- /dev/null +++ b/mne/datasets/lite_data/__init__.py @@ -0,0 +1,7 @@ +# Authors: The MNE-Python contributors. +# License: BSD-3-Clause +# Copyright the MNE-Python contributors. + +"""Curated data subset for the JupyterLite browser documentation.""" + +from .lite_data import data_path, get_version diff --git a/mne/datasets/lite_data/lite_data.py b/mne/datasets/lite_data/lite_data.py new file mode 100644 index 00000000000..02122e2080f --- /dev/null +++ b/mne/datasets/lite_data/lite_data.py @@ -0,0 +1,49 @@ +# Authors: The MNE-Python contributors. +# License: BSD-3-Clause +# Copyright the MNE-Python contributors. + +"""Curated data subset used by the JupyterLite browser documentation. + +``lite_data`` holds the data files needed to run the tutorials and examples in +the browser, taken from ``sample``, ``kiloword``, ``erp_core``, ``mtrf`` and +``eegbci``. The files are unchanged and keep the same checksums as the full +datasets. It extracts to ``MNE-lite-data/`` with each file under its original +dataset folder (``MNE-sample-data/``, ``MNE-kiloword-data/``, ...), so paths +match. + +Those datasets ship as separate multi-GB archives, so without this the +documentation build would download several gigabytes to serve a handful of +files. + +The ``somato`` dataset is not included, so the somatosensory tutorials and +examples do not run in the browser. +""" + +from ...utils import verbose +from ..utils import _data_path_doc, _download_mne_dataset, _get_version, _version_doc + + +@verbose +def data_path( + path=None, force_update=False, update_path=True, download=True, *, verbose=None +): # noqa: D103 + return _download_mne_dataset( + name="lite_data", + processor="untar", + path=path, + force_update=force_update, + update_path=update_path, + download=download, + ) + + +data_path.__doc__ = _data_path_doc.format( + name="lite_data", conf="MNE_DATASETS_LITE_DATA_PATH" +) + + +def get_version(): # noqa: D103 + return _get_version("lite_data") + + +get_version.__doc__ = _version_doc.format(name="lite_data") diff --git a/mne/datasets/tests/test_datasets.py b/mne/datasets/tests/test_datasets.py index a7f985392e7..53bdb1b5b2a 100644 --- a/mne/datasets/tests/test_datasets.py +++ b/mne/datasets/tests/test_datasets.py @@ -322,3 +322,18 @@ def test_fetch_uncompressed_file(tmp_path): ) fetch_dataset(dataset_dict, path=None, force_update=True) assert (tmp_path / "foo" / "LICENSE.foo").is_file() + + +def test_lite_data(): + """Test the lite_data curated dataset is registered correctly.""" + from mne.datasets import lite_data + from mne.datasets.config import MNE_DATASETS + + assert "lite_data" in MNE_DATASETS + cfg = MNE_DATASETS["lite_data"] + assert cfg["archive_name"] == "MNE-lite-data.tar.gz" + assert cfg["hash"].startswith("md5:") + assert cfg["url"].startswith("https://osf.io/") + assert cfg["config_key"] == "MNE_DATASETS_LITE_DATA_PATH" + assert callable(lite_data.data_path) + assert callable(lite_data.get_version) diff --git a/mne/utils/config.py b/mne/utils/config.py index a33779fb442..adc72b92796 100644 --- a/mne/utils/config.py +++ b/mne/utils/config.py @@ -170,6 +170,7 @@ def set_memmap_min_size(memmap_min_size): "MNE_DATASETS_TESTING_PATH": "str, path for testing data", "MNE_DATASETS_VISUAL_92_CATEGORIES_PATH": "str, path for visual_92_categories data", "MNE_DATASETS_KILOWORD_PATH": "str, path for kiloword data", + "MNE_DATASETS_LITE_DATA_PATH": "str, path for lite_data data", "MNE_DATASETS_FIELDTRIP_CMC_PATH": "str, path for fieldtrip_cmc data", "MNE_DATASETS_PHANTOM_KIT_PATH": "str, path for phantom_kit data", "MNE_DATASETS_PHANTOM_4DBTI_PATH": "str, path for phantom_4dbti data",