spacr.qt.screens.tabulate¶

Workflow inputs and outputs¶

Tabulate¶

Choose grouping variables and measurement columns, then inspect pivot tables and groupwise sample sizes.

Open: Help search → Database Browser → Tabulate.

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

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

API reference.

Module tutorial.

The Tabulate screen — a pivot table, and the chart of it underneath.

A JMP-style Tabulate: drag plateID down the rows, gene across the columns, tick the aggregations, read the numbers.

Four parts:

spacr.qt.widgets.pivot_builder.PivotPanel — the wells and the grid;
spacr.qt.widgets.graph_builder.GraphBuilderPanel — the chart of the summary, in the lower half of the splitter;
spacr.qt.widgets.data_filter_panel.DataFilterPanel — the Local Data Filter, so narrowing the population narrows the table and every other open view at once;
spacr.qt.screens.graph_builder.read_table() — the same CSV/SQLite reader the Graph Builder loads through.

The table is not a chart¶

“Plot this table” hands the Graph Builder to_long() — one row per non-empty cell, one column per statistic — and the Graph Builder does the rest. So x = plateID, y = mean, size = n is a drag, and there is no second implementation of scales, facets or colour to keep in step with the first.

Two things follow from the summary being a real frame rather than a picture, and both are intended:

the chart’s own status line reports no object keys in this table, because a summary row is a group, not an object. Brushing it cannot publish an object selection, and the status line says so instead of publishing an empty one.
the chart is on its own linked-selection source, so it does not answer to a lasso drawn over individual cells somewhere else.

Filter, then aggregate¶

A filter change recomputes the pivot rather than restyling it, for the same reason it recomputes a PCA: an aggregate is a property of the population, and a mean of the unfiltered rows shown next to a filtered plot is the kind of mismatch nobody catches by eye.

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

Classes¶

TabulateScreen

Load a measurement table, pivot it, and plot the summary.

Functions¶

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

Module Contents¶

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

Bases: PySide6.QtWidgets.QWidget

Load a measurement table, pivot it, and plot the summary.

Parameters:

link – a private LinkedSelection for tests. None joins the process-wide one.
parent – parent widget; ownership only.
threaded – False runs every table read inline instead of on the job runner’s thread. A test needs the result on the line after the call; a user needs the window to keep painting while a large table loads. The jobs are the same either way – they still register, still report failure through job_failed – so only the waiting differs.

Build the screen: the pivot builder beside the shared filter.

The pivot, the graph and the filter are sections of CollapsibleSplitter panes – each folds by its heading and each shared edge drags.

Parameters:

parent – parent widget, or None.
link – shared selection link.
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 worker threads are still winding down.

choose_table() → None[source]¶: Ask which table in the project to use.

closeEvent(event)[source]¶

Stop background work and unlink before going away.

Parameters:: event – the Qt close event.

is_busy() → bool[source]¶: True while a table read is in flight.

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

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

The read runs on a worker thread. SELECT * FROM cell into pandas measures 1.5 s for a 200 000-row measurement table on a warm local SSD; run inline, the read would stop the whole window from redrawing. Listing the table names stays inline – it is one sqlite_master query, measured at 0.4 ms – because the picker has to be populated before the read is dispatched, to know which table to read.

Returns as soon as the read is dispatched; _on_frame_loaded() finishes on the GUI thread.

Parameters:: path – a .csv, .tsv or .txt file, or any other suffix as a SQLite database whose table names fill the table picker. A database that cannot be listed is reported in the source line and nothing is read.

plot_summary(frame: pandas.DataFrame | None = None) → None[source]¶

Hand the summary to the Graph Builder.

The summary rows are groups rather than objects, so the chart’s status line will say the table carries no object keys and that brushing cannot publish a selection, because a summary row is a group of objects, not an object.

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

Pivot frame. The one call a host needs.

Parameters:: frame – the table to filter and pivot; it replaces the current one.

spacr.qt.screens.tabulate.make_tabulate_screen(app_key: str | None = None) → PySide6.QtWidgets.QWidget[source]¶: Factory handed to spacr.qt.app.register_app().

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

Put Tabulate in the app registry, through the public seam. Idempotent.

The row – intro, cli_note, api_module and translations among it – is declared in spacr.qt.app_catalog, and spacr.qt.app.register_app() distributes it into the four registry tables.

Returns:: True if this call is what registered it. Safe to call twice.

Not called at import, for the reason app.py’s _SELF_REGISTERING_APPS table documents: a registration made anywhere else is one that some importer’s snapshot of APPS predates. The screen is listed in that table as:

("spacr.qt.screens.tabulate", "register"),