pulse2percept.datasets.base

get_data_dir, clear_data_dir, has_network, osf_is_reachable, download_from_osf, fetch_url

Functions

clear_data_dir([data_dir])

Delete all content in the data directory

download_from_osf(osf_id_or_url, filename[, ...])

Download a file from OSF into the data directory (once)

fetch_url(url, file_path[, progress_bar, ...])

Download a remote file

get_data_dir([data_dir])

Return the path of the pulse2percept data directory

has_network([timeout])

Check for general network connectivity

osf_is_reachable([test_url, timeout])

Check whether OSF downloads are reachable
pulse2percept.datasets.base.get_data_dir(data_dir=None)[source]

Return the path of the pulse2percept data directory

This directory is used to store the datasets retrieved by the data fetch utility functions to avoid downloading the data several times.

By default, this is set to a directory called ‘pulse2percept_data’ in the user home directory. Alternatively, it can be set by a PULSE2PERCEPT_DATA environment variable or set programmatically by specifying a path.

If the directory does not already exist, it is automatically created.

Added in version 0.6.

Parameters:

data_dir (str or None) – The path to the pulse2percept data directory.

pulse2percept.datasets.base.clear_data_dir(data_dir=None)[source]

Delete all content in the data directory

By default, this is set to a directory called ‘pulse2percept_data’ in the user home directory. Alternatively, it can be set by a PULSE2PERCEPT_DATA environment variable or set programmatically by specifying a path.

Added in version 0.6.

Parameters:

data_dir (str or None) – The path to the pulse2percept data directory.

pulse2percept.datasets.base.has_network(timeout=3.0)[source]

Check for general network connectivity

Attempts TCP connections to a small set of well-known hosts (e.g., DNS and OSF). If any connection succeeds within the timeout, the host is considered online. This is a fast pre-flight check that avoids unnecessary download attempts.

Parameters:

timeout (float, optional) – Timeout in seconds for each connectivity attempt. Default is 3.0.

Returns:

True if at least one probe succeeds; False otherwise.

Return type:

bool

pulse2percept.datasets.base.fetch_url(url, file_path, progress_bar=<function _report_hook>, remote_checksum=None)[source]

Download a remote file

Fetch a dataset pointed to by url, check its SHA-256 checksum for integrity, and save it to file_path.

Added in version 0.6.

Parameters:

  • url (string) – URL of file to download

  • file_path (string) – Path to the local file that will be created

  • progress_bar (func callback, optional) – A callback to a function func(count, block_size, total_size) that will display a progress bar.

  • remote_checksum (str, optional) – The expected SHA-256 checksum of the file.

pulse2percept.datasets.base.osf_is_reachable(test_url='https://osf.io/rduj4', timeout=5.0)[source]

Check whether OSF downloads are reachable

Probes OSF by normalizing the given URL or GUID to the direct download form (https://osf.io/download/<GUID>) and issuing a quick HEAD request. If HEAD is not supported, falls back to fetching a few bytes with GET. No files are written to disk.

Parameters:

  • test_url (str, optional) – An OSF GUID or URL used for the probe (defaults to a tiny file you own).

  • timeout (float, optional) – Request timeout in seconds. Default is 5.0.

Returns:

True if OSF responds successfully; False otherwise.

Return type:

bool

pulse2percept.datasets.base.download_from_osf(osf_id_or_url, filename, checksum=None, data_path=None, download_if_missing=True, progress_bar=<function _report_hook>)[source]

Download a file from OSF into the data directory (once)

Normalizes an OSF GUID or URL to the direct download endpoint (https://osf.io/download/<GUID>), performs quick pre-flight checks (general network + OSF reachability), and downloads the file via fetch_url(). If the file already exists, it is not downloaded again.

Parameters:

  • osf_id_or_url (str) – OSF GUID (e.g., 'pf2ja') or OSF URL (with or without /download).

  • filename (str) – Local filename to save under the data directory (e.g., 'han2021.zip').

  • checksum (str or None, optional) – Expected SHA-256 hex digest. If provided, integrity is verified.

  • data_path (str or None, optional) – Custom data directory. Defaults to get_data_dir().

  • download_if_missing (bool, optional) – If False and the file is missing locally, raises an IOError instead of downloading. Default is True.

  • progress_bar (callable, optional) – Progress callback with signature func(count, block_size, total_size). Defaults to _report_hook().

Returns:

Absolute path to the downloaded (or already present) local file.

Return type:

str

Raises:

IOError – If the file is missing and download_if_missing is False; if there is no network connectivity; if OSF is unreachable; or if the checksum verification fails.