spacr.qt.screens.model_explanation

Dedicated workbenches for CV explanation and hit investigation.

Classes

ExplainCvPanel	Run and render one provenance-bearing surrogate explanation.
InvestigateHitPanel	Guide-fraction-aware, cross-fitted candidate-cell investigation.
InvestigateHitScreen	Dedicated post-regression screen with explicit promotion and undo.
ModelExplanationScreen	The screen that explains a computer-vision model's decisions.

Functions

make_investigate_hit_screen(→ PySide6.QtWidgets.QWidget)	Build the hit-investigation screen, for the app registry.
make_model_explanation_screen(→ PySide6.QtWidgets.QWidget)	Build the model-explanation screen, for the app registry.

Module Contents

class spacr.qt.screens.model_explanation.ExplainCvPanel(host=None, parent=None)

Bases: PySide6.QtWidgets.QWidget

Run and render one provenance-bearing surrogate explanation.

Parameters:

• host – the screen that runs training on this panel’s behalf – host._on_train_requested is what the “train” action reaches. None is guarded for, so the panel still builds and renders and the action simply does nothing, which is what a test wants.

• parent – parent widget.

Build the explanation panel.

Parameters:

• host – the screen that runs training on this panel’s behalf; None is guarded for, so the panel still builds and the action simply does nothing.

• parent – parent widget, or None.

closeEvent(event) → None

Shut the job pool down before going away.

A WORKER OUTLIVING ITS PANEL writes results into a widget whose C++ half is gone, which is a crash rather than a leak.

Parameters:

event – the Qt close event.

importance_methods() → list

The importance measures currently ticked, in table order.

open_activation_maps() → None

Hand off to the activation-map module for the current model.

open_held_out_objects() → None

Show the held-out objects the explanation was scored on.

Does nothing when there is no result or nothing was held out, which is the state before a run rather than a failure.

run() → None

Read the form and run the explanation, refusing an incomplete one.

Both inputs are required, and the refusal is silent-safe: a missing field is the ordinary state before the user has finished filling it in, not an error to interrupt them with.

run_analysis(database: str, predictions: str, *, path_column: str = 'path', prediction_column: str = 'pred', model_family: str = 'random_forest', split_by: str = 'well', output: str = '', importance_methods: Sequence[str] | None = None, shap_explainer: str = 'auto')

Run the surrogate explanation and render it.

SEPARATE FROM run() so the analysis can be driven without the form – a test, or another screen handing over inputs it already has.

Parameters:

• database – the measurements database.

• predictions – the model’s predictions.

• path_column – which column joins predictions to objects.

• prediction_column – which column holds the prediction.

• importance_methods – measures to compute; all three when None.

• shap_explainer – 'auto', 'tree' or 'kernel'.

class spacr.qt.screens.model_explanation.InvestigateHitPanel(host=None, parent=None)

Bases: PySide6.QtWidgets.QWidget

Guide-fraction-aware, cross-fitted candidate-cell investigation.

Parameters:

• host – the screen that runs training on this panel’s behalf – host._on_train_requested is what the “train” action reaches. None is guarded for, so the panel still builds and renders and the action simply does nothing, which is what a test wants.

• parent – parent widget.

Build the hit-investigation panel.

Parameters:

• host – the screen that runs training on this panel’s behalf; None is guarded for, so the panel still builds and the action simply does nothing.

• parent – parent widget, or None.

closeEvent(event) → None

Shut the job pool down before going away.

Parameters:

event – the Qt close event.

configure_hit(*, folder: str = '', gene: str = '', effect: float = 0.0, guides: Sequence[str] = (), fdr: float = float('nan'), phenotype: str = '', guide_agreement: float = float('nan'), n_guides: int = 0, well_support: int = 0) → None

Fill the form from a hit the regression screen picked.

The seam that makes this screen reachable from a result rather than only from a blank form: everything the investigation needs is already known at the point the user clicks a hit.

Parameters:

• folder – the run folder the hit came from.

• gene – the gene the hit names.

• effect – its effect size.

• guides – the guides supporting it.

open_candidates() → None

Show the candidate cells this investigation found.

open_umap() → None

Show the candidates in the embedding, when hosted by a screen.

promote() → None

Record this hit as annotated, against the attribution run.

REFUSES WITHOUT AN ANNOTATION. A promotion is a claim about the biology, and one with no note attached says only that somebody pressed a button.

run() → None

Read the form and run the investigation.

The guide and feature lists are comma-separated free text, so blanks are dropped rather than passed on as empty names.

run_analysis(*, database: str, predictions: str, fractions: str, gene: str, guides: Sequence[str], score: str, direction: str, features: Sequence[str], folder: str)

Run the cross-fitted investigation and render it.

Separate from run() so it can be driven without the form.

Parameters:

• database – the measurements database.

• predictions – the model’s predictions.

• fractions – the guide-fraction table.

• gene – the gene under investigation.

• guides – the guides supporting the hit.

• score – which score column to investigate.

• direction – 'positive' or 'negative': whether larger or smaller scores rank first, passed as hit_direction.

• features – measured feature columns for the attribution model, passed as hit_feature_columns; empty lets the investigation choose numeric features itself.

• folder – the regression results folder the hit came from, passed as results_folder; outputs are written below it.

undo() → None

Withdraw the last promotion.

Does nothing when there is none, so the button is safe to press twice.

class spacr.qt.screens.model_explanation.InvestigateHitScreen(host=None, parent=None)

Bases: PySide6.QtWidgets.QWidget

Dedicated post-regression screen with explicit promotion and undo.

Parameters:

• host – the screen that runs training on this panel’s behalf – host._on_train_requested is what the “train” action reaches. None is guarded for, so the panel still builds and renders and the action simply does nothing, which is what a test wants.

• parent – parent widget.

Build the screen around one InvestigateHitPanel.

Parameters:

• host – the screen that runs training on the panel’s behalf.

• parent – parent widget, or None.

apply_seed(seed: Dict[str, Any]) → None

Accept the normal MainWindow hand-off from Hit List.

Parameters:

seed – hand-off settings from the hit list. results_folder, target_gene, hit_effect, target_guides, hit_fdr, hit_phenotype, hit_guide_agreement, hit_n_guides and hit_well_support are read, each with a fallback when missing.

configure_hit(**request) → None

Forwarded to the panel this screen wraps.

Parameters:

request – the hit’s folder, gene, effect and guides.

class spacr.qt.screens.model_explanation.ModelExplanationScreen(host=None, parent=None)

Bases: PySide6.QtWidgets.QWidget

The screen that explains a computer-vision model’s decisions.

Wraps ExplainCvPanel in the standard module chrome. The header’s instruction is the order the panel enforces – fidelity FIRST, then importance – because an importance ranking read off a model that does not fit is a ranking of nothing, and it looks identical to a good one.

Parameters:

• host – the main window, for screen navigation.

• parent – Qt parent.

Build the screen around one ExplainCvPanel.

Parameters:

• host – the screen that runs training on the panel’s behalf.

• parent – parent widget, or None.

spacr.qt.screens.model_explanation.make_investigate_hit_screen(app_key: str | None = None, host=None) → PySide6.QtWidgets.QWidget

Build the hit-investigation screen, for the app registry.

Parameters:

• app_key – accepted and unused, as above.

• host – the main window, passed through for navigation.

Returns:

a new InvestigateHitScreen.

spacr.qt.screens.model_explanation.make_model_explanation_screen(app_key: str | None = None, host=None) → PySide6.QtWidgets.QWidget

Build the model-explanation screen, for the app registry.

Parameters:

• app_key – accepted and unused – the registry calls every factory with the key it registered, and this screen serves exactly one.

• host – the main window, passed through for navigation.

Returns:

a new ModelExplanationScreen.