Tools

arrow_function(points_bokeh_plot, adata, embedding_key, bt_slider_roll, bt_slider_pitch, bt_slider_yaw, source_rotmatrix_etc, bt_toggle_anim, hidden_checkbox_A, div_signature_list, multiselect_signature, sign_nr, sl_component1, sl_component2, sl_component3, label_sign)

Create and manage the arrow tool for oriented signature analysis Add the “Arrow Tool” to the Bokeh scatter plot that lets the user draw an arrow (start and end points). The arrow direction is then used to compute an oriented signature: a set of features most correlated with the arrow direction in the embedding space.

Parameters:

• points_bokeh_plot (bokeh.plotting.figure) – Bokeh scatter plot of observations.

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

• embedding_key (str) – Key in adata.obsm storing the embedding coordinates.

• 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.

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

• bt_toggle_anim (bokeh.models.Toggle) – Toggle controlling animation state.

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

• div_signature_list (bokeh.models.Div) – Div displaying most correlated features from the computed signature.

• multiselect_signature (bokeh.models.MultiSelect) – MultiSelect widget listing most correlated features from the computed signature.

• sign_nr (list) – A list containing an single integer to count the number of signatures that were computed.

• sl_component1 (bokeh.models.RadioButtonGroup) – Button to select which dimension should be used for the x-axis.

• sl_component2 (bokeh.models.RadioButtonGroup) – Button to select which dimension should be used for the y-axis.

• sl_component3 (bokeh.models.RadioButtonGroup) – Button to select which dimension should be used for the z-axis.

• label_sign (bokeh.models.MultiSelect) – Widget for selecting groups in violin plots / heat map.

Returns:

Tuple containing the Bokeh widgets created by this function

• bt_sign_oriented (bokeh.models.Button): Button that triggers oriented signature computation based on the drawn arrow.

• help_button_oriented (bokeh.models.HelpButton): Tooltip button describing requirements for computing oriented signatures.

create_new_field_button(source, select_color_by, unique_dict, obs_string, trigger_legend_refresh)

Create a button that pops up a dialog to create a new labelling field.

The popup asks for a field name, then adds that field to the data source (initialised to "unlabeled" for all points), registers it with the legend system, and switches the “Color by” dropdown to it.

Parameters:

• source – bokeh.models.ColumnDataSource Data source to extend with the new field.

• select_color_by – bokeh.models.Select The “Color by” dropdown — will be switched to the new field.

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

• obs_string – list Mutable list of categorical obs field names — the new field is appended here so the legend system treats it as categorical.

• trigger_legend_refresh – callable Callable (field_name: str) -> None that rebuilds the legend for a given field.

Returns:

Tuple containing –

• hidden_relay (bokeh.models.TextInput): Invisible relay widget (must be in the document layout).

• button (bokeh.models.Button): “Create new field” button.

csv_load_button(source)

Create a button to load previously selected points from a CSV file.

Parameters:

source (bokeh.models.ColumnDataSource) – Data source with at least a "name" field, against which CSV entries will be matched.

Returns:

Load selection button (bokeh.models.Button) – On click, it prompts for a CSV file and updates source.selected.indices with the matched entries.

download_selected_button(source, original_keys)

Create a button to download selected points as a CSV file.

Parameters:

• source – bokeh.models.ColumnDataSource Data source containing the selected points to be downloaded.

• original_keys – list of str Column names to include in the downloaded CSV file.

Returns:

Save selection button (bokeh.models.Button) – On click, it downloads the currently selected points as a CSV file.

load_labels_button(source, select_color_by, unique_dict, obs_string, trigger_legend_refresh)

Create a button to load labels from a CSV file into the data source.

The CSV must have the format name\t<field_name> (tab-separated, first line is the header). If the named field does not yet exist it is created and initialised to "unlabeled" before the loaded values are applied.

The button opens a file picker in the browser. The selected file’s raw text is relayed to a hidden TextInput which triggers a server-side Python callback that updates the data source, recomputes colors, and rebuilds the legend — avoiding the race condition that arises when these steps are performed purely client-side.

Parameters:

• source – bokeh.models.ColumnDataSource Data source to update with loaded labels.

• select_color_by – bokeh.models.Select The “Color by” dropdown — will be switched to the loaded field.

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

• obs_string – list Mutable list of categorical obs field names — new fields are appended here so the legend handles them.

• trigger_legend_refresh – callable Callable (field_name: str) -> None that rebuilds the legend.

Returns:

Tuple containing –

• hidden_csv_input (bokeh.models.TextInput): Invisible relay widget (must be present in the document layout).

• button (bokeh.models.Button): “Load field” button.

relabel_selection_button(source, select_color_by, unique_dict, obs_string, trigger_legend_refresh)

Create a button that pops up a dialog to (re)label selected points within the currently active “Color by” field.

The popup asks for a label name and the target field, then applies the label server-side (replacing any previous assignment of that label name so the selection is always an exact replacement, not an addition). Colors and the legend are refreshed automatically.

Parameters:

• source – bokeh.models.ColumnDataSource Data source containing the data points.

• select_color_by – bokeh.models.Select The “Color by” dropdown — its current value determines which field is being labelled.

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

• obs_string – list Mutable list of categorical obs field names (user-created fields are appended here so the legend handles them).

• trigger_legend_refresh – callable Callable (field_name: str) -> None that clears the legend cache for field_name and rebuilds the legend widgets.

Returns:

Tuple containing –

• hidden_relay (bokeh.models.TextInput): Invisible relay widget (must be in the document layout).

• button (bokeh.models.Button): “Label selection” button.

save_labels_button(source, select_color_by)

Create a button to save the currently active field’s labels to a CSV file.

The saved CSV has the format name\t<field_name> so it can be reloaded by load_labels_button() into the correct field.

Parameters:

• source – bokeh.models.ColumnDataSource Data source containing the label fields.

• select_color_by – bokeh.models.Select The “Color by” dropdown — its current value names the field to save.

Returns:

Save field button (bokeh.models.Button) – On click, downloads all points with their labels as a TSV/CSV file.

gene_query_button(offset_text_feature_color)

Create a button to search for genes in the HGNC database.

This function generates a Bokeh Button when clicked, extracts the feature names from the feature input text box, and for each feature, opens a new browser tab to the corresponding search results page on the HGNC website. It may include + and - operators, as well as Ensembl IDs.

Parameters:

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

Returns:

btn_open_link (bokeh.models.Button) – Button that opens HGNC search pages for the features listed in offset_text_feature_color.

signature_buttons(adata, offset_text_feature_color, offset_label, hidden_checkbox_A, hidden_checkbox_B, label_signature)

Create the UI elements e.g., buttons, help tooltips, and a multi-select widget that allow users to compute differential feature signatures between interactively defined cell subsets. It provides options to compare “Subset A vs. Rest” and “Subset A vs. Subset B”.

Parameters:

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

• 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) – Hidden text input that stores the group labels for generating violin/heatmap plots

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

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

• label_signature – bokeh.models.MultiSelect Widget listing available group labels including Subset A and Subset B or Rest.

Returns:

Tuple containing the Bokeh components created by this function

• bt_sign1 (bokeh.models.Button): Button to compute “A vs. Rest”.

• bt_sign2 (bokeh.models.Button): Button to compute “A vs. B”.

• help_button1 (bokeh.models.HelpButton): Help tooltip for bt_sign1.

• help_button2 (bokeh.models.HelpButton): Help tooltip for bt_sign2.

• multiselect_signature (bokeh.models.MultiSelect): Widget to display the ranked features of the computed signature.

• div_signature_list (bokeh.models.Div): Div element to display the signature title and a summary of top features.

• signature_nr (list): List containing a single integer used to number the computed signatures sequentially.

subset_buttons(points_bokeh_plot, source_rotmatrix_etc, bt_slider_range)

Generate toggle switches and buttons for setting, highlighting, and selecting subsets of samples directly within from the scatterplot.

Parameters:

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

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

• bt_slider_range (bokeh.models.RangeSlider) – Slider for filtering samples based on a selected feature’s value. It is passed here so its value can be reset when the user clears a selection.

Returns:

Tuple containing all the created Bokeh widgets so they can be added

to the main application layout.

• bt_A (bokeh.models.Button): Button to assign the current selection to Subset A.

• toggle_A (bokeh.models.Toggle): Toggle to turn the visual highlighting of Subset A on or off.

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

• bt_B (bokeh.models.Button): Button to assign the current selection to Subset B.

• toggle_B (bokeh.models.Toggle): Toggle to turn the visual highlighting of Subset B on or off.

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

• bt_AplusB (bokeh.models.Button): Button to select the union of Subset A and Subset B.

• bt_nothing (bokeh.models.Button): Button to clear the current selection.

• bt_selectA (bokeh.models.Button): Button to select all samples from Subset A.

• bt_selectB (bokeh.models.Button): Button to select all samples from Subset B.