
.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "generated/auto_examples/core/tutorial_eegdash_offline.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_generated_auto_examples_core_tutorial_eegdash_offline.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_generated_auto_examples_core_tutorial_eegdash_offline.py:

============================
Working Offline with EEGDash
============================

Many HPC clusters restrict or block network access. It's common to have
dedicated queues for internet-enabled jobs that differ from GPU queues.
This tutorial shows how to use EEGDash offline once a dataset is present
on disk.

.. GENERATED FROM PYTHON SOURCE LINES 10-74

.. code-block:: Python


    from pathlib import Path
    import platformdirs

    from eegdash.const import RELEASE_TO_OPENNEURO_DATASET_MAP
    from eegdash.dataset.dataset import EEGChallengeDataset


    # We'll use Release R2 as an example (HBN subset). EEGChallengeDataset uses a
    # suffixed cache folder for the competition data (e.g., "-bdf-mini").
    release = "R2"
    dataset_id = RELEASE_TO_OPENNEURO_DATASET_MAP[release]
    task = "RestingState"
    # Choose a cache directory. This should be on a fast local filesystem.
    cache_dir = Path(platformdirs.user_cache_dir("EEGDash"))
    cache_dir.mkdir(parents=True, exist_ok=True)

    # ######################################################################
    # Step 1: Populate the local cache (Online)
    # -----------------------------------------
    # This block downloads the dataset from S3 to your local cache directory.
    # Run this part on a machine with internet access. If the dataset is already
    # on your disk at the specified ``cache_dir``, you can comment out or skip
    # this section.
    #
    # To keep this example self-contained, we prefetch the data here.

    ds_online = EEGChallengeDataset(
        release=release,
        cache_dir=cache_dir,
        task=task,
        mini=True,
    )

    # Optional prefetch of all recordings (downloads everything to cache).
    from joblib import Parallel, delayed

    _ = Parallel(n_jobs=-1)(delayed(lambda d: d.raw)(d) for d in ds_online.datasets)


    # ######################################################################
    # Step 2: Basic Offline Usage
    # ---------------------------
    # Once the data is cached locally, you can interact with it without needing an
    # internet connection. The key is to instantiate your dataset object with the
    # ``download=False`` flag. This tells EEGDash to look for data in the
    # ``cache_dir`` instead of trying to connect to the database or S3.


    # Here we check that the local cache folder exists
    offline_root = cache_dir / f"{dataset_id}-bdf-mini"
    print(f"Local dataset folder exists: {offline_root.exists()}\n{offline_root}")

    ds_offline = EEGChallengeDataset(
        release=release,
        cache_dir=cache_dir,
        task=task,
        download=False,
    )

    print(f"Found {len(ds_offline.datasets)} recording(s) offline.")
    if ds_offline.datasets:
        print("First record bidspath:", ds_offline.datasets[0].record["bidspath"])





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    /Users/baristim/Projects/EEGDash-2/eegdash/dataset/dataset.py:126: UserWarning: 

    [EEGChallengeDataset] EEG 2025 Competition Data Notice:
    -------------------------------------------------------
    This object loads the HBN dataset that has been preprocessed for the EEG Challenge:
      - Downsampled from 500Hz to 100Hz
      - Bandpass filtered (0.5–50 Hz)

    For full preprocessing details, see:
      https://github.com/eeg2025/downsample-datasets

    IMPORTANT: The data accessed via `EEGChallengeDataset` is NOT identical to what you get from `EEGDashDataset` directly.
    If you are participating in the competition, always use `EEGChallengeDataset` to ensure consistency with the challenge data.


      warn(
    Local dataset folder exists: True
    /Users/baristim/Library/Caches/EEGDash/ds005506-bdf-mini
    /Users/baristim/Projects/EEGDash-2/eegdash/dataset/dataset.py:126: UserWarning: 

    [EEGChallengeDataset] EEG 2025 Competition Data Notice:
    -------------------------------------------------------
    This object loads the HBN dataset that has been preprocessed for the EEG Challenge:
      - Downsampled from 500Hz to 100Hz
      - Bandpass filtered (0.5–50 Hz)

    For full preprocessing details, see:
      https://github.com/eeg2025/downsample-datasets

    IMPORTANT: The data accessed via `EEGChallengeDataset` is NOT identical to what you get from `EEGDashDataset` directly.
    If you are participating in the competition, always use `EEGChallengeDataset` to ensure consistency with the challenge data.


      warn(
    Found 20 recording(s) offline.
    First record bidspath: ds005506/sub-NDARAB793GL3/eeg/sub-NDARAB793GL3_task-RestingState_eeg.bdf




.. GENERATED FROM PYTHON SOURCE LINES 75-83

%%
######################################################################
Step 3: Filtering Entities Offline
----------------------------------
Even without a database connection, you can still filter your dataset by
BIDS entities like subject, session, or task. When ``download=False``, EEGDash
uses the BIDS directory structure and filenames to apply these filters. This
example shows how to load data for a specific subject from the local cache.

.. GENERATED FROM PYTHON SOURCE LINES 83-140

.. code-block:: Python


    ds_offline_sub = EEGChallengeDataset(
        cache_dir=cache_dir,
        release=release,
        download=False,
        subject="NDARAB793GL3",
    )

    print(f"Filtered by subject=NDARAB793GL3: {len(ds_offline_sub.datasets)} recording(s).")
    if ds_offline_sub.datasets:
        keys = ("dataset", "subject", "task", "run")
        print("Records (dataset, subject, task, run):")
        for idx, base_ds in enumerate(ds_offline_sub.datasets, start=1):
            rec = base_ds.record
            summary = ", ".join(f"{k}={rec.get(k)}" for k in keys)
            print(f"  {idx:03d}: {summary}")


    # ######################################################################
    # Step 4: Comparing Online vs. Offline Data
    # -----------------------------------------
    # As a sanity check, you can verify that the data loaded from your local cache
    # is identical to the data fetched from the online sources. This section
    # compares the shape of the raw data from the online and offline datasets to
    # ensure they match. This is a good way to confirm your local cache is complete
    # and correct.
    #
    # If you have network access, you can uncomment the block below to download and
    # compare shapes.

    raw_online = ds_online.datasets[0].raw
    raw_offline = ds_offline.datasets[0].raw
    print("online shape:", raw_online.get_data().shape)
    print("offline shape:", raw_offline.get_data().shape)
    print("shapes equal:", raw_online.get_data().shape == raw_offline.get_data().shape)

    # ######################################################################
    # Step 4.1: Comparing Descriptions, Online vs. Offline Data
    # ---------------------------------------------------------
    #
    # If you have network access, you can uncomment the block below to download and
    # compare shapes.
    description_online = ds_online.description
    description_offline = ds_offline.description
    print(description_offline)
    print(description_online)
    print("Online description shape:", description_online.shape)
    print("Offline description shape:", description_offline.shape)
    print("Descriptions equal:", description_online.equals(description_offline))

    # ######################################################################
    # Notes and troubleshooting
    # -------------------------
    # - Working offline selects recordings by parsing BIDS filenames and directory
    #   structure. Some DB-only fields are unavailable; entity filters (subject,
    #   session, task, run) usually suffice.
    # - If you encounter issues, please open a GitHub issue so we can discuss.




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    /Users/baristim/Projects/EEGDash-2/eegdash/dataset/dataset.py:126: UserWarning: 

    [EEGChallengeDataset] EEG 2025 Competition Data Notice:
    -------------------------------------------------------
    This object loads the HBN dataset that has been preprocessed for the EEG Challenge:
      - Downsampled from 500Hz to 100Hz
      - Bandpass filtered (0.5–50 Hz)

    For full preprocessing details, see:
      https://github.com/eeg2025/downsample-datasets

    IMPORTANT: The data accessed via `EEGChallengeDataset` is NOT identical to what you get from `EEGDashDataset` directly.
    If you are participating in the competition, always use `EEGChallengeDataset` to ensure consistency with the challenge data.


      warn(
    Filtered by subject=NDARAB793GL3: 1 recording(s).
    Records (dataset, subject, task, run):
      001: dataset=ds005506, subject=NDARAB793GL3, task=RestingState, run=None
    online shape: (129, 40800)
    offline shape: (129, 40800)
    shapes equal: True
             subject          task      age sex  ... surroundsupp_2  seqlearning6target seqlearning8target symbolsearch
    0   NDARAB793GL3  RestingState  13.4391   M  ...      available         unavailable          available    available
    1   NDARAM675UR8  RestingState   5.5485   F  ...      available           available        unavailable    available
    2   NDARBM839WR5  RestingState   9.4003   M  ...      available         unavailable          available    available
    3   NDARBU730PN8  RestingState  13.7506   F  ...      available         unavailable          available    available
    4   NDARCT974NAJ  RestingState  17.6467   F  ...      available         unavailable          available    available
    5   NDARCW933FD5  RestingState  11.3337   F  ...      available         unavailable          available    available
    6   NDARCZ770BRG  RestingState   8.8827   M  ...      available         unavailable          available    available
    7   NDARDW741HCF  RestingState   7.8647   M  ...      available           available        unavailable    available
    8   NDARDZ058NZN  RestingState   6.5610   M  ...      available           available        unavailable    available
    9   NDAREC377AU2  RestingState  10.1290   F  ...      available         unavailable          available    available
    10  NDAREM500WWH  RestingState   5.5295   M  ...      available           available        unavailable    available
    11  NDAREV527ZRF  RestingState  11.7877   F  ...      available         unavailable          available    available
    12  NDAREV601CE7  RestingState  12.8719   M  ...      available         unavailable          available    available
    13  NDARFF070XHV  RestingState  11.2455   F  ...      available         unavailable          available    available
    14  NDARFR108JNB  RestingState   7.1394   F  ...      available           available        unavailable    available
    15  NDARFT305CG1  RestingState   8.5816   M  ...      available           available        unavailable    available
    16  NDARGA056TMW  RestingState  15.3003   M  ...      available         unavailable          available    available
    17  NDARGH775KF5  RestingState  10.7992   M  ...      available         unavailable          available    available
    18  NDARGJ878ZP4  RestingState   7.2675   F  ...      available           available        unavailable    available
    19  NDARHA387FPM  RestingState  11.2489   M  ...      available         unavailable          available    available

    [20 rows x 25 columns]
             subject          task      age sex  ... surroundsupp_2  seqlearning6target seqlearning8target symbolsearch
    0   NDARAB793GL3  RestingState  13.4391   M  ...      available         unavailable          available    available
    1   NDARAM675UR8  RestingState   5.5485   F  ...      available           available        unavailable    available
    2   NDARBM839WR5  RestingState   9.4003   M  ...      available         unavailable          available    available
    3   NDARBU730PN8  RestingState  13.7506   F  ...      available         unavailable          available    available
    4   NDARCT974NAJ  RestingState  17.6467   F  ...      available         unavailable          available    available
    5   NDARCW933FD5  RestingState  11.3337   F  ...      available         unavailable          available    available
    6   NDARCZ770BRG  RestingState   8.8827   M  ...      available         unavailable          available    available
    7   NDARDW741HCF  RestingState   7.8647   M  ...      available           available        unavailable    available
    8   NDARDZ058NZN  RestingState   6.5610   M  ...      available           available        unavailable    available
    9   NDAREC377AU2  RestingState  10.1290   F  ...      available         unavailable          available    available
    10  NDAREM500WWH  RestingState   5.5295   M  ...      available           available        unavailable    available
    11  NDAREV527ZRF  RestingState  11.7877   F  ...      available         unavailable          available    available
    12  NDAREV601CE7  RestingState  12.8719   M  ...      available         unavailable          available    available
    13  NDARFF070XHV  RestingState  11.2455   F  ...      available         unavailable          available    available
    14  NDARFR108JNB  RestingState   7.1394   F  ...      available           available        unavailable    available
    15  NDARFT305CG1  RestingState   8.5816   M  ...      available           available        unavailable    available
    16  NDARGA056TMW  RestingState  15.3003   M  ...      available         unavailable          available    available
    17  NDARGH775KF5  RestingState  10.7992   M  ...      available         unavailable          available    available
    18  NDARGJ878ZP4  RestingState   7.2675   F  ...      available           available        unavailable    available
    19  NDARHA387FPM  RestingState  11.2489   M  ...      available         unavailable          available    available

    [20 rows x 25 columns]
    Online description shape: (20, 25)
    Offline description shape: (20, 25)
    Descriptions equal: True





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 13.646 seconds)

**Estimated memory usage:**  1033 MB


.. _sphx_glr_download_generated_auto_examples_core_tutorial_eegdash_offline.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: tutorial_eegdash_offline.ipynb <tutorial_eegdash_offline.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: tutorial_eegdash_offline.py <tutorial_eegdash_offline.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: tutorial_eegdash_offline.zip <tutorial_eegdash_offline.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_
