spacr.qt.screens.hit_list

Workflow inputs and outputs

Hit List

Filter and rank saved hits with their effects, FDR and guide agreement.

Open: Regression → Hit List.

Inputs and outputs below include conditional alternatives. The guidance and handoff notes say which route applies.

Inputs

• Regression results and hits — Selected run results folder: coefficient/result CSVs, hit tables, settings and diagnostic figures.

Outputs

• Figures and table exports — The output location chosen by the tool; exports describe the selected data and filters.

Before this module

• Regression: Inspect ranked hits and guide agreement.

API reference.

Module tutorial.

Hit List — the deliverable at the end of a screen.

A regression run leaves a folder of plots and four CSVs, and none of them is the thing the experiment was for. results_significant.csv is p <= 0.05 with no multiple-testing correction, no gene names, and no indication of whether a gene’s own guides agree with each other. What the user wants is one table they can sort, narrow and send to a collaborator.

This screen is that table. Point it at a results folder and it builds the list through spacr.hits, which does the work that makes a hit list interpretable rather than merely present:

• the effect size with its standard error and 95% interval;

• a q-value across the genes actually tested, so a 0.05 on two thousand genes stops meaning what it does not mean;

• gRNA agreement — how many of the gene’s own guides push the same way. A gene called by one guide of six is the commonest way a pooled screen produces a confident artefact, and it was invisible in every table spaCR wrote before this one;

• the metadata join, collapsed to one row per gene before it is joined.

The filters across the top are the ones a user actually applies: FDR, minimum effect, minimum guide agreement, minimum guide count, direction, controls in or out, and a free-text search over the annotation. They compose, they are recorded on the list, and they travel into the export — so the CSV a collaborator receives says which filters produced it rather than being an anonymous subset.

Three exports, because the three uses are different: CSV to re-analyse, Markdown to paste into an email or an issue, HTML to open on a machine that has never heard of spaCR. The HTML is self-contained — no stylesheet, no script, no network — which is what makes it safe to send.

Building the list reads several CSVs and joins them, so it runs through spacr.qt.job_runner.JobRunner, off the GUI thread.

Classes

HitListScreen

Build, filter and export the hit list of one regression run.

Functions

connect_investigation(→ bool)	Connect a hit list's investigation request to its host workbench.
make_hit_list_screen(→ PySide6.QtWidgets.QWidget)	Build the screen bare and wire its one outgoing signal.

Module Contents

class spacr.qt.screens.hit_list.HitListScreen(parent=None, folder: str = '', metadata_files: Sequence[str] = (), regression_type: str = '', threaded: bool = True)

Bases: PySide6.QtWidgets.QWidget

Build, filter and export the hit list of one regression run.

Parameters:

• parent – Qt parent.

• folder – open straight onto this results folder.

• metadata_files – annotation CSVs to join.

• regression_type – the backend, when the caller knows it. Only changes how the list is ranked — the penalised backends have no p-value and rank by bootstrap selection frequency instead.

• threaded – False builds the list inline, so a test drives the screen synchronously without the behaviour diverging.

Variables:

last_error – text of the most recent failure, "" when the last operation worked. Failures land here and in the summary strip — never in a modal dialog, which hangs a headless run.

Build the hit-list screen and arm its drop zone.

Parameters:

• parent – parent widget, or None.

• folder – regression results folder to load immediately; empty leaves the screen asking for one.

• metadata_files – extra metadata tables to join onto the hits.

• regression_type – which fit produced the results, when the caller already knows.

• threaded – read on a worker thread. Set False in tests so load_folder finishes before it returns.

active_jobs() → int

How many worker threads are still winding down.

closeEvent(event) → None

Drain the worker before the widget goes.

Parameters:

event – the close event, passed on to the base class after the worker is shut down.

current_filters() → Dict[str, Any]

The filter arguments the controls currently spell out.

A control at its neutral value contributes nothing rather than a no-op criterion, so the recorded filters on an exported list name only what the user actually asked for.

export(path: str, fmt: str = 'csv') → str

Write the list as the filters currently stand.

Parameters:

• path – where to write.

• fmt – "csv", "markdown" or "html".

Returns:

the path written, or "" when there was nothing to write.

Raises:

ValueError – on an unknown format.

filtered() → spacr.hits.HitList | None

The list as the filters currently narrow it.

hits() → spacr.hits.HitList | None

The unfiltered list, or None before anything is loaded.

is_busy() → bool

True while a hit list is still being built.

load_folder(folder: str) → None

Build the hit list for folder, off the GUI thread.

Parameters:

folder – the regression results folder, shown in the folder field and read by spacr.hits.build_hit_list() on a worker. An empty value only asks the user to choose one.

metadata_files() → List[str]

The annotation files currently joined.

set_metadata_files(paths: Sequence[str]) → None

Replace the annotation files and rebuild if a folder is loaded.

Parameters:

paths – annotation files to join to the hit list, replacing the current ones; each is stored as a string.

spacr.qt.screens.hit_list.connect_investigation(screen, host) → bool

Connect a hit list’s investigation request to its host workbench.

Repeated calls do not create duplicate signal connections.

Parameters:

• screen – HitListScreen instance, or None.

• host – Object providing _on_investigate_hit_requested, or None.

Returns:

True if a new connection was made.

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

Build the screen bare and wire its one outgoing signal.

The constructor for a caller with no run to point it at; Regression builds its own, seeded, and calls connect_investigation() itself.

Nested helpers

HitListScreen.load_folder.build()

Load the data backend in the job that reads the table.

spacr/qt/screens/hit_list.py:402