clearex.gui.app

Functions

`get_dashboard_relay_manager`()	Return the shared GUI dashboard relay manager singleton.
`launch_gui`([initial, run_callback, ...])	Launch the PyQt GUI for workflow selection/execution.
`run_workflow_with_progress`(*, workflow, ...)	Execute a workflow while showing a modal GUI progress dialog.
`summarize_image_info`(info)	Build GUI-friendly metadata label strings.

Classes

`AnalysisExecutionProgressDialog`(args, *kwargs)	Modal progress dialog for analysis execution.
`AnalysisExecutionWorker`(args, *kwargs)	Background worker that executes selected analysis workflows.
`AnalysisSelectionDialog`(args, *kwargs)	Second-step GUI dialog for selecting and sequencing analysis operations.
`BatchDataStoreMaterializationWorker`(*args, ...)	Background worker that prepares canonical stores for many experiments.
`ClearExSetupDialog`(args, *kwargs)	First-step GUI dialog for experiment setup and store readiness.
`DaskBackendConfigDialog`(args, *kwargs)	Dialog for configuring Dask backend execution mode and parameters.
`DataStoreMaterializationWorker`(args, *kwargs)	Background worker that materializes canonical store data.
`ExperimentMetadataCacheEntry`(experiment, ...)	Cache one resolved setup metadata context for an experiment path.
`ExperimentStorePreparationRequest`(...)	Describe one experiment store that may need canonical materialization.
`ExperimentStorePreparationResult`(...)	Record the outcome of preparing one experiment's canonical store.
`GuiRunCallback`(args, *kwargs)
`MaterializationProgressDialog`(args, *kwargs)	Modal progress dialog for canonical store creation.
`SpatialCalibrationDialog`(args, *kwargs)	Dialog for configuring store-level stage-to-world axis bindings.
`ZarrSaveConfigDialog`(args, *kwargs)	Dialog for configuring analysis-store Zarr chunking and pyramid factors.

Exceptions

GuiUnavailableError

Raised when the PyQt GUI cannot be launched in this environment.

class clearex.gui.app.GuiRunCallback(*args, **kwargs): Bases: Protocol

exception clearex.gui.app.GuiUnavailableError

Bases: RuntimeError

Raised when the PyQt GUI cannot be launched in this environment.

clearex.gui.app.get_dashboard_relay_manager()

Return the shared GUI dashboard relay manager singleton.

Return type:: DashboardRelayManager

clearex.gui.app.summarize_image_info(info)

Build GUI-friendly metadata label strings.

Parameters:: info (ImageInfo) – Image metadata returned by an image reader.
Returns:: Flattened text fields for GUI presentation.
Return type:: dict[str, str]

class clearex.gui.app.ExperimentMetadataCacheEntry(experiment, source_data_path, image_info, experiment_signature, source_signature, override_directory)

Bases: object

Cache one resolved setup metadata context for an experiment path.

Parameters:

experiment (NavigateExperiment) – Parsed experiment metadata.
source_data_path (pathlib.Path) – Resolved acquisition source path.
image_info (ImageInfo) – Source metadata summary loaded for the setup panel.
experiment_signature (tuple[int, int], optional) – Cached signature of the experiment descriptor file.
source_signature (tuple[int, int], optional) – Cached signature of the resolved source path.
override_directory (pathlib.Path, optional) – Source-directory override active at cache creation time.

experiment: NavigateExperiment

source_data_path: Path

image_info: ImageInfo

experiment_signature: Optional[tuple[int, int]]

source_signature: Optional[tuple[int, int]]

override_directory: Optional[Path]

class clearex.gui.app.ExperimentStorePreparationRequest(experiment_path, experiment, source_data_path, target_store)

Bases: object

Describe one experiment store that may need canonical materialization.

Parameters:

experiment_path (pathlib.Path) – Navigate experiment.yml path represented in the setup list.
experiment (NavigateExperiment) – Parsed experiment metadata used for canonical store preparation.
source_data_path (pathlib.Path) – Resolved acquisition data path referenced by the experiment metadata.
target_store (pathlib.Path) – Canonical ClearEx store path for this experiment.

experiment_path: Path

experiment: NavigateExperiment

source_data_path: Path

target_store: Path

class clearex.gui.app.ExperimentStorePreparationResult(experiment_path, store_path, skipped_existing)

Bases: object

Record the outcome of preparing one experiment’s canonical store.

Parameters:

experiment_path (pathlib.Path) – Navigate experiment.yml path that was evaluated.
store_path (pathlib.Path) – Canonical store path used or created for that experiment.
skipped_existing (bool) – Whether an already-complete canonical store was reused without rematerialization.

experiment_path: Path

store_path: Path

skipped_existing: bool

class clearex.gui.app.ZarrSaveConfigDialog(*args, **kwargs)

Bases: QDialog

Dialog for configuring analysis-store Zarr chunking and pyramid factors.

Parameters:

initial (ZarrSaveConfig) – Initial Zarr save configuration used to populate controls.
parent (QDialog, optional) – Parent dialog widget.

Variables:

result_config (ZarrSaveConfig, optional) – Selected configuration when dialog is accepted.

class clearex.gui.app.SpatialCalibrationDialog(*args, **kwargs)

Bases: QDialog

Dialog for configuring store-level stage-to-world axis bindings.

Parameters:

initial (SpatialCalibrationConfig) –
parent (Optional[QDialog]) –

class clearex.gui.app.DaskBackendConfigDialog(*args, **kwargs)

Bases: QDialog

Dialog for configuring Dask backend execution mode and parameters.

Parameters:

initial (DaskBackendConfig) – Initial backend configuration used to populate controls.
parent (QDialog, optional) – Parent dialog widget.
recommendation_shape_tpczyx (Optional[Tuple[int, int, int, int, int, int]]) –
recommendation_chunks_tpczyx (Optional[Tuple[int, int, int, int, int, int]]) –
recommendation_dtype_itemsize (Optional[int]) –

Variables:

result_config (DaskBackendConfig, optional) – Selected configuration when dialog is accepted.

eventFilter(watched, event)

Handle hover and focus transitions for registered parameter help.

Parameters:

watched (PyQt6.QtCore.QObject) –
event (Optional[PyQt6.QtCore.QEvent]) –

Return type:

bool

class clearex.gui.app.DataStoreMaterializationWorker(*args, **kwargs)

Bases: QThread

Background worker that materializes canonical store data.

Parameters:

experiment (NavigateExperiment) – Parsed Navigate experiment metadata.
source_data_path (pathlib.Path) – Source acquisition data path.
dask_backend (DaskBackendConfig) – Backend configuration used for Dask execution.
zarr_save (ZarrSaveConfig) – Zarr chunk and pyramid configuration.

Variables:

progress_changed (pyqtSignal) – Signal with (percent, message) progress payload.
succeeded (pyqtSignal) – Signal with resulting store path string.
failed (pyqtSignal) – Signal with error text.

progress_changed: alias of int

succeeded: alias of str

failed: alias of str

run()

Execute materialization workflow in the background.

Parameters:: None –
Returns:: Emits success/failure signals on completion.
Return type:: None
Raises:: None – Exceptions are converted to failed signals.

class clearex.gui.app.BatchDataStoreMaterializationWorker(*args, **kwargs)

Bases: QThread

Background worker that prepares canonical stores for many experiments.

Parameters:

requests (sequence[ExperimentStorePreparationRequest]) – Ordered experiment store requests that still require preparation.
dask_backend (DaskBackendConfig) – Backend configuration used for Dask execution.
zarr_save (ZarrSaveConfig) – Zarr chunk and pyramid configuration to enforce.
force_rebuild (bool) –

Variables:

progress_changed (pyqtSignal) – Signal with (percent, message) progress payload.
succeeded (pyqtSignal) – Signal with a list of ExperimentStorePreparationResult objects for all prepared stores.
failed (pyqtSignal) – Signal with error text.

progress_changed: alias of int

succeeded: alias of object

failed: alias of str

run()

Execute batch canonical-store preparation in the background.

Parameters:: None –
Returns:: Emits success/failure signals on completion.
Return type:: None

class clearex.gui.app.MaterializationProgressDialog(*args, **kwargs)

Bases: QDialog

Modal progress dialog for canonical store creation.

Parameters:

title_text (str, optional) – Title shown at the top of the dialog.
initial_message (str, optional) – Initial progress message shown before updates arrive.
parent (QDialog, optional) – Parent window.

update_progress(percent, message)

Update progress bar and stage text.

Parameters:

percent (int) – Progress percentage value.
message (str) – Human-readable stage text.

Returns:

Widget state is updated in-place.

Return type:

None

class clearex.gui.app.AnalysisExecutionWorker(*args, **kwargs)

Bases: QThread

Background worker that executes selected analysis workflows.

Parameters:

workflow (WorkflowConfig) – Workflow configuration selected in GUI.
run_callback (callable) – Callback with signature (workflow, progress_callback, dask_client_lifecycle_callback=None) that executes the workflow.
dask_client_lifecycle_callback (Optional[DaskClientLifecycleCallback]) –

Variables:

progress_changed (pyqtSignal) – Signal with (percent, message) progress payload.
succeeded (pyqtSignal) – Signal emitted when execution completes successfully.
failed (pyqtSignal) – Signal carrying an error message when execution fails.

progress_changed: alias of int

cancelled: alias of str

failed: alias of str

cancel()

Request cooperative cancellation of the running workflow.

Parameters:: None –
Returns:: Cancellation is recorded in-place and checked on progress callbacks.
Return type:: None

run()

Execute the configured workflow in the background.

Parameters:: None –
Returns:: Emits success/failure signals.
Return type:: None

class clearex.gui.app.AnalysisExecutionProgressDialog(*args, **kwargs)

Bases: QDialog

Modal progress dialog for analysis execution.

Parameters:: parent (QDialog, optional) – Parent window.

update_progress(percent, message)

Update progress bar and stage message.

Parameters:

percent (int) – Progress percentage value.
message (str) – Human-readable stage text.

Returns:

Widget state is updated in-place.

Return type:

None

set_dashboard_available(available, tooltip=None)

Update dashboard button availability and tooltip text.

Parameters:

available (bool) –
tooltip (Optional[str]) –

Return type:

None

class clearex.gui.app.ClearExSetupDialog(*args, **kwargs)

Bases: QDialog

First-step GUI dialog for experiment setup and store readiness.

Parameters:: initial (WorkflowConfig) –

eventFilter(watched, event)

Handle list keyboard removal and drag/drop routed through the list.

Parameters:

watched (QObject) – Widget emitting the event.
event (QEvent) – Qt event object to evaluate.

Returns:

True when the event was handled, otherwise base class event filter result.

Return type:

bool

dragEnterEvent(event)

Accept dialog-level drags containing experiment inputs.

Parameters:: event (QDragEnterEvent) – Incoming drag-enter event.
Returns:: Event acceptance is updated in-place.
Return type:: None

dragMoveEvent(event)

Accept dialog-level drag-move events for valid experiment inputs.

Parameters:: event (QDragMoveEvent) – Incoming drag-move event.
Returns:: Event acceptance is updated in-place.
Return type:: None

dropEvent(event)

Handle dialog-level drops for experiment inputs.

Parameters:: event (QDropEvent) – Incoming drop event.
Returns:: Experiment list and event acceptance are updated in-place.
Return type:: None

class clearex.gui.app.AnalysisSelectionDialog(*args, **kwargs)

Bases: QDialog

Second-step GUI dialog for selecting and sequencing analysis operations.

Parameters:: initial (WorkflowConfig) –

eventFilter(watched, event)

Handle hover/focus transitions for parameter-help updates.

Parameters:

watched (QObject) – Widget emitting the event.
event (QEvent) – Qt event object.

Returns:

Returns base class event filter result.

Return type:

bool

reject()

Persist current GUI state before dismissing the dialog.

Parameters:: None –
Returns:: Dialog state is persisted best-effort before rejection.
Return type:: None

closeEvent(event)

Persist current GUI state before the dialog closes.

Parameters:: event (QCloseEvent) – Close event emitted by Qt.
Returns:: Close handling is delegated to QDialog after persistence.
Return type:: None

clearex.gui.app.launch_gui(initial=None, run_callback=None, dask_client_lifecycle_callback=None)

Launch the PyQt GUI for workflow selection/execution.

Parameters:

initial (WorkflowConfig, optional) – Initial workflow values to pre-populate GUI controls.
run_callback (callable, optional) – Optional execution callback. When provided, the GUI runs in iterative mode: after each analysis run, the analysis-selection dialog is shown again so the user can select the next task. Signature must be (workflow, progress_callback, dask_client_lifecycle_callback=None).
dask_client_lifecycle_callback (callable, optional) – Optional lifecycle callback forwarded into run_workflow_with_progress() during iterative GUI execution.

Returns:

In single-run mode (no run_callback), returns the selected workflow. In iterative mode, returns None when the user explicitly exits.

Return type:

WorkflowConfig, optional

Raises:

GuiUnavailableError – If PyQt6 is not installed or no display server is available.

Notes

The launch path ensures ~/.clearex exists and attempts to pre-populate GUI backend controls from the last persisted backend settings JSON.

clearex.gui.app.run_workflow_with_progress(*, workflow, run_callback, dask_client_lifecycle_callback=None)

Execute a workflow while showing a modal GUI progress dialog.

Parameters:

workflow (WorkflowConfig) – Workflow configuration to execute.
run_callback (callable) – Callback that performs workflow execution. Signature must be (workflow, progress_callback, dask_client_lifecycle_callback=None).
dask_client_lifecycle_callback (callable, optional) – Optional lifecycle callback forwarded to the workflow run callback.

Returns:

True when execution succeeds, False when it fails.

Return type:

bool

Raises:

GuiUnavailableError – If PyQt6 or a display server is unavailable.

Notes

SLURMCluster/SLURMRunner backend startup can require Python signal handlers, which must be installed from the main interpreter thread. For these backend modes, execution is run synchronously on the GUI thread with explicit processEvents updates.