Map to external data

connectome_interpreter.external_map.hex_heatmap(df: Series | DataFrame, style: dict | None = None, sizing: dict | None = None, dpi: int = 72, custom_colorscale: list | str | None = None, global_min: float | None = None, global_max: float | None = None, dataset: str | None = 'mcns_right', value_name: str = 'weight', colorbar: bool = True, title: str | None = None) → Figure[source]

Generate a hexagonal heat map plot of the data. The index of the data should be formatted as strings of the form ‘-12,34’, where the first number is the x-coordinate and the second number is the y-coordinate.

Parameters:

  • df (pd.Series | pd.DataFrame) – The data to plot. If a Series, it will be plotted as a single trace. If a DataFrame, each column will generate a separate frame in the plot.

  • style (Optional[dict]) –

    Dict containing styling formatting variables. Possible keys are:

    • ’font_type’: str, default=’arial’

    • ’linecolor’: str, default=’black’

    • ’papercolor’: str, default=’rgba(255,255,255,255)’ (white)

  • sizing (Optional[dict]) –

    Dict containing size formatting variables. Possible keys are:

    • ’fig_width’: int, default=260 (mm)

    • ’fig_height’: int, default=220 (mm)

    • ’fig_margin’: int, default=0 (mm)

    • ’fsize_ticks_pt’: int, default=20 (points)

    • ’fsize_title_pt’: int, default=20 (points) - colorbar title font size

    • ’fsize_plot_title_pt’: int, default=24 (points) - plot title font size

    • ’title_margin’: int, default=50 (pixels) - top margin when title is present

    • ’markersize’: int, default=18 if dataset=’mcns_right’, 20 if dataset=’fafb_right’

    • ’ticklen’: int, default=15

    • ’tickwidth’: int, default=5

    • ’axislinewidth’: int, default=3

    • ’markerlinewidth’: int, default=0.9

    • ’cbar_thickness’: int, default=20

    • ’cbar_len’: float, default=0.75

  • dpi (int) – Dots per inch for the output figure. Standard is 72 for screen/SVG/PDF. Use higher values (e.g., 300) for print-quality output.

  • custom_colorscale (Optional[Union[list, str]]) – Custom colorscale for the heatmap. If None, defaults to white-to-blue colorscale [[0, “rgb(255, 255, 255)”], [1, “rgb(0, 20, 200)”]].

  • global_min (Optional[float]) – Global minimum value for the color scale. If None, the minimum value of the data is used but if that is negative, use 0.

  • global_max (Optional[float]) – Global maximum value for the color scale. If None, the maximum value of the data is used.

  • dataset (str) –

    Default=’mcns_right’. The dataset to use for the hexagon locations. Options are:

    • ’mcns_right’: columnar coordinates of individual cells from columnar cell types: L1, L2, L3, L5, Mi1, Mi4, Mi9, C2, C3, Tm1, Tm2, Tm4, Tm9, Tm20, T1, within the medulla of the right optic lobe, from Nern et al. 2024.

    • ’fafb_right’: columnar coordinates of individual cells from columnar cell types, in the right optic lobe of FAFB, from Matsliah et al. 2024.

  • title (Optional[str]) – Title for the plot. If None, no title is displayed.

Returns:

go.Figure

Return type:

fig

connectome_interpreter.external_map.load_dataset(dataset: str) → DataFrame[source]

Load the dataset from the package data folder. These datasets have been preprocessed to work with connectomics data. The preprocessing scripts are in this repository: https://github.com/YijieYin/interpret_connectome.

Parameters:

dataset –

(str) The name of the dataset to load. Options are:

  • ’DoOR_adult’: mapping from glomeruli to chemicals, from Munch and Galizia DoOR dataset (https://www.nature.com/articles/srep21841), a composite of multiple studies and their own data. When it’s their own data (not specified), odour concentration is 10^-2. Ca imaging.

  • ’DoOR_adult_sfr_subtracted’: mapping from glomeruli to chemicals, with spontaneous firing rate subtracted. There are therefore negative values.

  • ’Dweck_adult_chem’: mapping from glomeruli to chemicals extracted from fruits, from Dweck et al. 2018 (https://www.cell.com/cell-reports/abstract/S2211-1247(18)30663-6). Normalised maximum frequency (Hz) responses to 10^-4 concentration of synthetic standards of the active compounds. Firing rates normalised to between 0 and 1. Electrophysiology data.

  • ’Dweck_adult_fruit’: number of compounds in a fruit that activated a glomerulus, from Dweck et al. 2018. Not normalised because compound count is not response magnitude.

  • ’Dweck_larva_chem’: mapping from olfactory receptors to chemicals, from Dweck et al. 2018. Normalised maximum frequency (Hz) responses to 10^-4 concentration of synthetic standards of the active compounds. Firing rates normalised to between 0 and 1.

  • ’Dweck_larva_fruit’: number of compounds in a fruit that activated a receptor, from Dweck et al. 2018. Not normalised because compound count is not response magnitude.

  • ’Nern2024’: columnar coordinates of individual cells from a collection of columnar cell types within the medulla of the right optic lobe, from Nern et al. 2024 (https://www.biorxiv.org/content/10.1101/2024.04.16.589741v2).

  • ’Matsliah2024’: columnar coordinates of individual cells from a collection of columnar cell types in the right optic lobe from FAFB, from Matsliah et al. 2024 (https://www.nature.com/articles/s41586-024-07981-1).

  • ’Badel2016_PN’: mapping from olfactory projection neurons to odours, from Badel et al. 2016 (https://www.cell.com/neuron/fulltext/S0896-6273(16)30201-X). Odour dilution is 10^-2 unless otherwise specified. Ca imaging.

  • ’Zhao2024’: mapping from hexagonal coordinates to 3D coordinates, update from Zhao et al. 2022 (https://www.biorxiv.org/content/10.1101/2022.12.14.520178v1).

  • ’Hallem2006’: mapping from glomeruli to chemicals, from Hallem and Carlson 2006 (https://www.cell.com/cell/abstract/S0092-8674(06)00363-1). Odour dilution is 10^-2 unless otherwise specified. Electrophysiology data.

  • ’Hallem2006_dilution’: mapping from glomeruli to chemicals across dilution rates, from Hallem and Carlson 2006.

  • ’Hallem2006_time’: response of glomeruli to odours, across timepoints, from Hallem and Carlson 2006.

  • ’Knaden2012_odour_valence’: behavioural valence of odours, from Knaden et al. 2012 (https://www.sciencedirect.com/science/article/pii/S2211124712000733).

Returns:

The dataset as a pandas DataFrame. For the adult, the glomeruli are in the rows. For the larva, receptors are in the rows.

Return type:

pd.DataFrame

connectome_interpreter.external_map.looming_stimulus(start_coords, all_coords, n_time=4)[source]

Generate a list of lists of coordinates for a looming stimulus. The stimulus starts at the start_coords and expands outwards in a hexagonal pattern. The stimulus expands for n_time steps. Currently the expansion happens one layer at a time.

Parameters:

  • start_coords (list) – List of strings of the form ‘x,y’ where x and y are the coordinates of the starting hexes for the stimulus.

  • all_coords (list) – List of strings of the form ‘x,y’ where x and y are the coordinates of all hexes in the grid.

  • n_time (int) – Default=4. Number of time steps for the stimulus to expand.

Returns:

List of lists of strings of the form ‘x,y’ where x and y are the coordinates of the hexes that are stimulated at each time step.

Return type:

stim_str (list)

connectome_interpreter.external_map.make_sine_stim(phase=0, amplitude=1, n=8)[source]

Generate a dictionary of values representing a sine wave stimulus with a given phase and amplitude. The sine wave is defined over n points, starting from the given phase.

Parameters:

  • phase (int) – Phase of the sine wave in degrees. Default is 0.

  • amplitude (float) – Amplitude of the sine wave. Default is 1.

  • n (int) – Number of points in the sine wave. Default is 8.

Returns:

A dictionary where keys are indices from 1 to n, and values are the corresponding sine wave values.

Return type:

dict

connectome_interpreter.external_map.map_to_experiment(df, dataset=None, custom_experiment=None)[source]

Map the connectomics data to experimental data. For example, if odour1 excites neuron1 0.5, and neuron2 0.6; both neuron1 and neuron2 output to neuron3 (0.7 and 0.8 respectively), then the output of neuron3 to odour1 is 0.5*0.7 + 0.6*0.8 = 0.83. The result would only be 1 if a stimulus excites neurons 100%, and those neurons constitue 100% of the downstream neuron’s input.

Parameters:

  • df (pd.DataFrame) – The connectivity data. Standardised input (e.g. glomeruli, receptors) in rows, observations (target neurons) in columns.

  • dataset (str) –

    The name of the dataset to load. Options are:

    • ’DoOR_adult’: mapping from glomeruli to chemicals, from Munch and Galizia DoOR dataset (https://www.nature.com/articles/srep21841), a composite of multiple studies and their own data. When it’s their own data (not specified), odour concentration is 10^-2. Ca imaging.

    • ’DoOR_adult_sfr_subtracted’: mapping from glomeruli to chemicals, with spontaneous firing rate subtracted. There are therefore negative values.

    • ’Dweck_adult_chem’: mapping from glomeruli to chemicals extracted from fruits, from Dweck et al. 2018 (https://www.cell.com/cell-reports/abstract/S2211-1247(18)30663-6). Normalised maximum frequency (Hz) responses to 10^-4 concentration of synthetic standards of the active compounds. Firing rates normalised to between 0 and 1. Electrophysiology data.

    • ’Dweck_adult_fruit’: number of compounds in a fruit that activated a glomerulus, from Dweck et al. 2018. Not normalised because compound count is not response magnitude.

    • ’Dweck_larva_chem’: mapping from olfactory receptors to chemicals, from Dweck et al. 2018. Normalised maximum frequency (Hz) responses to 10^-4 concentration of synthetic standards of the active compounds. Firing rates normalised to between 0 and 1.

    • ’Dweck_larva_fruit’: number of compounds in a fruit that activated a receptor, from Dweck et al. 2018. Not normalised because compound count is not response magnitude.

    • ’Nern2024’: columnar coordinates of individual cells from a collection of columnar cell types within the medulla of the right optic lobe, from Nern et al. 2024.

    • ’Badel2016_PN’: mapping from olfactory projection neurons to odours, from Badel et al. 2016 (https://www.cell.com/neuron/fulltext/S0896-6273(16)30201-X). Odour dilution is 10^-2 unless otherwise specified. Ca imaging.

    • ’Hallem2006’: mapping from glomeruli to chemicals, from Hallem and Carlson 2006 (https://www.cell.com/cell/abstract/S0092-8674(06)00363-1). Odour dilution is 10^-2 unless otherwise specified. Electrophysiology data.

    • ’Hallem2006_dilution’: mapping from glomeruli to chemicals across dilution rates, from Hallem and Carlson 2006.

  • custom_experiment (pd.DataFrame) – A custom experimental dataset to compare the connectomics data to. The row indices of this dataframe must match the row indices of df. They are the units of comparison (e.g. glomeruli).

Returns:

The similarity between the connectomics data and the experimental data. Rows are neurons, columns are external stimulus.

Return type:

pd.DataFrame

connectome_interpreter.external_map.plot_mollweide_projection(data: Series | DataFrame, fig_size: tuple = (900, 700), custom_colorscale: list | str | None = None, global_min: float | None = None, global_max: float | None = None, dataset: str = 'Zhao2024', marker_size: int = 8, value_name: str = 'weight', colorbar: bool = True) → Figure[source]

Generates a heatmap to visualize the value of column features per column using the mollweide projection.

Parameters:

  • data (pd.Series | pd.DataFrame) – Data with index formatted as strings of the form ‘-12,34’, where the first number is the x-coordinate and the second number is the y-coordinate. The data to plot. Each column will generate a separate frame in the plot.

  • fig_size (tuple) – Size of the figure in pixels (width, height).

  • custom_colorscale (list | str, optional) – Custom colorscale for the heatmap. If None, defaults to white-to-blue colorscale [[0, “rgb(255, 255, 255)”], [1, “rgb(0, 20, 200)”]]. Could also be a string e.g. ‘Viridis’ or ‘Reds’.

  • global_min (float | None) – Global minimum value for the color scale. If this minumum is >0, 0 is used.

  • global_max (float | None) – Global maximum value for the color scale. If None, the maximum value of the data is used.

  • dataset (str) –

    The dataset to use for the hexagon locations. Options are:

  • marker_size (int) – Size of markers in the plot.

Returns:

A Plotly figure object containing the mollweide projection heatmap.

Return type:

go.Figure