spacr.qt.screens.trellis

Workflow inputs and outputs

Small Multiples

Compare groups in small-multiple plots with explicit shared or independent axes.

Open: Graph Builder → Small Multiples.

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.

V5 — Small Multiples: one chart per group, in a grid, on shared axes.

Assembles four things that already exist into one surface:

• spacr.qt.widgets.trellis_view.TrellisPanelWidget — the drop zones, the scale options and the grid;

• spacr.qt.widgets.data_filter_panel.DataFilterPanel — the Local Data Filter, unchanged, so narrowing here narrows every open view;

• spacr.qt.widgets.formula_editor.FormulaPanel — computed columns, so ratio = area / perimeter ** 2 can be faceted the moment it is defined;

• spacr.qt.linked_selection — a brush on one panel highlights the same objects in the UMAP, on the plate map and in the crop grid.

Why it is a screen of its own and not a checkbox on the Graph Builder: the question a trellis answers is “does this shift hold in every plate?”, and the options that make that answerable — which panels share a scale, how a long strip of levels wraps, what n each panel is built on — are not decoration on a single chart. They are the chart.

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

Classes

TrellisScreen

A table, a filter, computed columns, and a grid of small multiples.

Functions

make_trellis_screen(→ PySide6.QtWidgets.QWidget)	Factory handed to spacr.qt.app.register_app().
register(→ bool)	Put Small Multiples in the app registry. Idempotent.

Module Contents

class spacr.qt.screens.trellis.TrellisScreen(parent=None, *, link=None, threaded: bool = True)

Bases: PySide6.QtWidgets.QWidget

A table, a filter, computed columns, and a grid of small multiples.

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 trellis panel beside the filter and column tabs.

Item 471: the panel and the side tabs share a draggable edge in a CollapsibleSplitter (trellis::body), and the side tabs fold by their heading.

Parameters:

• parent – parent widget, or None.

• link – shared selection link, passed to the panel and the filter.

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

active_jobs() → int

How many background jobs this screen is running.

Returns:

the job count.

choose_table() → None

Ask which table in the project to plot.

closeEvent(event)

Let the panel close first, so it can unlink its canvas.

Parameters:

event – the Qt close event.

is_busy() → bool

Whether anything is still running.

Returns:

True while work is outstanding.

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 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.

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

Plot frame. The one call a host needs.

Parameters:

• frame – the table to plot; it is also handed to the formula panel.

• label – source caption; empty shows the row and column counts.

set_spec(spec: spacr.qt.widgets.trellis_spec.TrellisSpec) → None

Draw a different grid.

Parameters:

spec – the trellis spec.

property spec: spacr.qt.widgets.trellis_spec.TrellisSpec

The grid the screen is drawing.

Returns:

the trellis spec.

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

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

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

Put Small Multiples in the app registry. Idempotent.

Called from spacr.qt.SELF_REGISTERING_MODULES, which spacr.qt.run() runs after spacr.qt.app is fully executed and before MainWindow.__init__ reads the registry — the position the docstring there explains.

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.