Plotting

The plotting module sets up the plots, the legend and all the buttons and widgets to interact with the data.

More precisely, it is responsible for:

• Creating the main Bokeh figure and rendering the 2D or 3D data embedding from an AnnData object.

• Implementing the complex client-side JavaScript callbacks that enable real-time 3D rotation (yaw, pitch, roll) and depth perception.

• Setting up standard Bokeh tools like HoverTool, LassoSelectTool, and sliders for user interaction.

• Coloring data points on the main scatter plot based on the values of one or more user-selected features.

• Generating violin plots and heatmaps, to visualize the distribution of feature values across different user-defined subsets or existing categorical labels.

• Managing the data sources and handling updates based on user interactions.

color_by_feature_value(points_bokeh_plot, violins_bokeh_plot, heat_map, adata, select_color_by, hidden_text_label_column, resize_width_input, hidden_legend_width, hidden_checkbox_A, hidden_checkbox_B, resize_w_input, resize_h_input, bt_slider_range, select_field)

Set up widgets and callbacks for coloring points by feature value. Update the plot coloring and refresh violin and heatmap plots based on user’s selected features and groups.

Parameters:

• points_bokeh_plot (bokeh.plotting.figure) – The main Scatter plot figure.

• violins_bokeh_plot (bokeh.plotting.figure) – Violion plot figure.

• heat_map (bokeh.plotting.figure) – heat map figure.

• adata (anndata.AnnData) – Annotated data matrix of shape n_obs x n_vars.

• select_color_by (bokeh.models.Select) – Dropdown menu for choosing a coloring field, its values will be added in the legend.

• hidden_text_label_column (bokeh.models.TextInput) – Hidden widget used internally to store selected label columns.

• resize_width_input (bokeh.models.TextInput) – Input to set scatter plot’s width.

• hidden_legend_width (bokeh.models.TextInput) – Hidden widget storing computed legend width.

• hidden_checkbox_A (bokeh.models.CheckboxGroup) – Widget storing “Subset A” sample indices.

• hidden_checkbox_B (bokeh.models.CheckboxGroup) – Widget storing “Subset B” sample indices.

• resize_w_input (bokeh.models.TextInput) – Button to set bottom’s figure (violin plot or heat map) width.

• resize_h_input (bokeh.models.TextInput) – Button to set bottom’s figure (violin plot or heat map) height.

• bt_slider_range (bokeh.models.RangeSlider) – Slider for filtering samples based on a selected feature’s value.

• select_field (bokeh.models.Select) – Dropdown menu in the legend for selecting a group from a field with many unique values.

Returns:

Tuple containing the Bokeh widgets created by this function

• offset_text_feature_color (bokeh.models.TextInput): Text input for entering feature names to color samples in the scatter plot.

• offset_label (bokeh.models.TextInput): A hidden text input that stores the group labels for generating violin/heatmap plots.

plot_var(adata, violins_bokeh_plot, heat_map, resize_w, resize_h, hidden_checkbox_A, hidden_checkbox_B, features, selected_labels=None)

Create or update violin plots and heatmaps showing feature(s) distributions for subsets of observations (e.g., subsets A, B, rest, or user-defined groups).

Parameters:

• adata (anndata.AnnData) – Annotated data matrix of shape n_obs x n_vars.

• violins_bokeh_plot (bokeh.plotting.figure) – Violin plot figure.

• heat_map (bokeh.plotting.figure) – Heatmap figure.

• resize_w (bokeh.models.TextInput) – Widget for resizing plot width.

• resize_h (bokeh.models.TextInput) – Widget for resizing plot height.

• hidden_checkbox_A (bokeh.models.CheckboxGroup) – Hidden widget storing Subset A samples indices.

• hidden_checkbox_B (bokeh.models.CheckboxGroup) – Hidden widget storing Subset B samples indices.

• features (list of str) – List of selected feature names (from adata.var_names) to plot.

• selected_labels (list of str, optional) – Labels for grouping observations. Groups can include subsets (“Subset A”, “Subset B”, “Rest”) or metadata categories. Defaults to None.

Returns:

None

check_obs_field(udict, field)

Check if a categorical field has a manageable number of unique values.

Parameters:

• udict (dict) – Dictionary mapping .obs keys to their number of unique values.

• field (str) – Field to check, should be a key of udict.

Returns:

True if the number of unique values is less than or equal to MAX_UNIQUE_VALUES, False otherwise.

main_figure(adata, embedding_key, width=900, height=600, title='')

Create the main interactive figure and all associated widgets.

Parameters:

• adata (anndata.AnnData) – Annotated data matrix of shape n_obs x n_vars.

• embedding_key (str) – The string key from adata.obsm specifying which embedding to plot.

• width (int) – Width of the main figure in pixels.

• height (int) – Height of the main figure in pixels.

• title (str) – Title for the main figure.

Returns:

Tuple containing all the created Bokeh components

• original_keys (list): List of all keys from adata.obs.

• unique_dict (dict): Maps categorical keys from adata.obs to unique values .

• obs_string (list): List of categorical keys with <= 40 unique values from adata.obs.

• obs_string_many (list): Categorical keys with > 40 unique values from adata.obs.

• obs_numerical (list): List of numerical observation fields from adata.obs.

• points_bokeh_plot (bokeh.plotting.figure): The main scatter plot figure.

• violins_bokeh_plot (bokeh.plotting.figure): Violin plot figure.

• heat_map (bokeh.plotting.figure): Heat map figure.

• bt_slider_point_size (bokeh.models.Slider): Widget for point size.

• bt_hidden_slider_yaw (bokeh.models.Slider): Hidden slider for animation.

• bt_slider_range (bokeh.models.RangeSlider): Slider for filtering samples based on a selected feature’s value.

• bt_toggle_anim (bokeh.models.Toggle): Toggles rotation animation.

• bt_slider_yaw (bokeh.models.Slider): Slider button that controls yaw rotation.

• bt_slider_pitch (bokeh.models.Slider): Slider button that controls pitch rotation.

• bt_slider_roll (bokeh.models.Slider): Slider button that controls roll rotation.

• resize_width_input (bokeh.models.TextInput): Input for setting main plot’s width.

• resize_height_input (bokeh.models.TextInput): Input for setting main plot’s height.

• resize_width_input_bis (bokeh.models.TextInput): Input for setting violin/heatmap plot’s width.

• resize_height_input_bis (bokeh.models.TextInput): Input for setting violin/heatmap plot’s height.

• source_rotmatrix_etc (bokeh.models.ColumnDataSource): Data source for computing points’ positions after rotations in the scatterplot.

• div_sample_names (bokeh.models.Div): Displays hovered sample names.

• sample_search_input (bokeh.models.TextInput): Text input to search specific sample via its ID.

• sl_component1 (bokeh.models.RadioButtonGroup, None if embedding <= 3 dimensions): Button to select which dimension should be used for the x-axis.

• sl_component2 (bokeh.models.RadioButtonGroup, None if embedding <= 3 dimensions): Button to select which dimension should be used for the y-axis.

• sl_component3 (bokeh.models.RadioButtonGroup, None if embedding <= 3 dimensions): Button to select which dimension should be used for the z-axis.

setup_legend(pb_plot, obs_string, obs_string_many, obs_numerical, source_rotmatrix_etc, resize_width_input, bt_slider_range, unique_dict)

Set up interactive legend and color mapping for a scatter plot. Creates Bokeh widgets and callbacks that control coloring of points by categorical or numerical observation fields, and dynamically builds legends or color bars depending on the field type.

Parameters:

• pb_plot – The main scatter plot figure.

• obs_string – List of categorical .obs keys with <= 40 unique values.

• obs_string_many – List of categorical .obs keys with > 40 unique values.

• obs_numerical – List of numerical observation fields.

• source_rotmatrix_etc – bokeh.models.ColumnDataSource Data source for computing points’ positions after rotations in the scatterplot.

• resize_width_input – bokeh.models.TextInput Input for setting main plot’s width.

• bt_slider_range – bokeh.models.RangeSlider Slider for filtering samples based on a selected feature’s value.

• unique_dict – dict Dictionary mapping field names to lists of unique values.

Returns:

Tuple containing all the created Bokeh components

• select_color_by (bokeh.models.Select): Dropdown menu for choosing a coloring field, its values will be added in the legend.

• help_button (bokeh.models.HelpButton): A help tooltip for the select widget.

• hidden_text_label_column (bokeh.models.TextInput): A hidden widget that triggers the color update via JavaScript.

• hidden_legend_width (bokeh.models.TextInput): A hidden widget that stores the current width of the legend.

• select_field (bokeh.models.Select): Dropdown menu in the legend for selecting a group from a field with many unique values.

• label_signature (bokeh.models.MultiSelect): Widget for selecting groups in violin plots / heat map (initialized here).