Trace Data Conversion (sanafe.data)

The sanafe.data module converts SANA-FE trace outputs into other useful formats, e.g., Pandas.

Conversion functions accept inputs using many different types:

  • a path or Path to a CSV produced by chip.sim()

  • the dict returned by chip.sim()

  • the raw in-memory values

  • a DataFrame (returned as-is)

Quickstart

Build a small network, run a simulation with all traces enabled, and convert each trace into a DataFrame:

import sanafe
import sanafe.data
import pandas

arch, _ = sanafe.load_example()
snn = sanafe.Network()
group = snn.create_neuron_group(
    "in", 2, {"bias": 0.5, "threshold": 1.0, "reset": 0.0},
    log_spikes=True, log_potential=True)
for neuron in group:
    neuron.map_to_core(arch.tiles[0].cores[0])

chip = sanafe.SpikingChip(arch)
chip.load(snn)
results_dict = chip.sim(5, spike_trace=True, potential_trace=True,
                        perf_trace=True, message_trace=True,
                        neuron_trace=True)

sanafe.data.spikes_to_raster(results_dict, n_timesteps=5)
sanafe.data.spikes_to_dataframe(results_dict)
sanafe.data.potentials_to_dataframe(results_dict)
sanafe.data.performance_to_dataframe(results_dict)
sanafe.data.messages_to_dataframe(results_dict)
sanafe.data.neuron_traces_to_dataframe(results_dict)
sanafe.data.spikes_to_raster(source: Any, groups: Sequence[str] | None = None, time_range: Tuple[int, int] | None = None, n_timesteps: int | None = None) → Tuple[np.ndarray, list[str], np.ndarray][source]

Convert a spike trace into a dense 2D raster matrix.

Parameters:

  • source – The spike trace data. May be a pandas.DataFrame, a path to a CSV file, the dict returned by chip.sim(), or the raw spike_trace values i.e., a per-timestep list, where each element is a list of spiking neurons for that timestep.

  • groups – Optional subset of neuron groups to include. Row order in the returned matrix follows the order given here; when omitted, all groups are included in sorted order.

  • time_range (tuple(int, int), optional) – Optional (start, stop) half-open interval of timesteps to include. When omitted, spans from the minimum to maximum timestep present in the data.

  • n_timesteps (int, optional) – Optional explicit number of columns in the matrix. Useful when the trace ends before the simulation does (e.g., no spikes in the final timesteps) and you want the matrix to span the full run. Ignored when time_range is given.

Returns:

A 3-tuple (matrix, neuron_ids, timesteps) where

  • matrix is a 2D boolean numpy.ndarray of shape (n_neurons, n_timesteps) with True where a spike occurred.

  • neuron_ids is a list of "group.offset" strings labelling each row of the matrix.

  • timesteps is a 1D numpy.ndarray giving the timestep index for each column.

Return type:

tuple

Raises:

ValueError – If no spike trace data can be found in source, or if groups contains unknown group names.

sanafe.data.spikes_to_dataframe(source: Any) → DataFrame[source]

Convert a spike trace into a pandas DataFrame.

Parameters:

source (pandas.DataFrame or Path or str or dict or list[list[NeuronAddress]]) – The spike trace data. May be a pandas.DataFrame, a path to a CSV file, the dict returned by chip.sim(), or the raw spike_trace value. In memory, spike traces are a per-timestep list, with each entry a list of NeuronAddress of neurons that fired that timestep.

Returns:

A DataFrame with columns timestep, group, neuron_offset, and neuron_id.

Return type:

pandas.DataFrame

Raises:

ValueError – If no spike trace data can be found in source.

sanafe.data.potentials_to_dataframe(source: Any, neuron_ids: Sequence[str] | None = None) → DataFrame[source]

Convert a membrane-potential trace into a pandas DataFrame indexed by timestep.

Parameters:

  • source (pandas.DataFrame or str or Path or dict or list[list[float]]) – The potential trace data. May be a pandas.DataFrame, a path to a CSV file, the dict returned by chip.sim(), or a 2D array of potential_trace values (i.e., a per-timestep list, containing per-neuron lists of potentials).

  • neuron_ids (List[str]) – Optional column labels for the neurons. When omitted, columns are named Neuron 0, Neuron 1, and so on. Only used when source is in-memory trace data.

Returns:

A DataFrame whose index is named timestep and whose columns correspond to individual neurons.

Return type:

pandas.DataFrame

Raises:

ValueError – If no potential trace data is found, or if neuron_ids length does not match the number of trace columns.

sanafe.data.performance_to_dataframe(source: Any) → DataFrame[source]

Convert a performance trace into a DataFrame.

Parameters:

dict (source (pandas.DataFrame or Path or str or) – The performance trace data. May be a pandas.DataFrame, a path to a CSV file, the dict from chip.sim() or a dict containing performance data (dict[str, list], i.e. lists of per-timestep values for each metric).

Returns:

A DataFrame of per-timestep performance metrics.

Return type:

pandas.DataFrame

Raises:

ValueError – If no performance trace data can be found in source.

sanafe.data.messages_to_dataframe(source: Any) → DataFrame[source]

Convert a message trace into a flat pandas DataFrame, one row per message.

In addition, convenience identifier columns are derived when their components are present:

  • src_neuron from src_neuron_group_id and src_neuron_offset

  • src_hw from src_tile_id and src_core_offset

  • dest_hw from dest_tile_id and dest_core_offset

Parameters:

source (pandas.DataFrame or Path or str or dict or list[list[dict]]) – The message trace data. May be a pandas.DataFrame, a path to a CSV file, the dict returned by chip.sim(), or the raw message_trace values.

Returns:

A DataFrame with one row per message.

Return type:

pandas.DataFrame

Raises:

ValueError – If no message trace data can be found in source.