spacr.qt.screens.experiment_design¶

Workflow inputs and outputs¶

Experiment Design¶

Enter conditions, controls, replicates and plate constraints, then export the experimental layout before acquisition.

Open: Home → Experiment Design.

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

Inputs

Screen design and power estimates — Saved planning tables or figures based on explicitly chosen effect sizes, variability and sampling assumptions.

Outputs

Experimental layout — Exported plate/condition/control/replicate map. Keep its plate and well identifiers consistent with the acquired data.

After this module

Power / Design: Use the experimental layout to define sampling assumptions, then revise the design.
Dose–Response: Acquire and measure the experiment first, preserving dose/condition identities.

API reference.

Module tutorial.

Design the plate before it is acquired, and export it once.

The screen half of spacr.qt.widgets.plate_layout. It draws the plate, lists what is wrong with the layout, and writes the three files the rest of spaCR reads – so the plate map is typed once rather than once for the plate handler and again into treatment_plate_metadata when the data comes back.

The warnings are the point rather than the drawing. Every finding it shows is about something that cannot be repaired after acquisition: controls sitting only on the plate edge, a control confined to one column, a condition with a single replicate. All of them are free to fix the day before and impossible to fix the day after.

What it is for. Planning a plate before it is imaged, as the first step of a screen: a layout can still be changed then, and the plate map exported here is what the measurements are joined to later.

What it needs. A plate identifier, a plate format from 6 to 1536 wells, and a list of conditions, each with a number of replicates and a role: treatment, positive control, negative control or blank. The layout – random, row, column or block – places the replicates, the edge setting uses the outer ring of wells or leaves it empty, and the seed makes a random layout reproducible.

What it produces. Export plate map writes three files to the chosen folder: plate_map.csv, one row per well keyed by plateID, rowID and columnID; plate_map.json, the design and the findings that were shown, so the layout can be regenerated; and plate_map_settings.json, the treatments and treatment_plate_metadata settings for an analysis. A random layout cannot be written as whole rows or columns, so that file then records why instead, and plate_map.csv is the authoritative record.

What to do next. Resolve the findings, then image the plate. When the data comes back, plate_map.csv joins the measurement tables on plateID, rowID and columnID without a translation step, and the settings file fills in the treatment settings of the analysis.

ONE PLATE WIDGET WHERE THERE CAN BE ONE. The square, the constant it is pitched at and the row/column headers come from spacr.qt.widgets.plate_map_picker rather than being declared a second time here; the two plates had already drifted apart once. What cannot be shared is the well itself, and the difference is real rather than historical: the picker’s well is a checkable QPushButton whose checked state IS the selection and which paints itself from a fixed pair of colours, while this one is a QLabel carrying a role, an edge mark, a name and a condition, painted by the theme through the properties below – a plate map that says what each well holds rather than only whether it is chosen.

Classes¶

ExperimentDesignScreen

Plate designer: conditions in, plate map and warnings out.

Functions¶

`make_experiment_design_screen`(→ PySide6.QtWidgets.QWidget)	Factory handed to `spacr.qt.app.register_app()`.
`register`(→ bool)	Add Experiment Design to the app registry. Idempotent.

Module Contents¶

class spacr.qt.screens.experiment_design.ExperimentDesignScreen(parent: PySide6.QtWidgets.QWidget | None = None, *, threaded: bool = True)[source]¶

Bases: PySide6.QtWidgets.QWidget

Plate designer: conditions in, plate map and warnings out.

Parameters:

threaded – False runs the export inline, emitting the same signals in the same order, so a test can drive the screen synchronously without the behaviour diverging.
parent – parent widget; ownership only.

Build the screen and seed it with a three-condition starting plate.

Parameters:

parent – parent widget, or None.
threaded – run the export on a worker thread. Set False in tests so export_to finishes before it returns.

active_jobs() → int[source]¶: How many worker threads are still winding down.

begin_well_drag(row: int, column: int, modifiers=None) → None[source]¶

Anchor a selection on one well.

Parameters:

row – the anchor well’s row index, counting from zero.
column – the anchor well’s column index, counting from zero.

closeEvent(event)[source]¶

Stop background work and unlink before going away.

Parameters:: event – the Qt close event.

conditions() → Tuple[spacr.qt.widgets.plate_layout.Condition, ...][source]¶

The conditions currently in the table, skipping unusable rows.

A half-typed row is not an error to shout about – the user is in the middle of typing it – so it is dropped and the plate redrawn from what is complete.

design() → spacr.qt.widgets.plate_layout.PlateDesign[source]¶: The design the form currently describes.

drag_wells_to(position) → None[source]¶

Preview the rectangle from the anchor to the well under a point.

Parameters:: position – the pointer as a QPoint in global screen coordinates; ignored when no drag is anchored, when it is over no well, or when the well has not changed since the last call.

export_to(folder) → bool[source]¶

Write the plate map. The file writing happens off the GUI thread.

Parameters:: folder – destination directory.
Returns:: whether the job was started.

findings_text() → str[source]¶: Every finding line currently on screen, joined. For tests.

finish_well_drag() → None[source]¶: End the gesture. The selection is already what the preview showed.

is_busy() → bool[source]¶: True while an export has not finished.

load_template(key: str, *_args) → bool[source]¶

Replace the design with the shipped template called key.

Everything but the plate name is replaced: the name has to match the image files the user will acquire, which no template can know.

Parameters:

key – a template key, see template_keys().
_args – whatever the menu action passes; ignored.

Returns:

True when the template was found and loaded.

refresh() → None[source]¶: Redraw the plate and the findings from the current form.

selected_well_names() → list[source]¶: The chosen wells as names, in reading order.

selected_wells() → set[source]¶: Every (row, column) currently chosen on the map.

status_text() → str[source]¶: The status line. For tests.

template_keys() → List[str][source]¶: The keys of the templates on the menu, in menu order.

well_at(position)[source]¶

The (row, column) under a GLOBAL point, or None.

Parameters:: position – a QPoint in global screen coordinates, mapped into each well’s own coordinates to test containment.

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

spacr.qt.screens.experiment_design.register() → bool[source]¶: Add Experiment Design to the app registry. Idempotent.