spacr.qt.screens.outliers

Workflow inputs and outputs

Outliers

Review robust object/well outlier scores and the selected exclusion rule before carrying filtered data into analysis.

Open: QC → Outliers.

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.

Outputs

• Quality-control results — Stored project checks and QC reports; a missing check is not a passing result.

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

API reference.

Module tutorial.

The Outliers screen — flag outlying objects and outlying wells.

A thin surface over spacr.qt.widgets.outlier_model, which holds all the statistics. The screen’s only jobs are to load a table, collect the four decisions the engine needs (features, method, threshold, transform), run it off the GUI thread, and show what came back without recomputing a single number of its own.

Assembles what already exists:

• spacr.qt.screens.graph_builder.read_table() / table_names() — the same CSV/SQLite reader the Graph Builder and PCA load through, rather than a third one that reads measurements.db slightly differently;

• spacr.qt.widgets.pca_view.FeaturePicker — the same tick list PCA uses, offering the same continuous columns by the same classifier, so a user who ticked eight features for a decomposition does not meet a different list here;

• spacr.qt.job_runner.JobRunner — an MCD fit on 200,000 objects takes seconds, so it runs off the GUI thread.

Two tables, because there are two answers

The Objects tab is the per-object flags; the Wells tab is the across-well pass. They are separate tabs rather than one merged view because they answer different questions and routinely disagree: a well shifted as a whole flags almost none of its individual objects and is nevertheless the most extreme point among wells. The engine’s report() is shown verbatim in the third tab, caveats included — the share flagged is not interpretable without the sentence saying whether a symmetric fence on skewed data produced it.

The object table shows the worst rows first and caps how many it draws; the number of flagged objects in the header comes from the result, never from the number of rows the table happens to be showing. Nothing about the export is capped.

Nothing is deleted here

The export writes the whole table with the flag columns added, and separately the flagged rows on their own. There is no “remove outliers” button: dropping objects is a decision made in the analysis.

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

Classes

OutliersScreen

Load a measurement table and flag outlying objects and wells.

Functions

make_outliers_screen(→ PySide6.QtWidgets.QWidget)	Factory handed to spacr.qt.app.register_app().
register(→ bool)	Put Outliers in the app registry, through the public seam. Idempotent.

Module Contents

class spacr.qt.screens.outliers.OutliersScreen(parent=None, *, threaded: bool = True)

Bases: PySide6.QtWidgets.QWidget

Load a measurement table and flag outlying objects and wells.

Parameters:

• threaded – False runs the table read and the scan inline, in the same order and through the same signals, so a test can drive the whole screen synchronously without the behaviour diverging.

• parent – parent widget; ownership only.

Build the screen: the controls beside the object, well and report tabs.

Parameters:

• parent – parent widget, or None.

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

active_jobs() → int

How many worker threads are still winding down.

choose_table() → None

Ask for a file, then load_path() it.

closeEvent(event)

Stop background work and unlink before going away.

Parameters:

event – the Qt close event.

current_method() → str

The spacr.qt.widgets.outlier_model.METHODS member picked.

export_csv() → None

Write the flags out: the whole table, the flagged rows, the wells.

Three files, because the three have different row meanings. The first is the whole table with the columns added — the “write columns” case, and the one that keeps every object — and the second is the same rows filtered down to the flagged ones for a quick look. The engine’s own filtered() is what produces it, so the file and the screen flag the same rows.

is_busy() → bool

True while a read or a scan is in flight.

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

Load a CSV or one table of a SQLite measurement database.

The read runs on a worker thread through spacr.qt.job_runner.JobRunner; listing the table names stays inline because the picker has to be populated before the read is dispatched, to know which table to read.

Parameters:

• path – a CSV, TSV or TXT file (by extension), read as one table; any other path is opened as a SQLite measurement database and its tables are listed in the picker.

• table – the database table to read, also selected in the picker when the database has it; None reads the picker’s current table.

objects_frame() → pandas.DataFrame | None

The loaded table with the flag columns added, or None.

scan() → None

Run the engine over the loaded table, off the GUI thread.

set_frame(frame: pandas.DataFrame, *, label: str = '', scan: bool = True) → None

Scan frame. The one call a host needs.

Parameters:

• frame – unmodified measurement table to expose in the feature picker and pass to the configured outlier scan.

• scan – False loads the table and fills the feature picker without running anything, for a caller that wants to set the method first.

spec() → spacr.qt.widgets.outlier_model.OutlierSpec

The controls as an OutlierSpec. The screen’s whole state.

Raises:

OutlierError – from the spec itself on a combination it refuses — the screen never invents a value the engine would not accept.

property frame: pandas.DataFrame | None

The table being scanned, unmodified.

property result

The last OutlierResult, or None.

spacr.qt.screens.outliers.make_outliers_screen(app_key: str | None = None) → PySide6.QtWidgets.QWidget

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

spacr.qt.screens.outliers.register() → bool

Put Outliers in the app registry, through the public seam. 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 only names the 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.

SECTION_EXPLORE rather than SECTION_RESULTS. The screen concerns whether to trust a run’s output, but it works like the Gate Editor and the Feature Explorer beside it: the user picks features and a threshold, and the output is a column to filter or gate on. Results & QC holds screens that return a verdict; this one returns flags, and filtered() is the only place a row is dropped, and only when it is called explicitly.

MAX_APPS_PER_SECTION is 13, and Results & QC was already at 12 with Control Charts, a campaign-level verdict, arriving in the same batch.

Not called at import. app.py imports spacr.qt.widgets before register_app exists, so nothing reachable from the top of that file can register during its import, and a registration that happens later is one that some importer’s snapshot of APPS predates. The one place a registration is visible to everybody is spacr.qt.SELF_REGISTERING_MODULES, which spacr.qt.run() runs after spacr.qt.app is fully executed and before MainWindow.__init__ reads the registry. Turning this screen on is therefore one row there:

"spacr.qt.screens.outliers",

and nothing else: the strings above travel with the registration.

Returns:

True if this call is what registered it. Safe to call again — a module imported from two paths, or a test that re-imports it, must not raise on the duplicate key.