tabs

GUI tabs for ClearMap.

All the classes in this module are subclasses (direct or indirect) of the ExperimentTab and GroupTab classes which derive from GenericTab and provide the basic structure and methods that are common to all tabs.

Presentation

Each tab manages a specific part of the processing pipeline and has its own UI elements. It is composed of:

• ui: QWidget constructed from a .ui file that defines the layout and the widgets.

• sample_manager: handles the sample metadata and workspace.

• sample_params: experiment-level object that links the UI to the sample configuration file.

• params: tab specific parameter link object (UI - config). (For the SampleInfoTab, this is the SampleParameters object.)

• name: used to identify the tab in the GUI.

• processing_type: identifies the type of tab, one of (None, ‘pre’, ‘post’, ‘batch’).

Abstract tabs hierarchy

• GenericTab: base class for all tabs, handles the UI and channel pages.

• ExperimentTab: base for tabs tied to a single experiment (SampleInfo, Stitching, Registration, CellMap, TractMap, Colocalization).

• PipelineTab: base for Pre/Post-processing tabs.

• PreProcessingTab / PostProcessingTab: specialisation of PipelineTab that form the basis for concrete tabs.

• GroupTab: base for group/multi-experiment tabs.

• BatchTab: abstract tab for batch/group workflows (e.g. batch processing, group analysis).

Optionally, for Pipeline tabs (PreProcessingTab and PostProcessingTab), a worker object is used to handle the processing steps and computation.

Tab setup flow

Setup order

Typical calling sequence is:

• tab.setup

• tab.set_params

  • sets sample_params if not SampleInfoTab

  • calls tab._set_params

  • calls tab._setup_workers (for pipeline tabs)

  • calls tab._create_channels (if the tab has channel pages)

  • calls tab._load_config_to_gui (via params)

  • calls tab._bind_params_signals (for tab-specific signals)

Tabs with channels

Some tabs can have channel pages. Channel pages are created by add_channel_tab() (invoked from set_params() and, for tabs that allow it, the (+) button). To control the behaviour of this method, the following methods can be implemented in the concrete tab classes:

• _setup_channel(page_widget, channel) (optional): additional setup for the UI (before binding).

• _bind_channel (required): wire channel-page-specific actions which are not automatically set through the params object attribute.

PipelineTab additional setup methods

• _setup_workers: sets up the worker (Processor) which handles the computations associated with this tab. Called in set_params and also when the sample config is applied.

Processing steps

Pre/Post processing tabs expose worker orchestration methods. UI widgets are wired via ParamLinks (and bus events), while buttons typically call small wrappers that run steps in threads and update progress dialogs.

---

class BatchProcessingTab(main_window, tab_idx: int, *, group_controller: AnalysisGroupController | None = None)

Bases: BatchTab

run_batch_process() → None

class CellCounterTab(main_window, tab_idx: int, sample_manager=None)

Bases: PostProcessingTab[CellDetector]

The tab responsible for the cell detection and cell coordinates alignment

detect_cells(channel: str) → None

Run the cell detection on the whole sample

filter_cells(channel: str) → None

handle_tool_tab_changed(tab_idx: int) → None

Triggered when a new sub tab (tooltab) of the cell detection tab is selected. It will either plot the cell parameter distributions or update the cell count display.

Parameters:

tab_idx (int)

make_colocalization_compatible(channel: str) → None

on_selected() → None

Called when this tab is selected; override in subclasses if needed.

plot_cell_filter_results(channel: str) → None

Plot the cells as colored dots on top of the raw image fraction used for tests

plot_cell_map_results(channel: str) → None

Plot the voxelization (density map) result

plot_debug_cropping_interface(channel: str) → None

Plot the orthoslicer to select a subset of the sample for cell detection tests

plot_detection_results(channel: str) → None

Display the different steps of the cell detection in a grid to evaluate the filters

plot_labeled_cells_scatter(channel: str, raw: bool = False) → None

Plot the cells as colored symbols on top of either the raw stitched (not aligned) image or the resampled (aligned) image

post_process_cells(channel: str) → None

preview_cell_filter(channel: str) → None

run_cell_map() → None

Run the whole pipeline at once

run_channel(channel: str) → None

Run the whole pipeline at once for a single channel

run_tuning_cell_detection(channel: str) → None

Run the cell detection on a subset of the sample which was previously selected

setup_cell_param_histogram(cells: DataFrame, plot_item: PlotWidget | None, key: str = 'size', x_log: bool = False) → PlotWidget

Plots the histogram of the cell parameter defined by key.

Parameters:

• cells (pd.DataFrame) – The Cells dataframe containing one row per detected cell

• plot_item (pg.PlotWidget | None) – Existing widget to reuse; creates a new one if None.

• key (str) –

  The key (cell attribute) in the dataframe to plot.

  One of ‘size’ or ‘source’

• x_log (bool) – X axis is logarithmic

update_cell_number(channel: str) → None

Update the cell count number displayed based on the detected/filtered cell files

voxelize(channel: str) → None

Creates the cell density plot

channels_ui_name = 'cell_map_params'

pipeline_name = 'cell_map'

workers_are_global = False

class ColocalizationTab(main_window, tab_idx: int, sample_manager)

Bases: PostProcessingTab[ColocalizationProcessor]

plot(channel_a: str, channel_b: str) → None

run_colocalization_for_pair(channel_a: str, channel_b: str) → None

save_filtered_table(channel_a: str, channel_b: str) → None

sort_channels(channel_a: str, channel_b: str) → tuple[str, str]

Return the channels ordered based on the state of the First channel radio buttons

Parameters:

• channel_a (str) – The name of the first channel

• channel_b (str) – The name of the second channel

Returns

tuple[str, str]

(first_channel, second_channel) as chosen by the user

voxelize_filtered_table(channel_a: str, channel_b: str) → None

channels_ui_name = 'colocalization_params'

pipeline_name = 'colocalization'

workers_are_global = False

class GroupAnalysisTab(main_window, tab_idx: int, *, group_controller: AnalysisGroupController)

Bases: BatchTab

get_analysable_channels() → list[str]

List the channels that have density maps available for analysis.

Warning

Assumes all samples have the same channels.

Returns

list of str

The list of channels that have density maps available

handle_groups_changed(event: UiBatchGroupsChanged) → None

make_group_stats_tables() → None

plot_density_maps(group_name: str)

plot_histograms(fold_threshold: int = 2) → None

plot_p_vals(*_, **__)

plot_volcanoes() → None

run_df_plots(plot_function: Callable, plot_kw_args: dict) → list

run_p_vals() → None

advanced_controls_names: list[str]

property processor

class RegistrationTab(main_window, tab_idx: int, sample_manager=None)

Bases: PreProcessingTab[RegistrationProcessor]

clear_landmarks(channel: str) → None

handle_align_with_changed(event: UiAlignWithChanged) → None

launch_landmarks_dialog(channel: int | str) → None

plot_registration_results() → None

Plot the result of the registration between 2 channels. Either side by side or as a composite

If the composite checkbox is checked, the two images are overlayed. Otherwise, they are displayed side by side

resample_channel(channel: str) → None

run_registration() → None

Run the actual registration between the sample and the reference atlas.

setup_atlas() → None

Setup the atlas that corresponds to the orientation and cropping of the sample

write_registration_landmark_coords(channel: str) → None

Write the corresponding landmarks to file for use in landmark optimised registration

advanced_controls_names: list[str]

channels_ui_name = 'registration_params'

landmark_selector: LandmarksSelectorDialog | None

pipeline_name = 'registration'

class SampleInfoTab(main_window, tab_idx: int, sample_manager=None)

Bases: ExperimentTab

The tab manager to define the parameters of the sample. This refers to values that are intrinsic to the sample and the acquisition like resolution, orientation …

display_atlas(event: UiRequestPlotAtlas) → None

Plot the atlas as a grayscale image in the viewer

edit_workspace_folders() → None

Open a dialog to edit workspace.resource_type_to_folder and propagate changes via SampleManager.set_resource_type_to_folder().

go_to_orientation() → None

Jump to the sample orientation (space info) tab

launch_pattern_wizard() → None

Start the pattern selection wizard. This wizard helps create the pattern strings for the individual tiles, with specific characters representing the digits for the different axes.

plot_mini_brain(event: UiRequestPlotMiniBrain) → None

Plot the brain icon which represents the acquisition sample orientation graphically to help users pick the right orientation.

prepare_channel_raw_data(event: UiPrepareRawDataForClearMap) → None

Per-channel ‘stitched’ asset creation from button.

prompt_prepare_all_channels_raw_data(force: bool = False) → None

GUI wrapper for bulk raw-data preparation with user confirmation.

Checks which pipeline-ready channels still need their working asset (npy tiles for tiled channels, stitched volume in npy for non-tiled) and presents a confirmation dialog before proceeding.

Prompts automatically once per session on first call. Subsequent automatic calls are no-ops; the manual button bypasses this guard via force=True.

Parameters:

force (bool) – If True, include already-prepared channels and bypass the once-per-session guard. Intended for the manual re-import button.

remove_channel(channel: str) → None

remove_current_channel() → None

Remove the current channel from the sample

update_atlas(event) → None

detached: bool

property src_folder: Path

class StitchingTab(main_window, tab_idx: int, sample_manager=None)

Bases: PreProcessingTab[StitchingProcessor]

The tab responsible for all the alignments, including the stitching and aligning to the atlas.

convert_tiles() → None

on_selected() → None

Called when this tab is selected; override in subclasses if needed.

plot_stitching_results(_) → None

Plot the stitched image in 3D in the viewer

preview_stitching_dumb(channel: str, color: bool) → None

Preview the stitching based only on a dumb overlay of the tiles i.e. only using the fixed guess overlap

Parameters:

• channel (str) – The channel to preview

• color (bool) – Whether to stitch in chessboard or continuous grayscale

preview_stitching_smart(channel: str, asset_sub_type: str = 'aligned_axis') → None

Preview the stitching based on the actual stitching variable, rigid by default.

Parameters:

• channel (str) – The channel to preview

• asset_sub_type (str) – One of (‘aligned_axis’, ‘aligned’, ‘placed’)

prompt_conversion(channel: str) → str | None

Prompt the user to convert the tiles to npy for efficiency

Parameters:

channel (str) – The channel to convert

run_stitching() → None

Run the actual stitching steps based on the values in the config file (set from the UI).

set_run_channel(_, state: bool, channel: str) → None

Set the channels to run the stitching on

Parameters:

• state (bool) – Whether the channel is checked

• channel (str) – The name of the channel

update_plotable_channels() → None

advanced_controls_names: list[str]

channels_ui_name = 'stitching_params'

pipeline_name = 'stitching'

class TractMapTab(main_window, tab_idx: int, sample_manager=None)

Bases: PostProcessingTab[TractMapProcessor]

The tab responsible for the tract map processing and visualization.

binarize_channel(channel: str) → None

compute_clipping_range(channel: str) → None

create_tuning_sample(channel: str) → None

Create an array from a subset of the sample to perform tests on

export_df(channel: str) → None

extract_coordinates(channel: str, tuning: bool) → None

intensities_to_percentiles(channel: str) → None

Convert the intensities to percentiles

label_coordinates(channel: str) → None

plot_binarization_thresholds(channel: str) → None

plot_binary(channel: str) → None

plot_debug_cropping_interface(channel: str) → None

Plot the ortho-slicer to select a subset for tracts detection tests

plot_labeled_tracts_scatter(channel: str, raw: bool = False) → None

plot_tract_map_results(channel: str)

run_channel(channel: str, tuning: bool) → None

run_tract_map(channel: str) → None

run_tuning_tract_map(channel: str) → None

transform_coordinates(channel: str) → None

voxelize(channel: str) → None

advanced_controls_names: list[str]

channels_ui_name = 'tract_map_params'

pipeline_name = 'tract_map'

workers_are_global = False

class VasculatureTab(main_window, tab_idx: int, sample_manager=None)

Bases: PostProcessingTab[BinaryVesselProcessor]

Tab for vasculature binarization, graph extraction and analysis.

Two distinct workers are accessed via substep:

• substep=’binary’ → BinaryVesselProcessor

• substep=’graph’ → VesselGraphOrchestrator

..note::

get_worker() is @overloaded so call sites resolve to the correct type automatically.

add_graph_filter() → None

binarize_and_postprocess_channel(channel: str, stop_on_error: bool = False) → None

Run the enabled binarization steps for channel in pipeline order.

Parameters:

• channel (str) – Channel name to process.

• stop_on_error (bool) – Whether to stop the process if an error occurs.

build_graph() → None

Run the pipeline to build the vasculature graph

combine() → None

Combine binarized channels into a single mask.

display_graph_chunk(graph_step: str) → None

Display a chunk of the graph selected with the slicer

Parameters:

graph_step (str) – The name of the step to display (from ‘raw’, ‘cleaned’, ‘reduced’, ‘annotated’)

display_graph_chunk_from_cfg() → None

pick_region() → None

Open a dialog to select a brain region and plot it

plot_binarization_results(plot_side_by_side: bool = True) → None

Plot the thresholded images resulting from the binarization at the steps specified by the comboboxes in the UI.

Parameters:

plot_side_by_side (bool) – Whether to plot the images side by side (True) or overlay them (False).

plot_graph_structure() → None

Plot a subregion of the vasculature graph corresponding to a brain structure

plot_graph_type_processing_chunk_slicer() → None

Plot the ortho-slicer to pick a sub part of the graph to display.

Warning

Depending on the display options, the whole graph may not fit in memory

plot_voxelization()

Plot the density map

post_process_graph() → None

Post process the graph by filtering, tracing and removing capillaries

run_all() → None

Run the complete vasculature pipeline.

save_stats() → None

Save the stats of the graph to a feather file

unload_temporary_graphs() → None

Unload the temporary vasculature graph objects to free up RAM

update_file_suffix(event: UiVesselGraphFiltersChanged) → None

Update the file suffix for the filtered graph

voxelize() → None

Run the voxelization (density map) on the vasculature graph

advanced_controls_names: list[str]

channels_ui_name = 'vasculature_params'

pipeline_name = 'vasculature'

workers_are_global = True

ui_task_progress(title_fn: Callable, steps_fn: Callable) → Callable

Wraps a tab method that performs a task and updates the main progress. - title_fn(self) -> str e.g. lambda s: “Group stats” - steps_fn(self) -> int e.g. lambda s: len(s.params.selected_comparisons)