Dataloader

This module provides functionality for loading the state (spike train or rate) of the simulated networks.

hetero.dataloader.load_mmap(file_path)

Creates a memory-mapped array from a NumPy .npy file. This function opens a NumPy .npy file and creates a memory-mapped array that allows direct access to the data on disk without fully loading it into memory. It reads the file header to determine the array’s shape, data type, and memory layout (C or Fortran order).

Parameters:

file_path (str) – Path to the .npy file to be memory-mapped.

Returns:

A memory-mapped array that shares the same data as the array stored in the .npy file. The array is opened in read-only mode.

Return type:

numpy.memmap

Note

The function handles the .npy file format internally by:

1. Reading the magic number to verify file format and version

2. Parsing the header to get array metadata

3. Creating a memory map starting at the data offset

The resulting memmap allows efficient access to large arrays without loading them entirely into memory.

hetero.dataloader.raster2array(raster_it, n_neurons, n_timesteps)

Converts the spike train dictionary (raster) to a binary numpy array.

Parameters:

• raster (dict) – Dictionary containing spike data with keys: - i: neuron indices - tick: spike times index

• n_neurons (int) – Total number of neurons

• n_timesteps (int) – Total number of timesteps

Returns:

Binary array of shape (n_neurons, n_timesteps)

Return type:

ndarray

hetero.dataloader.convolve(st_array, kernel, verbose=False, **kwargs)

Apply temporal filtering to spike trains. kwargs is expected to provide the kernel parameter (sigma, or tau_k) in the unif of timesteps. All causal kernels are normalized to 1.

Parameters:

• st_array (ndarray) – Binary spike array of shape (N_neurons, N_timesteps)

• kernel (str) –

  Kernel type, one of:

  • ’None’ or None: No filtering (returns the binary spike train)

  • ’gaussian’: half Gaussian (causal). Requires sigma.

  • ’gaussian_nc’: full Gaussian (non-causal). Requires sigma.

  • ’alpha’: Alpha kernel. Requires tau_k.

  • ’exp’: Exponential decay. Requires tau_k.

  • ’moving_avg’: Mean count over a constant window. Requires win.

• verbose (bool, optional) – Print kernel info (default: False)

Returns:

Filtered spike trains of same shape as input

Return type:

ndarray

hetero.dataloader.load_states(sim_path, net_id, state_name, activation_params, n_neuron=None, n_timesteps=None, verbose=True)

Load neural states for a given simulation and network, and further process them according to specified activation_params.

Parameters:

• sim_path (str) – Filesystem path to the simulation data root (passed to the internal loader).

• net_id (str) – Identifier for the network instance within the simulation (passed to the internal loader).

• state_name (str) – Name/key of the state to load (e.g. “spikes”, “voltage”, etc.; passed to the internal loader).

• activation_params (dict) –

  Readout activation settings. Valid keys are defined in the config module and can be extended. The following are provided by default:

  • ’None’ or ‘none’ or None: no activation, return raw states (wheter rate or spikes).

  • ’rate’: apply an activation function to the voltage traces.

  • ’array’: convert spike raster dict to dense array (with no convolution).

  • Custom kernels based on Gaussian, exponential decay, alpha function, and moving average, that convolve the arrayed spike trains.

• n_neuron (int, optional) – Number of neurons expected when converting raster dictionaries to arrays. Required by raster2array if the input is in raster/dict form and an array shape must be produced. If None, raster2array may infer size or raise.

• n_timesteps (int, optional) – Number of time steps expected when converting raster dictionaries to arrays. Required by raster2array to shape the output array if not inferred.

• verbose (bool, default True) – If True, pass verbosity flags down to helper functions (activation_func, convolve).

Returns:

states –

The loaded and post-processed state data. The exact type depends on the readout:

• Unchanged raw object for ‘None’ readout (whatever _loader returns).

• numpy.ndarray or similar for ‘rate’ (result of activation_func).

• numpy.ndarray for ‘array’ and convolved readouts (raster2array and convolve results).

Return type:

object

Raises:

ValueError – If the selected readout method is not supported by the function. (i.e., not one of None/’None’, ‘rate’, ‘array’, or a kernel readout as described above).

Note

• readout_params[‘readout_activation’] is expected to contain exactly one mapping; the function uses the first (and typically only) item to select the readout.

• Helper functions referenced here (internal loader, activation_func, raster2array, convolve) must be available in the module’s scope and accept the arguments as described in the readout_params contract.

• This function performs no file or network I/O itself beyond delegating to the internal loader; it primarily orchestrates loading + post-processing.