src.canns.data

Data utilities for CANNs.

This module provides dataset management, loading, and downloading utilities. It consolidates data-related functionality previously scattered across the codebase.

Submodules

• src.canns.data.datasets
• src.canns.data.loaders

Attributes

DATASETS
DEFAULT_DATA_DIR
HUGGINGFACE_REPO

Functions

download_dataset(dataset_key[, force])	Download a specific dataset.
get_data_dir()	Get the data directory, creating it if necessary.
get_dataset_path(dataset_key[, auto_setup])	Get path to a dataset, downloading/setting up if necessary.
get_huggingface_upload_guide()	Get guide for uploading datasets to Hugging Face.
list_datasets()	List available datasets with descriptions.
load(url[, cache_dir, force_download, file_type])	Universal data loading function that downloads and reads data from URLs.
load_grid_data([source, dataset_key])	Load grid cell data for 2D CANN analysis.
load_roi_data([source])	Load ROI data for 1D CANN analysis.
quick_setup()	Quick setup function to get datasets ready.

Package Contents

src.canns.data.download_dataset(dataset_key, force=False)

Download a specific dataset.

Parameters:

• dataset_key (str) – Key of the dataset to download (e.g., ‘grid_1’, ‘roi_data’).

• force (bool) – Whether to force re-download if file already exists.

Returns:

Path to downloaded file if successful, None otherwise.

Return type:

Path or None

src.canns.data.get_data_dir()

Get the data directory, creating it if necessary.

src.canns.data.get_dataset_path(dataset_key, auto_setup=True)

Get path to a dataset, downloading/setting up if necessary.

Parameters:

• dataset_key (str) – Key of the dataset.

• auto_setup (bool) – Whether to automatically attempt setup if dataset not found.

Returns:

Path to dataset file if available, None otherwise.

Return type:

Path or None

src.canns.data.get_huggingface_upload_guide()

Get guide for uploading datasets to Hugging Face.

Returns:

Upload guide text.

Return type:

str

src.canns.data.list_datasets()

List available datasets with descriptions.

src.canns.data.load(url, cache_dir=None, force_download=False, file_type=None)

Universal data loading function that downloads and reads data from URLs.

Parameters:

• url (str) – URL to download data from.

• cache_dir (str or Path, optional) – Directory to cache downloaded files. If None, uses temporary directory.

• force_download (bool) – Force re-download even if file exists in cache.

• file_type (str, optional) – Force specific file type (‘text’, ‘numpy’, ‘json’, ‘pickle’, ‘hdf5’). If None, auto-detect from file extension.

Returns:

Loaded data.

Return type:

Any

Examples

>>> # Load numpy data
>>> data = load('https://example.com/data.npz')
>>>
>>> # Load text data with custom cache
>>> data = load('https://example.com/data.txt', cache_dir='./cache')
>>>
>>> # Force specific file type
>>> data = load('https://example.com/data.bin', file_type='numpy')

src.canns.data.load_grid_data(source=None, dataset_key='grid_1')

Load grid cell data for 2D CANN analysis.

Parameters:

• source (str, Path, or None) – Data source. Can be: - URL string: downloads and loads from URL - Path: loads from local file - None: uses default CANNs dataset

• dataset_key (str) – Which default dataset to use (‘grid_1’ or ‘grid_2’) when source is None.

Returns:

Dictionary containing spike data and metadata if successful, None otherwise. Expected keys: ‘spike’, ‘t’, and optionally ‘x’, ‘y’ for position data.

Return type:

dict or None

Examples

>>> # Load default dataset
>>> grid_data = load_grid_data()
>>>
>>> # Load from URL
>>> grid_data = load_grid_data('https://example.com/grid_data.npz')
>>>
>>> # Load specific default dataset
>>> grid_data = load_grid_data(dataset_key='grid_2')

src.canns.data.load_roi_data(source=None)

Load ROI data for 1D CANN analysis.

Parameters:

source (str, Path, or None) – Data source. Can be: - URL string: downloads and loads from URL - Path: loads from local file - None: uses default CANNs dataset

Returns:

ROI data array if successful, None otherwise.

Return type:

ndarray or None

Examples

>>> # Load default dataset
>>> roi_data = load_roi_data()
>>>
>>> # Load from URL
>>> roi_data = load_roi_data('https://example.com/roi_data.txt')
>>>
>>> # Load from local file
>>> roi_data = load_roi_data('./my_roi_data.txt')

src.canns.data.quick_setup()

Quick setup function to get datasets ready.

Returns:

True if successful, False otherwise.

Return type:

bool

src.canns.data.DATASETS

src.canns.data.DEFAULT_DATA_DIR

src.canns.data.HUGGINGFACE_REPO = 'canns-team/data-analysis-datasets'