spacr.qt.screens.feature_explorer

Workflow inputs and outputs

Feature Explorer

Rank measured features for a chosen class comparison; review filtering and class definitions before interpreting the ranking.

Open: Classify → Feature Explorer.

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

Inputs

  • Measured objects — measurements/measurements.db; object tables depend on the enabled cell, nucleus, pathogen and organelle masks. Relevant tables, depending on the route: cell, nucleus, pathogen, cytoplasm. Relevant columns, depending on the route: plateID, rowID, columnID, fieldID.

  • Training annotations — A chosen annotation column in measurements/measurements.db, table png_list; labels belong to object identities. Relevant tables, depending on the route: png_list. Relevant columns, depending on the route: prcfo.

Outputs

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

Before this module

  • Measure: Define the class comparison and inspect filtering.

API reference.

Module tutorial.

V4 — Feature Explorer: which of the four hundred features separates them.

spaCR measures hundreds of features per object, so the useful question is never “plot cell_area by condition” — it is “which of these actually differs, and by how much”. This screen answers that one: every continuous column scored against a class column, sorted by separation, with the distributions of the top few drawn underneath.

The statistic is AUC by default and the reason is written down in spacr.qt.widgets.feature_rank; so is what it cannot see, which the panel puts on screen next to the picker rather than in a manual.

Assembles the ranking panel with the Local Data Filter (so a ranking can be restricted to one plate without leaving the screen) and the B7 formula panel (so a derived feature is ranked alongside the measured ones). The ranking runs on a worker thread through spacr.qt.job_runner.JobRunner: four hundred features over two hundred thousand objects is a sort per feature, and doing that on the GUI thread is a frozen window.

register() is not called at import; read its docstring.

Classes

FeatureExplorerScreen

A table, a filter, computed columns, and a ranking of every feature.

Functions

make_feature_explorer_screen(→ PySide6.QtWidgets.QWidget)

Factory handed to spacr.qt.app.register_app().

register(→ bool)

Put the Feature Explorer in the app registry. Idempotent.

Module Contents

class spacr.qt.screens.feature_explorer.FeatureExplorerScreen(parent=None, *, link=None, threaded: bool = True)[source]

Bases: PySide6.QtWidgets.QWidget

A table, a filter, computed columns, and a ranking of every feature.

Parameters:

  • parent – parent widget.

  • link – the LinkedSelection this screen’s views join, so a selection made here reaches the others. None joins the shared one; pass a private one in a test.

  • threaded – whether the work runs off the GUI thread. False runs it inline, which is what makes a test deterministic.

Build the screen: the ranking panel beside the filter and column tabs.

Parameters:

  • parent – parent widget, or None.

  • link – shared selection link. Injectable so a test drives a private one rather than the process-wide link every other open view is also listening to.

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

active_jobs() → int[source]

How many background jobs this screen is running.

Returns:

the job count.

choose_export() → None[source]

Ask where to write the ranking.

choose_table() → None[source]

Ask which table in the project to rank.

closeEvent(event)[source]

Shut background work down before going away.

Parameters:

event – the Qt close event.

export_ranking(path: str) → str | None[source]

Write the ranking to a file.

Parameters:

path – where to write it.

Returns:

True when it was written.

is_busy() → bool[source]

Whether anything is still running.

What the window asks before closing: a ranking exported while its run is still going would be an export of half of it.

Returns:

True while work is outstanding.

load_path(path: str, table: str | None = None) → None[source]

Read a CSV or one table of a measurement database, off the GUI thread.

Parameters:

  • path – a .csv, .tsv or .txt table, or any other file treated as a measurement database whose table names fill the table picker.

  • table – the database table to read; None reads the table currently chosen in the picker.

ranking_frame() → pandas.DataFrame | None[source]

The ranking as a tidy frame — one row per feature, every statistic.

Every statistic, not only the one ranked by: a reader who wants to know whether the top feature is a shift or a spread should not have to re-run the screen with a different picker.

set_frame(frame: pandas.DataFrame, *, label: str = '') → None[source]

Point the screen at a table to rank.

Parameters:

frame – the rows, or None to clear.

property spec: spacr.qt.widgets.feature_rank.ExplorerSpec[source]

What the screen is currently set to rank.

Returns:

the explorer spec.

spacr.qt.screens.feature_explorer.make_feature_explorer_screen(app_key: str | None = None) → PySide6.QtWidgets.QWidget[source]

Factory handed to spacr.qt.app.register_app().

spacr.qt.screens.feature_explorer.register() → bool[source]

Put the Feature Explorer in the app registry. Idempotent.

The row itself – the key, the name, the blurb, the section, the “no headless run” sentence, the API doc link and the nine translations of the display name – is declared in spacr.qt.app_catalog. spacr.qt.app.register_app() distributes those into the four tables each used to need a hand-edit in, and this function’s whole job is to name which row. That is what lets the app be registered without importing this module at all: the launch reads the table, and the screen is imported when somebody opens it.

Returns:

True if this call is what registered it.