eegdash.downloader module#

File downloading utilities for EEG data from cloud storage.

This module provides functions for downloading EEG data files and BIDS dependencies from AWS S3 storage, with support for caching and progress tracking. It handles the communication between the EEGDash metadata database and the actual EEG data stored in the cloud.

eegdash.downloader.download_files(files: Sequence[tuple[str, Path]] | Iterable[tuple[str, Path]], *, filesystem: S3FileSystem | None = None, skip_existing: bool = True, skip_missing: bool = False) → list[Path][source]

Download multiple S3 URIs to local destinations.

Parameters:

  • files (iterable of (str, Path)) – Pairs of (S3 URI, local destination path).

  • filesystem (s3fs.S3FileSystem | None) – Optional pre-created filesystem to reuse across multiple downloads.

  • skip_existing (bool) – If True, do not download files that already exist locally.

  • skip_missing (bool) – If True, skip files that do not exist on S3 instead of raising.

eegdash.downloader.download_s3_file(s3_path: str, local_path: Path, *, filesystem: S3FileSystem | None = None) → Path[source]

Download a single file from S3 to a local path.

Handles the download of a raw EEG data file from an S3 bucket, caching it at the specified local path. Creates parent directories if they do not exist.

Parameters:

  • s3_path (str) – The full S3 URI of the file to download.

  • local_path (pathlib.Path) – The local file path where the downloaded file will be saved.

  • filesystem (s3fs.S3FileSystem | None) – Optional pre-created filesystem to reuse across multiple downloads.

Returns:

The local path to the downloaded file.

Return type:

pathlib.Path

eegdash.downloader.get_s3_filesystem() → S3FileSystem[source]

Get an anonymous S3 filesystem object.

Initializes and returns an s3fs.S3FileSystem for anonymous access to public S3 buckets, configured for the ‘us-east-2’ region.

Returns:

An S3 filesystem object.

Return type:

s3fs.S3FileSystem

eegdash.downloader.get_s3path(s3_bucket: str, filepath: str) → str[source]

Construct an S3 URI from a bucket and file path.

Parameters:

  • s3_bucket (str) – The S3 bucket name (e.g., “s3://my-bucket”).

  • filepath (str) – The path to the file within the bucket.

Returns:

The full S3 URI (e.g., “s3://my-bucket/path/to/file”).

Return type:

str