ibl_alignment_gui.app.controllers.app_controller

Classes

AlignmentGUIController

The main controller class for the alignment GUI application.

class ibl_alignment_gui.app.controllers.app_controller.AlignmentGUIController(offline=False, csv=None, yaml=None, pid=None, allen=False)

Bases: object

The main controller class for the alignment GUI application.

Parameters:

• offline (bool) – Whether to run in offline mode (local files) or online mode (ONE/Alyx)

• csv (Path or str or None) – Path to a CSV file containing local sessions on the filesystem.

• allen (bool) – Whether to run the Allen/Code Ocean (anatomical) workflow. Uses a yaml session with a ProbeHandlerAllenYaml model and adds a DocDB checkbox to toggle the DocDB backend.

Variables:

• csv (str or bool or None) – The CSV path used for session loading. Defaults to False if no CSV is provided.

• offline (bool) – Indicates whether the controller is in offline mode.

• view (AlignmentGUIView) – The GUI view for the alignment application.

• model (ProbeHandlerLocal or ProbeHandlerCSV or ProbeHandlerONE) – The data model used for session management and probe handling.

• loaded (bool) – Indicates whether session data has been loaded.

• extend_feature (int) – Parameter controlling feature extension when applying alignments.

• lin_fit (bool) – Whether to use a linear fit when applying alignments.

• show_lines (bool) – Whether to display reference lines in the GUI.

• show_labels (bool) – Whether to display labels in the GUI.

• show_channels (bool) – Whether to display channels in the GUI.

• hover_line (pg.InfiniteLine or None) – The currently hovered line item, if any.

• hover_shank (str or None) – The shank name of the currently hovered item, if any.

• hover_idx (int or None) – The shank index of the currently hovered item, if any.

• hover_config (str or None) – The configuration of the currently hovered item, if any.

• all_shanks (list) – A list of all shanks.

• shank_items (defaultdict of Bunch) – A dictionary containing the ShankController instances for each shank and configuration.

• slice_figs (Bunch) – A container for slice figures currently displayed.

• blockPlugins (bool) – Whether plugins are temporarily blocked from running.

• filter_init (img_init, probe_init, line_init, slice_init,) – Track the initially loaded image, probe, line, slice, and filter states, respectively.

• plugins (dict) – A mapping of plugin names to plugin instances.

add_points_to_display()

Add reference points to the fit plot for the selected shank.

Return type:

None

add_reference_lines_to_display(items, **kwargs)

Add previously created reference lines and scatter points to their respective plots.

Return type:

None

align_reference_lines(items, **kwargs)

See ShankController.align_reference_lines() for details.

Return type:

None

apply_fit(fit_function, **kwargs)

Apply a given fitting function to histology data and update all relevant plots.

Parameters:

• fit_function (Callable) – A function that modifies the alignment

• **kwargs – Additional arguments passed to fit_function.

Return type:

None

complete_button_pressed()

Triggered when complete button or Shift+U is pressed.

Saves channel locations and alignments. The per-shank user input (which shanks, QC assessment, upload confirmation) is gathered here on the main thread via modal dialogs; the slow saving itself then runs on a background thread (see _run_in_thread() and ProbeHandler.upload_shanks), with the results reported in _on_upload_finished().

Return type:

None

connect_cluster_plugin(items)

Connect the cluster feature plugin to the scatter plot.

Return type:

None

create_reference_line(pos, items)

Create a reference line and a corresponding scatter point.

It creates: - A track line in the histology figure - Feature lines in the image, line, and probe figures that are synchronized - A scatter point in the fit figure indicating the correspondence

Parameters:

pos (float) – Y-axis position at which to create the reference line.

Return type:

None

create_reference_lines(positions, items)

Create reference lines across at multiple positions.

Parameters:

positions (array-like of float) – List or array of y-axis positions at which to create reference lines.

Return type:

None

create_shanks()

Create ShankController instance for each shank and config combination.

Return type:

None

data_button_pressed()

Load in all the relevant data and instantiate the GUI display.

Triggered when the data button is pressed. The atlas build, data load and plot build run on a background thread (see _run_in_thread() and ProbeHandler.load_all) so the GUI stays responsive and a progress dialog can be shown. The display is assembled in _on_load_finished() once loading completes.

Return type:

None

delete_reference_line()

Delete the currently selected reference line from all plots.

Triggered when the user hovers over a reference line and presses Shift+D.

Return type:

None

execute_plugins(func, *args, **kwargs)

Execute plugin methods that are linked to specific methods within the controller.

Parameters:

func (str) – The key to the function to execute

filter_unit_pressed(filter_type, data_only=True)

Filter the ephys plots according to the type of unit selected.

Parameters:

• filter_type (str) – The unit type

• data_only (bool) – Whether the plot can be generated without histology data

Return type:

None

fit_button_pressed()

Scale the regions using reference lines and updates plots.

Called when the fit button or Enter is pressed.

Return type:

None

get_config()

Get the current config or default if both are selected.

Returns:

config – The config to use

Return type:

str

get_scaled_histology(items, **kwargs)

See ShankController.get_scaled_histology() for details.

Return type:

None

init_shanks()

Initialise the plots for each ShankController and add callbacks to plot scenes.

Return type:

None

lin_fit_option_changed(state)

Toggle the use of linear fit for scaling histology data.

Parameters:

state (int) – 0 disables linear fit, any other value enables it.

Return type:

None

load_pid(pid)

Configure the dropdowns to a probe insertion and load its data.

Resolves pid to the subject, session and shank dropdown selections, sets each dropdown accordingly and loads the data, reproducing a manual subject -> session -> shank selection followed by pressing the data button. Only valid in online mode.

Parameters:

pid (str) – The probe insertion id (UUID) to load.

Raises:

ValueError – If pid cannot be resolved to an insertion in the subject dropdown.

Return type:

None

loop_through_tabs(direction)

Move between shank tabs using left and right arrow keys.

Parameters:

direction (int) – The direction to move in, -1 for previous, +1 for next

next_button_pressed()

Update the display with next alignment stored in the alignment buffer.

Ensures user cannot go past latest move. Called when the prev button or Shift+right arrow is pressed.

Return type:

None

on_alignment_selected(idx)

Triggered when an alignment is selected from the alignment dropdown list.

Updates the reference lines to the selected alignment.

Parameters:

idx (int) – The index selected in the dropdown list

Return type:

None

on_config_selected(idx, init=False)

Triggered when a config is selected from the config dropdown list.

Parameters:

• idx (int) – The index selected in the dropdown list

• init (bool) – Whether this is the first time loading the probe or not

Return type:

None

on_folder_selected(folder_path=None)

Triggered in offline mode when a data folder is chosen from the source button.

Return type:

None

on_mouse_double_clicked(event, idx)

Handle a mouse double-click event on the ephys or histology plots.

Adds a movable reference line on the ephys and histology plots.

Parameters:

• event (pyqtgraph.GraphicsScene.mouseEvents.MouseClickEvent) – The mouse double-click event.

• idx (int) – The index of the panel that the mouse click event occured

Return type:

None

on_mouse_hover(hover_items, name, idx, config)

Handle a mouse hover event over the pyqtgraph plot items.

Identifies reference lines or linear regions the mouse is hovering over to allow interactive operations like deletion or displaying additional info.

Parameters:

• items (hover) – List of items under the mouse cursor.

• name (str) – The name of the tab being hovered over

• idx (int) – Then index of the tab that is being hovered over

• config (str) – The config of the tab being hovered over

Return type:

None

on_open_session_yaml()

Open a different session yaml (File menu) and reload the whole GUI.

Return type:

None

on_reset_levels()

Reset the levels of all plots to the default range.

Triggered by pressing Shift+R.

Return type:

None

on_session_selected(idx)

Triggered when a session/ probe is selected from the session dropdown list.

Parameters:

idx (int) – The index selected in the dropdown list

Return type:

None

on_shank_selected(idx)

Triggered when a shank is selected from the shank dropdown list.

Updates the alignment dropdown list with any previous alignments for this shank. If the data is already loaded, the display is updated to highlight the selected shank. If the layout is in tab mode, the fit lines and points on the fit plot are only shown for the selected shank.

Parameters:

idx (int) – The index selected in the dropdown list

Return type:

None

on_subject_selected(idx)

Triggered when a subject/ session is selected from the subject dropdown list.

Parameters:

idx (int) – The index selected in the dropdown list

Return type:

None

on_use_docdb_changed(_state=None)

Toggle the DocDB alignment backend and refresh the alignment dropdown.

Triggered when the DocDB checkbox is ticked/unticked (Allen workflow only). Switches the backend on the model, then (once data is loaded) reloads the previous alignments for the selected shank so the alignment dropdown and reference lines reflect the new source.

Parameters:

_state (int or None) – The checkbox state emitted by the stateChanged signal. Unused; the checkbox is queried directly via the view.

Return type:

None

on_view_changed()

Triggered when the view is changed between feature and ephys plots.

plot_channel_panels(items, **kwargs)

Plot channels on slice plots.

Return type:

None

plot_dual_colorbar(results, fig)

Update colorbar based on config selection.

When the selected_config is both, update the colorbar displayed to show the levels of both configs. The levels of the default config are shown on the top axis, and the levels of the non-default config on the bottom axis.

Parameters:

• results (Bunch) – A bunch containing the cbar figures per shank and config

• fig (str) – The name of the plot item to show the updated dual colorbar on

Return type:

None

plot_feature_panels(plot_key, data_only=True, **kwargs)

Plot feature panels per shank and config.

Parameters:

• plot_key (str) – The key of the feature plot to display

• data_only (bool) – Whether the plot can be generated without histology data

Return type:

None

plot_fit_panels(items, **kwargs)

Plot fit panel per shank and config.

Return type:

None

plot_histology_panels(items, **kwargs)

Plot histology panel per shank and config.

plot_histology_ref_panels(items, **kwargs)

Plot histology reference panel per shank and config.

Return type:

None

plot_image_panels(plot_key, data_only=True, **kwargs)

Plot image panels per shank and config.

Parameters:

• plot_key (str) – The key of the image plot to display

• data_only (bool) – Whether the plot can be generated without histology data

Return type:

None

plot_line_panels(plot_key, data_only=True, **kwargs)

Plot line panels per shank and config.

Parameters:

• plot_key (str) – The key of the line plot to display

• data_only (bool) – Whether the plot can be generated without histology data

Return type:

None

plot_panels(plot_key, plot_type, plot_func, init_attr, dual_cb_name=None, plugin_event=None, data_only=True, **kwargs)

Plot a generic panel per shank and config.

Parameters:

• plot_key (str) – The key of the plot to display

• plot_type (str) – The type of plot to update e.g. image, probe, scatter

• plot_func (str) – The name of the function used to update the plots

• init_attr (str) – The name of the attribute that stores the current plot key of the plot type e.g. self.probe_init

• dual_cb_name (str) – The name of the dual colorbar object to use

• plugin_event (str) – The plugin event name to link plugin callbacks

• data_only (bool) – Whether the plot can be generated without histology data

Return type:

None

plot_probe_panels(plot_key, data_only=True, **kwargs)

Plot probe panels per shank and config.

Parameters:

• plot_key (str) – The key of the probe plot to display

• data_only (bool) – Whether the plot can be generated without histology data

Return type:

None

plot_region_ref_panels(plot_key, data_only=True)

Handle Region Plots menu selection — delegates non-Original keys to the plugin.

Return type:

None

plot_scale_factor_panels(shanks=None)

Plot scale factor panel for list of shanks.

If the selected_config is both adjusts the display of the colorbar.

Parameters:

shanks (list or tuple) – List of shanks to plot figure for

Return type:

None

plot_scatter_panels(plot_key, data_only=True, **kwargs)

Plot scatter panels per shank and config.

Parameters:

• plot_key (str) – The key of the scatter plot to display

• data_only (bool) – Whether the plot can be generated without histology data

Return type:

None

plot_slice_panels(plot_key, data_only=True)

Plot slice panels and configure the LUT.

Parameters:

• plot_key (str) – The key of the slice plot to display

• data_only (bool) – Whether the plot can be generated without histology data

Return type:

None

Notes

• If the plot type is ‘Annotation’, the LUT is removed.

populate_menubar()

Populate menu bar tabs based on avaialble plots.

prev_button_pressed()

Update the display with previous alignment stored in the alignment buffer.

Called when next button or Shift+left arrow is pressed.

Return type:

None

remove_fit_panels(items, **kwargs)

Remove lines on fit plot for shanks other than the selected shanks.

Return type:

None

remove_points_from_display(items, **kwargs)

Remove all reference points from the fit plot.

Return type:

None

remove_reference_lines_from_display(items, **kwargs)

Remove all reference lines and scatter points from the respective plots.

Return type:

None

reset_axis_button_pressed()

Reset plot axis to default values.

Triggered by pressing Shift+A.

Return type:

None

reset_button_pressed()

Reset the feature and track alignment to initial starting alignment and updates plots.

Called when reset button or Shift+R is pressed.

Return type:

None

reset_feature_and_tracks(items, **kwargs)

See ShankHandler.reset_features_and_tracks() for details.

Return type:

None

reset_levels(items, **kwargs)

See ShankController.reset_levels() for details.

Return type:

None

reset_reference_line_arrays(items, **kwargs)

See ShankController.init_reference_line_arrays() for details.

Return type:

None

reset_shanks(items, **kwargs)

See ShankController.init_plot_items() for details.

Return type:

None

reset_slice_axis(items, **kwargs)

See ShankController.reset_slice_axis() for details.

Return type:

None

save_progress_button_pressed()

Triggered when the save progress button or Shift+S is pressed.

Saves the current alignment of the chosen shanks to file, so that it can be recovered if the GUI crashes before the alignment has been uploaded. The saved alignment is offered in the alignment dropdown the next time the data is loaded, and is deleted once the alignment has been successfully uploaded.

Return type:

None

scale_hist_data(items, **kwargs)

Scale brain regions along the probe track based on reference lines.

Return type:

None

set_ephys_plots()

Set the ephys plots to the values stored in the init variables.

Return type:

None

set_init_reference_lines(items, **kwargs)

Find the initial alignment for specified shanks and creates reference lines.

Return type:

None

set_probe_lims(items, data_only=True, **kwargs)

See ShankController.set_probe_lims() for details.

Return type:

None

set_shank_header(items, **kwargs)

See ShankController.set_header_style() for details.

Return type:

None

set_xaxis_range(items, *args, **kwargs)

See ShankController.set_xaxis_range() for details.

Return type:

None

set_yaxis_lims()

Set the y-axis limits for all shanks based on stored values.

Parameters:

data_only (bool) – Whether the plot can be generated without histology data

Return type:

None

set_yaxis_range(items, *args, **kwargs)

See ShankController.set_yaxis_range() for details.

Return type:

None

setup(init=True)

Set up the GUI display according to the config used.

Parameters:

init (bool) – Whether the GUI is being loaded for a new probe or if the config is just changing

Return type:

None

setup_connections()

Set up all the connections between the view and controller methods.

shank_tab_changed(idx)

Triggered when the tab on the shank tabs view is changed.

Parameters:

idx (int) – The index of the newly selected tab

slice_tab_changed(idx)

Triggered when the tab on the slice tabs view is changed.

Parameters:

idx (int) – The index of the newly selected tab

Return type:

None

tab_layout_changed()

Triggered when the tab layout is changed to a grid layout.

Return type:

None

toggle_channels()

Toggle visibility of channels and trajectory lines on the slice image.

Triggered by pressing Shift+C.

Return type:

None

toggle_labels()

Toggle visibility of brain region labels on histology plot.

Triggered by pressing Shift+L.

Return type:

None

toggle_layout()

Toggle the layout between the grid and shank views.

Triggered when T is pressed.

Return type:

None

toggle_plots(plot_type, direction)

Toggle through the different plot types.

Can toggle through the image, line, probe and slice plots by pressing the keys Alt+1, Alt+2, Alt+3 and Alt+4 respectively.

Parameters:

• plot_type (str) – The type of plot to toggle through e.g. image, probe, scatter

• direction (int) – The direction to toggle in, -1 for previous, +1 for next

Return type:

None

toggle_reference_lines()

Toggle visibility of reference lines.

Triggered by pressing Shift+H.

Return type:

None

update_feature_reference_line(feature_line, idx, config)

Triggered when a reference line is moved in one of the electrophysiology plots.

This function ensures the line’s new position is synchronized across the other ephys plots, and updates the corresponding scatter point in the fit plot.

Parameters:

• feature_line (pyqtgraph.InfiniteLine) – The line instance that was moved by the user.

• idx (int) – The panel number that the line instance belongs to, used to update the selected_shank

• config (str) – The config of the panel that the line instance belongs to

Return type:

None

update_plots(shanks=())

Update all plots and displays to reflect the current alignment state.

Parameters:

shanks (tuple) – The list of shanks to update plots for

Return type:

None

update_string()

Update on-screen text showing current and total alignment steps.

Return type:

None

update_track_reference_line(track_line, idx, config)

Triggered when a reference line in the histology plot is moved.

This updates the corresponding scatter point in the fit plot.

Parameters:

• track_line (pyqtgraph.InfiniteLine) – The line instance that was moved by the user.

• idx (int) – The panel number that the line instance belongs to, used to update the selected_shank

• config (str) – The config of the panel that the line instance belongs to

Return type:

None