Utils

connectome_interpreter.utils.adjacency_df_to_el(adjacency, threshold=None)

Convert a DataFrame representing an adjacency matrix to an edge list.

This function takes a DataFrame where the index and columns represent nodes in the graph, and the values represent the weights of the edges between them. It converts this DataFrame to an edge list, where each row represents an edge in the graph, with columns ‘pre’, ‘post’, and ‘weight’.

Parameters:

• adjacency (pd.DataFrame) – A DataFrame representing an adjacency matrix.

• threshold (float, optional) – If provided, edges with values below this threshold are removed. Default to None.

Returns:

A DataFrame with columns ‘pre’, ‘post’, and ‘weight’, representing the edge list of the graph.

Return type:

pd.DataFrame

connectome_interpreter.utils.change_model_weights(model, df, mode, coefficient=0.1, offset=0, normalise=True)

Change the weights of the model based on the provided DataFrame. The DataFrame should contain columns ‘pre’ and ‘post’, and optionally ‘conditional’, which contain indices of the connectivity weights in model. The weights are modified proportional to: 1. The similarity of pre and post activations (i.e. the sum of element- wise multiplication of activations across time), and 2. The coefficient provided. 3. The similarity of conditional activations (if provided). offset specifies the time lag between the conditional neurons and the pre and post neurons.

The ‘mode’ column should specify whether the weight change is ltp or ltd.

Parameters:

• model (torch.nn.Module) – The model containing the weights to change.

• df (pd.DataFrame) – A DataFrame containing the columns ‘pre’ and ‘post’.

• mode (str) – The mode of weight change, either ‘ltp’ or ‘ltd’. coefficient (float): The coefficient to multiply the weight change by. Can be thought of as the ‘strength of plasticity’. Default to 0.1.

• offset (int) – Offset between the conditional neurons and the pre and post neurons. Default to 0. -1 means the conditional neurons’ activity precede the pre and post neurons, and the activity of conditional neurons at time t is related to the activity of pre and post neurons at time t+1.

• normalise (bool) – Whether to normalise the weights after changing them, such that absolute weights to postsynaptic neuron sums to 1. Default to True.

Returns:

This function modifies the model weights in place.

Return type:

None

connectome_interpreter.utils.check_consecutive_layers(df)

Check if the layers in the DataFrame are consecutive.

Parameters:

df (pd.DataFrame) – A DataFrame containing the column ‘layer’ (integer).

Returns:

True if the layers are consecutive, False otherwise

Return type:

bool

connectome_interpreter.utils.compare_connectivity(m1, m2, inidx1: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], outidx1: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], inidx2: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], outidx2: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], g1_pre: dict | None = None, g1_post: dict | None = None, g2_pre: dict | None = None, g2_post: dict | None = None, suffices: List[str] = ['_l', '_2'], display: bool = True, threshold: float = 0, sort_within: str = 'column', sort_by: str | None = None, threshold_axis: str = 'row', merge: str = 'outer', suffix_in: str = 'column')

Compare the connectivity between two matrices.

Parameters:

• m1 (scipy.sparse matrix or numpy.ndarray) – The first connectivity matrix.

• m2 (scipy.sparse matrix or numpy.ndarray) – The second connectivity matrix.

• inidx1 (int, float, list, set, numpy.ndarray, or pandas.Series) – The indices of the presynaptic neurons in the first matrix.

• outidx1 (int, float, list, set, numpy.ndarray, or pandas.Series) – The indices of the postsynaptic neurons in the first matrix.

• inidx2 (int, float, list, set, numpy.ndarray, or pandas.Series) – The indices of the presynaptic neurons in the second matrix.

• outidx2 (int, float, list, set, numpy.ndarray, or pandas.Series) – The indices of the postsynaptic neurons in the second matrix.

• g1_pre (dict, optional) – A dictionary mapping the presynaptic indices to groups in the first matrix. Defaults to None.

• g1_post (dict, optional) – A dictionary mapping the postsynaptic indices to groups in the first matrix. Defaults to None.

• g2_pre (dict, optional) – A dictionary mapping the presynaptic indices to groups in the second matrix. Defaults to None.

• g2_post (dict, optional) – A dictionary mapping the postsynaptic indices to groups in the second matrix. Defaults to None.

• suffices (list, optional) – A list of suffixes to append to the column names of the two matrices. Defaults to [‘_l’, ‘_2’].

• display (bool, optional) – Whether to display the resulting DataFrame in colour gradient. Defaults to True.

• threshold (float, optional) – The threshold below which to remove values. Defaults to 0.

• sort_within (str, optional) – Whether to sort the DataFrame with ‘column’ (across rows) or ‘row’ (across columns). Defaults to ‘column’.

• sort_by (str, optional) – The column to sort by. Defaults to None.

• threshold_axis (str, optional) – The axis to apply the threshold to. Defaults to

• 'row' (removing entire rows if no value exceeds display_threshold)

• merge (str, optional) – The type of merge to perform on the two DataFrames. When suffix_in is ‘row’ (separating input by suffices), the merge is performed on the columns of the two DataFrames. When suffix_in is ‘column’ (separating target by suffices), the merge is performed on the rows of the two DataFrames. Possible values are ‘inner’, ‘outer’, ‘left’, and ‘right’. Defaults to ‘outer’.

• suffix_in (str, optional) – Whether to put the suffixes on the rows or columns. Possible values are ‘row’ and ‘column’. Defaults to ‘column’.

Returns:

A DataFrame containing the connectivity values from the two matrices, with columns suffixed by the values in suffices.

Return type:

pd.DataFrame

connectome_interpreter.utils.coo_tensor_to_el(coo_tensor)

Convert a PyTorch sparse COO tensor to a DataFrame representing an edge list.

This function checks if the input tensor is sparse. If not, it converts it to a sparse COO tensor. It then extracts the indices and values, and creates a DataFrame with columns ‘pre’, ‘post’, and ‘weight’. Each row in the DataFrame represents an edge in the graph, where ‘pre’ and ‘post’ are the nodes connected by the edge, and ‘weight’ is the weight of the edge.

Parameters:

coo_tensor (torch.Tensor) – A PyTorch tensor, either already in sparse COO format or dense.

Returns:

A DataFrame with columns ‘pre’, ‘post’, and ‘weight’, representing the edge list of the graph.

Return type:

pd.DataFrame

connectome_interpreter.utils.coo_to_el(coo, row_indices=None, col_indices=None)

Extracts an edgelist from a COO matrix, optionally using pre-specified row and/or column indices. If row_indices or col_indices are None, all rows or columns are considered, respectively. Each row in the resulting DataFrame represents an edge in the graph, where ‘pre’ and ‘post’ are the nodes connected by the edge, and ‘value’ is the weight of the edge.

Parameters:

• coo – A scipy.sparse.coo_matrix instance.

• row_indices – Optional; A list or array of row indices of interest.

• col_indices – Optional; A list or array of column indices of interest.

Returns:

A DataFrame with columns ‘pre’, ‘post’, and ‘value’, representing the edge list of the graph.

Return type:

pd.DataFrame

connectome_interpreter.utils.count_keys_per_value(d)

Count the number of keys per value in a dictionary.

Parameters:

d (dict) – The input dictionary.

Returns:

A dictionary where each key is a value from the input dictionary, and each value is the number of keys that map to that value.

Return type:

dict

connectome_interpreter.utils.display_df(df, cmap=None, vmin=None, vmax=None, diverging=False)

Thin wrapper around the display function to display a DataFrame with a

background gradient.

Parameters:

• df (pd.DataFrame) – The DataFrame to display.

• cmap (str, optional) – The name of the colormap to use for the background gradient. If None (default), ‘RdBu_r’ is used when diverging=True (red is high) and ‘Blues’ otherwise.

• vmin (float, optional) – The minimum value for the colormap. If None, it defaults to -max(|df|) when diverging=True, otherwise the minimum value of the DataFrame.

• vmax (float, optional) – The maximum value for the colormap. If None, it defaults to +max(|df|) when diverging=True, otherwise the maximum value of the DataFrame.

• diverging (bool, optional) – If True, the colour scale is symmetric around zero so that 0 maps to the centre of the colormap. Use this when the DataFrame contains both positive and negative values and you want 0 to read as a neutral midpoint. Defaults to False.

Returns:

This function displays the DataFrame using the display function

Return type:

None

connectome_interpreter.utils.dynamic_representation(tensor, density_threshold=0.2)

Convert tensor to sparse if density is below threshold, otherwise to dense. This might be memory intensive.

connectome_interpreter.utils.get_activations(array, global_indices: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], idx_map: dict | None = None, top_n=None, threshold=None)

Get activation for neurons (in rows) in array for each time step (in columns). Optionally group neurons by idx_map, and filter by top_n or threshold.

Parameters:

• array (np.ndarray) – 2D array of neuron activations, where rows represent neurons and columns represent different time steps.

• global_indices (int, list, set, np.ndarray, pd.Series) – Array of global neuron indices corresponding to keys in idx_map.

• idx_map (dict, optional) – Mapping from neuron index (global_indices) to neuron identifier. If not None, and if multiple neurons map to the same identifier, the activations are averaged. Defaults to None.

• top_n (int, optional) – Number of top activations to return for each column. If None, all activations above the threshold are returned. Defaults to None.

• threshold (float, dict, optional) – Minimum activation level to consider. If a dictionary is provided, the threshold for each column is specified by the column index. Defaults to None.

Returns:

A dictionary where each key is a column index and each value is a nested dictionary of neuron identifiers and their activations, for those activations that are either in the top n, above the threshold, or both.

Return type:

dict

Note

The global_indices have to be in the same order as the indices in defining the original model. If both n and threshold are provided, the function returns up to top n activations that are also above the threshold for each column.

connectome_interpreter.utils.get_ngl_link(df: DataFrame | Series, no_connection_invisible: bool = True, group_by: dict | None = None, colour_saturation: float = 0.4, scene=None, source: list | None = None, normalise: str | None = None, diverging: bool = False, include_postsynaptic_neuron: bool = False, diff_colours_per_layer: bool = False, colors: list | None = None, colormap: str | None = None, df_format: str = 'wide', open_here: bool = False, width: int = 1500, height: int = 800) → str

Generates a Neuroglancer link with layers based on the neuron ids and the values in df.

Parameters:

• df (pandas.DataFrame or pandas.Series) – A DataFrame containing neuron metadata. If df_format == wide (default), the index should contain neuron identifiers (bodyId/root_ids), and columns should represent different attributes, timesteps or categories. If df_format == long, the DataFrame should contain three columns: ‘neuron_id’, ‘layer’, and ‘activation’.

• no_connection_invisible (bool, optional) – Whether to make invisible neurons that are not connected. Default to True (invisible).

• group_by (dict, optional) – A dictionary mapping neuron identifiers to group names. Each group will have its own layer. Default to None.

• colour_saturation (float, optional) – The saturation of the colours. Default to 0.4.

• scene (ngl.Scene, optional) – A Neuroglancer scene object from nglscenes package. You can read a scene from clipboard like scene = Scene.from_clipboard().

• source (list, optional) – The source of the Neuroglancer layers. Default to None, in which case Full Adult Fly Brain neurons are used.

• normalise (str, optional) – How to normalise the values. layer for normalising within each layer; all for normalising by the min and max value in the entire dataframe. Default to None.

• diverging (bool, optional) – If True, normalisation is symmetric around zero so that original 0 maps to the centre of the colormap. Use this when your data has both positive and negative values and you want 0 to read as a neutral midpoint. Default False.

• include_postsynaptic_neuron (bool, optional) – Whether to include the postsynaptic neuron (column names of df) in the visualisation. Default to False. Only works if df_format is ‘wide’.

• diff_colours_per_layer (bool, optional) – Whether to use different colours for each layer. Default to False.

• colors (list, optional) – A list of colours to use for the neurons in each layer, if diff_colours_per_layer is True. If None, a default list of colours is used. Default to None.

• colormap (str, optional) – Name of the colormap. If None (default), ‘RdBu_r’ is used (red represents higher values) when diverging=True and ‘viridis’ otherwise.

• df_format (str, optional) – The format of the DataFrame. Either ‘wide’ or ‘long’. Default to ‘wide’.

• open_here (bool, optional) – Whether to display the Neuroglancer scene in the notebook. Default to False.

• width (int, optional) – The width of the Neuroglancer scene. Default to 1500.

• height (int, optional) – The height of the Neuroglancer scene. Default to 800.

Returns:

A URL to the generated Neuroglancer scene.

Return type:

str

Note

The function assumes that the ‘scene1’ variable is defined in the

global scope and is an instance of ngl.Scene.

The function creates separate Neuroglancer layers for each column in

the DataFrame, using the column name as the layer name.

The root_ids are colored based on the values in the DataFrame, with a

color scale ranging from white (minimum value) to a specified color (maximum value).

The function relies on the Neuroglancer library for layer creation and

scene manipulation.

connectome_interpreter.utils.make_grid_inputs(v1: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], v2: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], num_layers: int, grid_size: int = 10, timepoints: int | list = 0, device=None, cap: bool = True, cap_value: float = 1.0) → Tuple[Tensor, List[Tuple[float, float]]]

Make a batch of input using combinations of v1 and v2 at different strengths (0 to 1).

Parameters:

• v1 – The first input vector.

• v2 – The second input vector. Its length should match that of v1.

• num_layers (int) – The number of layers in the model.

• grid_size (int, optional) – The number of points in the grid. Defaults to 10.

• timepoints (int|list, optional) – The timepoints at which combinations of v1 and v2 are used. Defaults to 0 (the first timepoint).

• device (str, optional) – The device to create the inputs on. If None, if GPU is available, the inputs are created on the GPU. Otherwise CPU.

• cap (bool, optional) – Whether to cap the values at cap_value. This is to prevent two inputs adding up to make a neuron activation > 1. Defaults to True.

• cap_value (float, optional) – The value to cap the inputs at. Defaults to 1.0.

Returns:

torch.Tensor:

A tensor of shape (grid_size**2, len(v1), num_layers).

list:

A list of grid coordinates.

Return type:

tuple

connectome_interpreter.utils.modify_coo_matrix(sparse_matrix, input_idx: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, output_idx: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, value=None, updates_df: DataFrame | None = None, re_normalize: bool = True)

Modify the values of a sparse matrix (either COO or CSR format) at specified indices.

There are two modes of operation:

1. Single update mode: where input_idx, output_idx, and value are provided as individual arguments. In this case all combinations of input_idx and output_idx are updated.

2. Batch update mode: where updates_df is provided, a DataFrame with columns [‘input_idx’, ‘output_idx’, ‘value’].

Parameters:

• sparse_matrix (coo_matrix or csr_matrix) – The sparse matrix to modify.

• input_idx (int, list, numpy.ndarray, set, optional) – Row indices for updates.

• output_idx (int, list, numpy.ndarray, set, optional) – Column indices for updates.

• value (numeric, list, numpy.ndarray, optional) – New values for updates. If it is a number, then it is used for all updates. Else, it needs to be of length equal to the product of the lengths of input_idx and output_idx.

• updates_df (DataFrame, optional) – The DataFrame containing batch updates.

• re_normalize (bool, optional) – Whether to re-normalize the matrix after updating, such that all values in each column sum up to 1. Default to True.

Note

In single update mode, input_idx, output_idx, and value must all be provided. In batch update mode, only updates_df should be provided. If both modes are provided, the function will prioritize the single update mode.

Returns:

The updated sparse matrix, in the same format as the input.

Return type:

coo_matrix or csr_matrix

connectome_interpreter.utils.output_grid_data(grid_outputs: Tensor | ndarray[tuple[int, ...], dtype[_ScalarType_co]], grid_coords: List[Tuple[float, float]], selected_index: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]]

Extract the output grid data for selected indices.

Parameters:

• grid_outputs (torch.Tensor|np.ndarray) – The output grid tensor of shape (grid_size**2, num_neurons, num_layers).

• grid_coords (list) – A list of grid coordinates. Best from function make_grid_inputs().

• selected_index (arrayable) – The index or indices to extract.

Returns:

A list of length num_layers of mean values with shape (grid_size, grid_size) for the selected indices.

Return type:

list

connectome_interpreter.utils.plot_layered_paths(paths: DataFrame, figsize: tuple = (10, 8), priority_indices=None, sort_dict: dict | None = None, sort_by_activation: bool = False, fraction: float = 0.03, pad: float = 0.02, weight_decimals: int = 2, neuron_to_sign: dict | None = None, sign_color_map: dict = {-1: 'blue', 1: 'red'}, neuron_to_color: dict | None = None, node_activation_min: float | None = None, node_activation_max: float | None = None, edge_text: bool = True, edge_text_size: int = 10, node_text: bool = True, highlight_nodes: list[str] = [], interactive: bool = False, save_plot: bool = False, file_name: str = 'layered_paths', label_pos: float = 0.7, default_neuron_color: str = 'lightblue', default_edge_color: str = 'lightgrey', node_size: int = 500)

Plots a directed graph of layered paths with optional node coloring based on activation values.

This function creates a visualization of a directed graph with nodes placed in layers. Nodes can be optionally colored based on ‘pre_activation’ and ‘post_activation’ columns present in the dataframe. If these columns are missing, a default color is used for all nodes. The edges are weighted, and their labels represent the weight values.

Parameters:

• paths (pandas.DataFrame) – A dataframe containing the columns ‘pre’, ‘post’, ‘layer’, ‘weight’, and optionally ‘pre_activation’, ‘post_activation’, ‘pre_layer’, ‘post_layer’. Each row represents an edge in the graph. The ‘pre’ and ‘post’ columns refer to the source and target nodes, respectively. The ‘layer’ column is used to place nodes in layers, and ‘weight’ indicates the edge weight. If present, ‘pre_activation’ and ‘post_activation’ are used to color the nodes based on their activation values.

• figsize (tuple, optional) – A tuple indicating the size of the matplotlib figure. Defaults to (10, 8).

• priority_indices (list, optional) – A list of indices to prioritize when creating the layered positions. Nodes with these indices will be placed at the top of their respective layers. Defaults to None.

• sort_dict (dict, optional) – A dictionary mapping node names to their priority values (bigger values are higher in the plot). Nodes will be sorted based on these values before plotting. Defaults to None.

• sort_by_activation (bool, optional) – A flag to sort the nodes based on their activation values (after grouping by priority). Defaults to False.

• fraction (float, optional) – The fraction of the figure width to use for the colorbar. Defaults to 0.03.

• pad (float, optional) – The padding between the colorbar and the plot. Defaults to 0.02.

• weight_decimals (int, optional) – The number of decimal places to display for edge weights. Defaults to 2.

• neuron_to_sign (dict, optional) – A dictionary mapping neuron names (as they appear in path_df) to their signs (e.g. {‘KCg-m’: 1, ‘Delta7’: -1}). Can also use a dictionary to map neuron names to their neurotransmitter name. Defaults to None.

• sign_color_map (dict, optional) – A dictionary used to color edges. Defaults is lightgrey but if neuron_to_sign is provided, the default is to color edges red if the pre-neuron is excitatory, and blue if inhibitory. If the neuron_to_sign values are neurotransmitter names, then provide a dictionary that maps neurotransmitter names to colors. If the keys of sign_color_map do not match the values of neuron_to_sign, a warning is printed and the default color is used for the difference.

• neuron_to_color (dict, optional) – A dictionary mapping neuron names to colors. If not provided, a default color is used for all nodes. The keys should match the node names (‘pre’ and ‘post’) in paths. The difference is given the default color.

• node_activation_min (float, optional) – The minimum value for node activation. If not provided, the minimum value of node activations is used. Defaults to None.

• node_activation_max (float, optional) – The maximum value for node activation. If not provided, the maximum value of node activations is used. Defaults to None.

• edge_text (bool, optional) – Whether to display edge weights as text on the plot. Defaults to True.

• edge_text_size (int, optional) – The font size for edge weight text. Defaults to 10.

• node_text (bool, optional) – Whether to display node names as text on the plot. Defaults to True.

• highlight_nodes (list[str], optional) – A list of node names to highlight bold in the plot. Defaults to an empty list.

• interactive (bool, optional) – Whether to create an interactive plot using pyvis. Defaults to False. If False, a static matplotlib plot is created.

• save_plot (bool, optional) – Whether to save the plot to a file. Defaults to False.

• file_name (str, optional) – The name of the file to save the plot. Defaults to “layered_paths” in the local directory (.html if interactive and .pdf if static).

• label_pos (float, optional) – The position of the edge labels. Defaults to 0.7. Bigger values move the labels closer to the left of the edge. Only works if interactive is False.

• default_neuron_color (str, optional) – The default color for nodes if no specific color is provided in neuron_to_color. Defaults to “lightblue”.

• default_edge_color (str, optional) – The default color for edges if no specific color is provided. Defaults to “lightgrey”.

• node_size (int, optional) – The size of the nodes in the plot. Defaults to 500.

Returns:

This function does not return a value. It generates a plot using matplotlib or pyvis.

Return type:

None

Note

If ‘pre_layer’ and ‘post_layer’ columns are not in the dataframe, they will be

created within the function to uniquely identify the nodes based on their ‘pre’/’post’ values and ‘layer’.

The function automatically checks for the presence of ‘pre_activation’ and

‘post_activation’ columns to determine whether to color the nodes based on activation values.

The positions of the nodes are determined by a custom positioning function

(create_layered_positions).

This function requires the networkx library for graph operations and matplotlib

for plotting. For interactive plots, it requires the pyvis library (where the node label has to be underneath the node).

connectome_interpreter.utils.plot_output_grid(grid_outputs: Tensor | ndarray[tuple[int, ...], dtype[_ScalarType_co]], grid_coords: List[Tuple[float, float]], selected_index: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], *, figsize: tuple = (10, 8), cmap: str = 'viridis', xlab: str = 'v1 Activation', ylab: str = 'v2 Activation', title: str | None = None, show_values: bool = False, fmt: str = '.2f')

Plot the output grid for selected indices.

Parameters:

• grid_outputs (torch.Tensor|np.ndarray) – The output grid tensor of shape (grid_size**2, num_neurons, num_layers).

• grid_coords (list) – A list of grid coordinates. Best from function make_grid_inputs().

• selected_index (int|list) – The index or indices to plot.

• figsize (tuple, optional) – The size of the figure. Defaults to (10, 8).

• cmap (str, optional) – The colormap to use. Defaults to ‘viridis’.

• xlab (str, optional) – The x-axis label. Defaults to ‘v1 Activation’.

• ylab (str, optional) – The y-axis label. Defaults to ‘v2 Activation’.

• title (str, optional) – The title of the plot. Defaults to None.

• show_values (bool, optional) – Whether to display the values on the heatmap. Defaults to False.

• fmt (str, optional) – The format of the values. Defaults to ‘.2f’.

Returns:

This function displays the plot.

Return type:

None

connectome_interpreter.utils.plot_paths(paths: DataFrame, figsize: tuple = (10, 8), priority_indices: Sequence[str] | None = None, sort_dict: dict | None = None, sort_by_activation: bool = False, sort_by_weight: bool = False, weight_decimals: int = 2, neuron_to_sign: dict | None = None, sign_color_map: dict = {-1: 'blue', 1: 'red'}, neuron_to_color: dict | None = None, node_activation_min: float | None = None, node_activation_max: float | None = None, edge_text: bool = True, edge_text_size: int = 10, node_text: bool = True, highlight_nodes: list[str] = [], show: bool = True, interactive: bool = False, save_plot: bool = False, file_name: str = 'paths', label_pos: float = 0.7, default_neuron_color: str = 'lightblue', default_edge_color: str = 'lightgrey', node_size: int = 500, node_text_size: int = 12, untangle_passes: int = 20, pre_pad: float = 0.2, post_pad: float = 0.2, seed: int | None = None, edge_width_scale: float = 15) → None

Plotting function for both layered (where layers are discrete, in layer column of paths), and flow paths (where layers can be continuous, in pre_layer and post_layer columns in paths).

The priority of nodes works as follows: without priority_indices, sort_dict or sort_by_activation, the nodes are ordered to minimize edge crossings. Otherwise, sort_dict > priority_indices > sort_by_activation for ordering nodes.

Parameters:

• paths (pd.DataFrame) – DataFrame containing the paths to plot. It could be the output of e.g. find_paths_of_length(), layered_el(), or find_paths_iteratively().

• figsize (tuple, optional) – Size of the figure. Defaults to (10, 8).

• priority_indices (list, optional) – List of neuron identifiers to put on top in the layout. This is treated the same as sort_dict with value 1. Defaults to None.

• sort_dict (dict, optional) – Dictionary mapping neuron identifiers to values for sorting. If provided, neurons will be sorted by these values. Bigger values are on top. Defaults to None.

• sort_by_activation (bool, optional) – If True, sort neurons by their activation values (if available in the DataFrame). Defaults to False.

• weight_decimals (int, optional) – Number of decimal places to display for weights. Defaults to 2.

• neuron_to_sign (dict, optional) – Dictionary mapping neuron identifiers to their sign (keys in the sign_color_map). If provided, edges will be colored based on the sign. Defaults to None.

• sign_color_map (dict, optional) – Dictionary mapping sign values to colors. Defaults to {1: “red”, -1: “blue”}.

• neuron_to_color (dict, optional) – Dictionary mapping neuron identifiers to colors. If None, a default color will be used for all neurons. Defaults to None.

• node_activation_min (float, optional) – Minimum activation value for node coloring. If None, the minimum activation value from the DataFrame will be used. Defaults to None.

• node_activation_max (float, optional) – Maximum activation value for node coloring. If None, the maximum activation value from the DataFrame will be used. Defaults to None.

• edge_text (bool, optional) – If True, display edge weights as text on the plot. Defaults to True.

• edge_text_size (int, optional) – Font size for edge text. Defaults to 10.

• node_text (bool, optional) – If True, display neuron identifiers as text on the plot. Defaults to True.

• highlight_nodes (list, optional) – List of neuron identifiers to highlight in the plot. Defaults to an empty list.

• show (bool, optional) – If True, display the plot (when interactive is False). If False, the function returns the figure and axis objects. Defaults to True.

• interactive (bool, optional) – If True, create an interactive plot using Pyvis. Defaults to False.

• save_plot (bool, optional) – If True, save the plot to a file. Defaults to False.

• file_name (str, optional) – Name of the file to save the plot if save_plot is True. Defaults to “paths”.

• label_pos (float, optional) – Position of the weight labels on the edges. Defaults to 0.7.

• default_neuron_color (str, optional) – Default color for neurons if not specified in neuron_to_color. Defaults to “lightblue”.

• default_edge_color (str, optional) – Default color for edges if not specified in neuron_to_sign. Defaults to “lightgrey”.

• node_size (int, optional) – Size of the nodes in the plot. Defaults to 500.

• untangle_passes (int, optional) – Number of passes for using positions of connected neurons to determine neuron position. Defaults to 20.

• pre_pad (float, optional) – Padding to add to the left side of the plot. Defaults to 0.2.

• post_pad (float, optional) – Padding to add to the right side of the plot. Defaults to 0.2.

• seed (int, optional) – Random seed for reproducibility. Defaults to None.

• edge_width_scale (float, optional) – Scale factor for edge widths. Defaults to 15.

Returns:

Only returned when show=False and interactive=False. Otherwise, the plot is either shown directly or displayed in an interactive window.

Return type:

fig, ax

connectome_interpreter.utils.pytorch_sparse_to_scipy(sparse_tensor, scipy_format='csr')

Convert a PyTorch sparse tensor to a SciPy sparse matrix.

Parameters:

• sparse_tensor (torch.sparse.Tensor) – PyTorch sparse tensor in COO format

• scipy_format (str) – Desired format for the SciPy sparse matrix. Must be one of ‘csr’, ‘csc’, ‘coo’.

Returns:

SciPy CSR sparse matrix

Return type:

scipy.sparse.csr_matrix

connectome_interpreter.utils.sc_connectivity_summary(df, inidx_map=None, outidx_map=None)

Single cell connectivity summary. For each group based on inidx_map, select the neuron with the strongest input to each postsynaptic group, and give value by the total weight from that presynaptic group for each average post-synaptic neuron. The output could be fed into get_ngl_link(). The idea of this function came from Dr Alexandra Fragniere.

Parameters:

• df (pd.DataFrame) – A DataFrame with pre in the row indices, post in the column names, and weights as values.

• inidx_map (dict, optional) – A mapping from the presynaptic indices to group identifiers. If None, the presynaptic indices themselves are used as group identifiers. Defaults to None.

• outidx_map (dict, optional) – A mapping from the postsynaptic indices to group identifiers. If None, the postsynaptic indices are used as group identifiers. Defaults to None.

Returns:

A DataFrame, with values in outidx_map as column names. Row indices are a subset of the original row indices: the top input in each group. The values in the dataframe are the sum of the weights from each inidx_map group to an average member of the outidx_map group.

Return type:

pd.DataFrame

connectome_interpreter.utils.scipy_sparse_to_pytorch(scipy_sparse, device: device = device(type='cpu'))

Convert a SciPy sparse matrix to a PyTorch sparse tensor.

Parameters:

• scipy_sparse (scipy.sparse.spmatrix) – SciPy sparse matrix

• device (torch.device) – Device to create the PyTorch sparse tensor on. Defaults to GPU if available, otherwise CPU.

Returns:

PyTorch sparse tensor

Return type:

torch.sparse.Tensor

connectome_interpreter.utils.tensor_to_csc(tensor)

Turn torch.Tensor into scipy Compressed Sparse Column matrix.

Parameters:

tensor (torch.Tensor) – A (sparse) tensor.

Returns:

A Scipy sparse Compressed Sparse Column matrix.

Return type:

scipy.sparse.csc_matrix

connectome_interpreter.utils.to_nparray(input_data: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], unique: bool = True) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Converts the input data into a numpy array, filtering out any NaN values (and duplicates). The input can be a single number, a list, a set, a numpy array, or a pandas Series.

Parameters:

• input_data – The input data to convert. Can be of type int (including numpy.int64 and numpy.int32), float, list, set, numpy.ndarray, pandas.Series, or pandas.Index.

• unique (bool, optional) – Whether to return only unique values. Default to True. NOTE: np.unique() sorts the array.

Returns:

A unique numpy array created from the input data, with all NaN values removed.

Return type:

numpy.ndarray

connectome_interpreter.utils.torch_sparse_where(x, threshold)

Apply a threshold to a tensor, setting values below the threshold to zero. This function allows the tensor to be sparse. torch.where() does not.

Parameters:

• x (torch.Tensor) – The input tensor to apply the threshold to.

• threshold (float) – The threshold value.

Returns:

A new tensor with values below the threshold set to zero.

Return type:

torch.Tensor