Capabilities¶

spaCR processes an image-based screen from raw microscopy files to a ranked hit list. This page lists its capabilities by area; the Python API quickstart and interactive tutorials cover individual workflows.

Core screen workflow¶

Mask¶

Mask prepares TIFF, OME-TIFF, LIF, CZI and ND2 acquisitions and segments cells, nuclei, pathogens and organelles with Cellpose. It supports 2-D, volumetric and time-series data, estimates object diameter, and can exchange mask corrections with the layer viewer or napari.

The objects are not a fixed set of four. A project has a cell, a nucleus and a pathogen, a cytoplasm derived from them, and as many organelle slots as number_of_organelles specifies – from none up to twenty-six. Each slot is independent, with its own channel, diameter, detection method and morphology.

A slot is given a morphology preset – punctate, vesicular, spherical, filamentous, tubular, reticular, cisternal, toroidal, crescent, or custom – and the preset chooses the detection strategy, one of spots, network, irregular or ring.

Mask generation lays out the per-object settings as one table under Per-object settings, with a column for each object whose channel is set; the cell column is always shown. An object’s channel is set on the ordinary form, and the values of a hidden object are kept for when its channel is set again. Every object has a Remove background check box, and the cell column also has Adjust cells. Add a filter adds a row that filters objects on any scikit-image regionprop, such as area or mean intensity; each object’s cell takes 200 – 5000, a minimum alone (200), a maximum alone (– 5000) or a blank for no filter. These rows are the object_filters setting. Choosing a Cellpose 3 model for an object shows a Cellpose 3 category with that backend’s own settings. Quality Control holds the segmentation checks together with output, storage, runtime and reliability settings.

Mask’s Live preview shows the result as Overlay, Masks, Flows or Cell probability. Right-click a picture to Save as PNG… or Save as PDF…. Once a session has produced more than one mask, Compare masks… lays the masks and images you tick over one another, each with its own opacity and stacking order, in a panel of its own.

Measure¶

Measure writes per-object morphology, intensity, texture, radial, spatial and colocalization features to measurements.db. It can save classifier-ready object crops, estimate illumination correction from a plate, restrict work to a region of interest and report segmentation quality before a run.

Measure’s settings are grouped as Input & Experiment, Mask & Channel Mapping, Image Preprocessing (with Image Deconvolution (PSF) and Illumination Correction), Features, Object Filtering, Crop Output, 3D Calibration (Beta) and Postprocessing (with Runtime & Reliability). The segmentation-quality verdict is opt-in: the QC switch beside 3D and Time opens it in a popup, and closing the popup turns the switch off.

Annotate and Classify¶

Annotate provides a keyboard-driven crop grid, records labels directly in the project database and can rank an active-learning queue by uncertainty. A page holds as many crops as fit and never scrolls; the rest are on the next page. After Suggest…, suggested crops carry a ? badge: click one or press Y to confirm it, right-click or press N to reject it, and U undoes. Confirm the rest of the page and Reject the rest of the page judge every remaining suggestion at once. Rejections are stored; in a two-class column, the next training round uses a rejected suggestion as an example of the other class. Classify trains PyTorch image models or classical and boosted models from measurement tables. Checkpoints record their dataset, split rule, class balance and held-out metrics. The Essentials view of Classify holds what is needed to choose and train either family — an image model such as ResNet or MaxViT, or a tabular model such as XGBoost or a random forest — and greys the settings of the family not chosen.

Classify CV also offers optional rotations and reflections at inference time. See Classifier evaluation workbench for the aggregation methods, original and mean probabilities, and orientation-stability flags.

Map Barcodes¶

Barcode mapping decodes row, column and gRNA barcodes from FASTQ reads, joins them to imaged wells and reports abundance, collision, unmapped-read and library-coverage checks.

Regression¶

Regression estimates guide, gene, condition and control effects. Its model families cover continuous, fractional, binary and count responses, robust and quantile fits, penalised high-dimensional designs, mixed effects and guide permutation. Diagnostics and run summaries are written beside the result.

Planning, quality control and exploration¶

Power and Design estimate cell and well requirements and lay out plates, controls and replicates.
QC Dashboard combines segmentation, plate, annotation-agreement and leakage checks.
Batch correction provides centering, z-scoring, robust z-scoring, control centering and ComBat with protected biological covariates.
Graph Builder, gates and linked views connect summary plots to the object crops behind them.
Feature, dose-response, control-chart and outlier views inspect a result without an export/re-import cycle.
Layer and lineage views connect images, masks and the cell → nucleus → pathogen object hierarchy.

In Live Preview, QC image views and the raw/enhanced comparison, wheel zoom keeps the image point beneath the pointer in place. This also works when the image is smaller than its viewport; Fit or opening a new image resets the extra navigation space. Linked comparison views update together after the zoom. Orthogonal image views zoom around the pointer without moving the crosshair’s selected position.

For Toxoplasma compartment-intensity comparisons, see Recruitment: compartment ratios and channel identity.

Reproducibility and interoperability¶

Every run can record its identifier, seed, resolved settings and outputs. Interrupted workflows can resume from checkpoints, and the run history can compare settings and artefacts. Measurements export to AnnData; optional integrations read or write OME-Zarr, connect to OMERO and send masks to napari.

How a module is reached¶

The home screen groups modules into four categories – Core, Data, Tools and Organism – and nineteen modules have a tile in one of them. Core holds the pipeline modules, run in order; Data holds import, embeddings, run comparison, design, dose–response and QC; Tools holds modules that operate on an existing project rather than pipeline steps; Organism opens the Toxoplasma guide and its available assays. Planned analyses are marked Coming soon. Make Masks is filed under Tools.

Most modules do not have a tile; they inspect or extend work started in another module. They open from:

a button on their host’s masthead – as a page beside that host’s settings, already pointed at the same project. Investigate Hit and Prediction Profiler open from Regression; Format Converter and External Masks from Import; Layer Viewer, Control Charts and Outliers from QC.
the Help menu, for the ones that inspect or administer work that already exists rather than belonging behind any one module – Run History, Pipeline Graph, Project Browser, Database Browser, Report, Data Manager, Plate Queue, Batch Runner and Distributed Jobs.
the command palette (Ctrl+K), which reaches EVERY module, tiled or not. It is the one route with no exceptions, and the keyboard user’s navigation.

Modules without a tile are installed, translated and documented in the same way as tiled modules, and those that are pipelines also run headlessly under spacr-run.

Host	Opens from its masthead
Mask	Timelapse
Measure	Illumination Correction, AnnData Export, Motility Assay
Annotate	Annotator Agreement
Classify	Classifier Evaluation, Explain CV Model, Activation Maps
Map Barcodes	Barcode QC
Regression	Volcano Explorer, Hit List, Methods & Results
Image UMAP	Image Scatter, PCA
Make Masks	Cellpose Workbench, Mask the whole folder, Model Compare, Model Zoo, Curate, Napari Bridge

Parameter Sweep is reached a third way: it is a panel on the Regression screen, opened by the Parameter sweep switch on its settings form.

Picking up where you left off¶

Session restore: every ordinary start reopens the module that was on screen when spaCR last closed or crashed, with its settings and input folder. No run is started. While the status bar says what was reopened, its Open fresh button puts that module’s default settings back and goes to Home; spacr-qt --fresh skips the restore for one start. Turn it off in Preferences → Modules → Session (on by default). A module named on the command line, or a Force restart record, takes precedence.
Settings autosave: every 30 seconds the unsaved settings of every open module are kept as a draft in the preference store; nothing is written when nothing changed. A clean exit drops the drafts. If spaCR ended without closing, the next start asks once whether to restore them (drafts identical to the reopened session are not asked about). The same behaviour applies on Linux, macOS and Windows, because the store is Qt’s own settings store.

Undo and redo¶

Ctrl+Z undoes and Ctrl+Shift+Z or Ctrl+Y redoes in a module’s settings panel, in the Gate Editor and in Annotate:

in the settings panel, each changed setting is one step. Loading settings, applying a template or replaying a run does not add steps. While you are typing in a text field, Ctrl+Z undoes the typing first;
in the Gate Editor, each change to the gates (drawing, moving, renaming or deleting a gate) is one step;
in Annotate, U and Ctrl+Z undo the last label and Ctrl+Shift+Z or Ctrl+Y puts it back;
the Make Masks editor keeps its own Undo and Redo.

Running jobs¶

Help → Window → Jobs opens the Jobs panel at the right edge of the window. It lists every job that is running, with its module, a progress bar, the time elapsed and its last output line. Cancel asks that job to stop. With nothing running, the panel says No jobs are running.

Two spaCR windows¶

You can open more than one spaCR window. When a module runs, spaCR claims its source folder, which holds measurements.db and the results, and the Queue screen claims the plate queue. If another window already uses that folder or queue, Project open in another window names the other process and offers:

Open read-only: look without writing. This window then refuses to run a pipeline that writes there, and the Queue screen cannot change or run the queue;
Continue anyway: write as well, when you are sure the other window is idle. Two windows writing the same queue, database or results folder can corrupt them;
Cancel.

The answer is remembered for that folder until the window closes. A window that ended without closing does not keep its claims: the next window takes them over. The lock files are in ~/.spacr/locks; set SPACR_LOCK_DIR to keep them elsewhere.

Accessibility¶

Every control has a name that screen readers announce, taken from its label, tooltip or placeholder, and the names follow the interface language. Tab moves out of text boxes and tables to the next control instead of typing a tab. Preferences → Appearance → Theme offers High contrast, in which all text has a contrast ratio of at least 7:1 against its background.

Data-art themes¶

Under Preferences → Appearance, Theme selects the interface palette; the ten night palettes remain available. Animation chooses a decorative background independently, or None to stop it. These backgrounds do not display project measurements. The main window defaults to spaCR field; the Settings backdrop defaults to None.

The animation menu lists spaCR field, spaCR advection, spaCR growth, spaCR waves, spaCR blobs, spaCR aurora, spaCR stratified, and spaCR spinn, in that order.

spaCR field — A crisp gravitational dot field with optional local mouse influence and expanding ripples.
spaCR advection — Fine particles form evolving vortices and branching currents, with optional mouse gravity.
spaCR growth — Short mycelial segments grow from one starting point per colony and fork repeatedly. Each fork redirects the continuing tip and starts a daughter tip, so the branched front advances across the screen. Density controls the number of live tips. Older trails fade as new colonies begin; visible ink stays within a quarter of the screen.
spaCR waves — Round points carry travelling waves and move away from the mouse within its enabled radius.
spaCR blobs — Soft colour blobs, large and small, drift and slowly change size.
spaCR aurora — Irregular curtains of fine rays rise from luminous folds, fan towards the sky, and change length and brightness independently. The spaCR palette uses green with pink upper light for this theme; other selected palettes remain available.
spaCR stratified — A slow starfield moves in three depth layers; spaCR stratified direction selects up, down or random travel.
spaCR spinn — Fine paper facets move gently and spin locally in response to the mouse. Rotation is fastest beside the pointer and fades smoothly to zero at the Mouse gravity radius; changing the radius changes the affected area.

Mouse gravity radius sets the affected area as a percentage of the shorter screen edge. Its default is 15%; set it to 0 to disable mouse influence. Animation density changes the number of elements independently of Animation detail, which changes drawing resolution. Density has a minimum of 1%; increasing Detail does not trim the chosen population. The renderer bounds its sampling work within the screen’s pixel budget. Select Random in Animation palette for per-element colours. Fresh installations use Dark, spaCR field and the spaCR animation palette, with Density 10%, Gravity 15%, Detail, Speed and Size 100%, and Page opacity 60%. Dot blinking controls the percentage of visible dots that flash white: 0 switches it off (the default), and nonzero values range from 0.00001% to 10%. The setting applies to spaCR field, spaCR advection, spaCR waves and spaCR stratified. Field fade is on. The blue rim uses a relative perimeter length of 17%, Chase 50%, centred alignment, Beat mode and a 1.5 s cycle. Existing saved preferences remain in effect until changed or reset.

Animation background colour sets the background independently of the animation palette. Until you choose a colour, it follows the page theme; Theme colour restores that behaviour. The chosen colour’s brightness is kept within the active Dark or Light theme’s range. It applies to the main window, module screens and animated settings popups. A full-screen wallpaper can cover the background fill.

Popup wave frequency sets automatic waves per minute in spaCR field. The default is 5 waves/minute; 0 disables popup waves. When enabled, opening a popup immediately starts the first wave from its centre, followed by waves at the selected rate. Moving the popup moves the origin of new waves; closing it stops new waves while existing waves fade. This control is independent of mouse gravity, dot blinking, density and drawing detail.

Press Apply to preview changes while Preferences stays open. A separate question offers Keep or Revert. Revert restores the saved and live settings; your edited controls remain available to change or apply again. Closing the question also reverts. Save keeps changes and closes Preferences.

Preferences keeps four lines of help visible below the settings. Longer help scrolls within the strip without moving the dialog. Drag the strip’s narrow top edge to make it taller or shorter; Preferences remembers the chosen height. Moving from a control into the strip keeps its help available to read and scroll.

Settings backdrop remains independent of the main animation during both Apply and Save. None disables popup motion while retaining the blue rim. Settings backdrop darkness controls the settings card’s opacity over its animation, from 0% to 100% (default 85%), combined with Page opacity. Page opacity also applies when Settings backdrop is None. Higher darkness values cover more of the animation to make text easier to read. Popups remain above their owning spaCR window without using a global always-on-top flag, so other applications can cover them.

In spaCR field, left-drag an unoccupied background area to pull a local patch of dots. Releasing the button lets it spring back smoothly without restarting the pattern. This background gesture leaves scientific canvas and control gestures available.

Arranging the window¶

Home keeps its panels in a right-hand column. Drag the column’s arrow handle to resize it, or click it to fold the column away and bring it back. The Text size slider below the lowest panel scales the text in those panels.
The dock: while it is shown, drag its edge to make it wider or narrower; double-click the edge to fit it to the module names again.
A module’s right-hand column (console, actions and the other panels) resizes as one by dragging its left edge. Hold Ctrl and scroll over it to make its text larger or smaller; Ctrl+0 over the column returns to the default size.
Tooltips appear once the pointer has rested on a control for the Tooltip delay set in Preferences → Appearance (2.0 s by default; 0 shows them at once) and stay while the pointer is on them. The same delay applies to popup tooltips. Fixed hint text at the bottom of Home and Preferences appears immediately. Turn popup tooltips off with Show tooltips on the same page.

These sizes are remembered between sessions.

To resize a popup, point at one of its edges or corners. A thin blue guide line appears across the middle half of each side you can drag. Drag from anywhere along that edge or corner; the line only marks the side.

Make Masks¶

Make Masks corrects masks by hand and carries the Cellpose loop on its masthead. Its canvas has ten tools: Brush, Erase, Erase object, Wand, Draw, Box, Divide / Merge, Zoom, Recrop and Ruler. Wand adds a region by default; hold Ctrl while clicking to remove it. The Make Masks reference covers these tools, Levels, detection settings, primary/secondary pairing, saving and measurement.

Box draws independent class-labelled rectangles for YOLO annotation. Move or resize a box, undo or redo edits, and use Save boxes to preserve the project or Export YOLO… to write normalized labels and ordered class metadata. Source images and segmentation masks remain unchanged.

Draw traces a free-form outline that closes and fills as a single object – the tool a brush is not, because a brush stamps disks along the path, so tracing a rim with it labels the rim and leaves the middle background. Divide / Merge splits an object with a left-dragged line: the larger component retains its ID and the smaller receives a new one. Right-drag a line across objects to merge them under the first crossed ID, without painting the background between them. Other objects keep their labels.

Recrop is the only tool that changes which field is on screen rather than what is painted on it. A staged crop holding several cells is not one training example, and curating it as one teaches a network that two objects are one picture – so a box round an object writes that region of both the image and the mask as a field of its own, queued straight after the current one, and the multi-object original is retired into recropped_originals/ rather than curated. A box smaller than the minimum side, or one repeating a cut already made, is refused; objects the box cuts through are dropped, because an object whose boundary is where the mouse was released is not that object; and the labels that survive are renumbered from one.

Running Cellpose-SAM from this screen shows its two intermediate outputs beside the mask: the cell-probability map and the flow field. A mask is a threshold applied to that probability map, and a candidate object is discarded when its flows disagree with the ones the network predicted by more than the flow-error threshold. When a mask is wrong, those two panes are where the reason is visible.

Settings that apply¶

The settings panel shows a control only when it applies to the run being set up:

the settings of a slot past number_of_organelles, its channel included, are removed from the form;
an object whose channel names no plane is not in the run at all, so its settings are not on the form;
a setting belonging to one morphology is dropped for a slot of another: a punctate organelle has no ridge filter.

The 3D and Time switches declare which dimensions the plate has. z_stack declares a z axis and enables the volumetric settings – segmentation mode, anisotropy and voxel size – and stops with an error rather than guessing which axis is z. timelapse declares a time axis and reveals tracking; a single-timepoint plate ignores it. The 4D settings apply only when the data is both a z-stack and a time series, and appear only then.

Timelapse event annotations and pretrained features (alpha)¶

Enable Show alpha features in Preferences to use Event annotations… in Timelapse. Choose an existing spaCR tracks CSV and its matching image sequence, open the tracked field and confirm the pairing. Select an observed track and zero-based frame, enter an event name and press Add or update. Save writes the staged labels to an annotations CSV and selects it for event detection; closing without saving leaves the file unchanged. One track at one frame can have only one event label. Changed tracker or annotation files must be reopened before saving.

The annotation table names field, track_id, frame and event; an object column identifies the tracked object type. Label every event in fields used for training. The event detector evaluates held-out annotated fields, reports precision, recall and timing error, then trains and saves a model for reuse. Event classes come from the experiment’s annotations.

The default small encoder runs on CPU. The optional videomae encoder uses pretrained video features from VideoMAE event encoder in Model Zoo, installed in its own environment. Supply the verified local official checkpoint folder and exactly three ordered source-channel indices; use [0,0,0] only when deliberately repeating a monochrome channel. The frozen encoder can use CUDA, Metal or CPU; the small event classifier trains on CPU. The checkpoint’s Kinetics classes are not microscopy event labels, and pretrained features require held-out evaluation on the intended microscopy experiment. The checkpoint is licensed CC-BY-NC-4.0; inference downloads no weights. These controls remain alpha.

Figure settings¶

Preferences → Figures sets how every spaCR figure looks and how it is saved. The settings apply to figures drawn on screen and to the files the pipelines and the save buttons write; only the settings you change are applied, so a figure keeps its own look for everything else.

Text and lines: font, the sizes of titles, axis labels, tick labels and legend entries (Legend size), line width and marker size.
Colour: the palette for categories and the Colormap for heat maps, images and density plots. viridis (the default) and cividis stay readable with colour-blindness and in greyscale.
Layout: background, grid, axis lines and Despine offset, which moves the axis lines away from the data. Figure width and Figure height, in inches, set the size of new figures; the height applies when the page shape is custom.
Saving: Format is PDF, PNG, SVG or TIFF, with its resolution. Also save writes a second copy in another format beside each saved figure, for example a PNG next to a PDF. Vector text keeps text editable in PDF and SVG files instead of turning it into outlines.
Bar and point graphs: Error bars shows the standard error (sem, the default), the standard deviation (sd), a confidence interval at the CI level (ci), a 95% interval (ci95) or nothing. Error-bar cap size sets the cap width. Point overlay draws the individual points over bar and box graphs, spread by Jitter width and drawn with the opacity in Point alpha.

Settings can also differ per graph type. A figure is styled once, so a change you make with its right-click menu is kept when it is saved. Figures that are already drawn with several panels keep their size and resolution; the size and resolution settings apply to new figures and to saved files.

Working with figures¶

Right-click any figure in spaCR, in a module’s figure list or in an embedded plot such as Graph Builder, the UMAP explorer or a training comparison, to open its figure menu. The Volcano explorer and the Gate Editor keep their own right-click menus and add these entries to them.

Edit figure… changes the title, axis labels, limits, scales, fonts, colours, legend, size and resolution of this figure. Changes appear as you make them.
Change graph type redraws the figure as another graph that fits its data. Groups can be shown as box, violin, strip, swarm, bar, point or boxen plots, a box or bar plot with points, or as histogram, KDE or ECDF; two measurements as scatter, line, hexbin, KDE or regression plots; one distribution as histogram, KDE, ECDF, box, violin, strip or boxen; counts as a count plot or heat map; and a matrix as a heat map or clustered heat map. The figure is redrawn from its data and keeps your Figure settings.
Statistics… shows the test spaCR chose for the data and lets you override the Test, the Subject column, Paired / repeated measures and the Multiple-comparison correction. Show on the plot draws the test and significance brackets on the figure.
Save figure (zip)… writes one zip file with the figure in your saved format and as PNG, data.csv with the plotted data, statistics.csv and statistics.txt, spec.json with the figure’s full recipe, and recreate_figure.py, a script that draws the same figure from the CSV and JSON files without spaCR.

How the statistics are chosen¶

The automatic choice follows the data:

Groups: each group is tested for normality (Shapiro–Wilk) and the groups for equal variance (Bartlett, or Levene when a group is not normal). Two groups are compared with Student’s t, Welch’s t or Mann–Whitney, and paired data with a paired t test or Wilcoxon. Three or more groups get a one-way ANOVA followed by Tukey HSD, Welch’s ANOVA followed by Games–Howell, Kruskal–Wallis followed by Dunn, or Friedman followed by pairwise Wilcoxon tests, with pairwise p-values corrected for multiple comparisons.
Two measurements: Pearson or Spearman correlation, chosen by normality.
Counts: chi-square, or Fisher’s exact test when an expected count is below 5; tables larger than 2×2 use the Fisher–Freeman–Halton test with a fixed-seed Monte Carlo p-value.
Proportions (a 0/1 outcome): a two-proportion z test or Fisher’s exact test; three or more groups get chi-square followed by corrected pairwise z tests.

statistics.csv has one row per test, with the test name, groups, statistic, degrees of freedom, p-value, adjusted p-value and correction, effect size, number of observations, whether the test was chosen automatically or by you, and the reason for the choice.

Figures in Graph Builder and the Volcano explorer carry their data rows. For other figures, spaCR reads the plotted values back from the figure; box and violin plots drawn this way keep only their summary, not the individual rows. A new graph type replaces a faceted Graph Builder grid with a single plot until Graph Builder draws the chart again.

Workers and free memory¶

Before a module starts its workers, spaCR estimates how much memory each worker needs from one input, such as a field, mask, crop batch or table. If the n_jobs you set would leave less than 12.5% of the computer’s RAM free, a popup shows the estimate, the free memory and the number of workers that fit. Choose Use N workers (recommended) to run with that number, or keep your own number; Measure then pauses new fields whenever free memory drops below the reserve. Free RAM by closing applications… lists your own largest programs. Nothing is ticked at first, and only the programs you tick are asked to quit, after you confirm; they can usually save first, but unsaved work in them may still be lost.

Runs started without the GUI lower n_jobs to the number that keeps the reserve free and print a warning. Turn ram_guard off in Advanced to keep your n_jobs unchanged; Measure still waits while free memory is below the reserve.

Worker startup and final retries¶

spaCR starts the first application worker immediately, then spaces additional process and thread workers by ten seconds. This applies to spaCR’s managed pools, executors, independent mask workers and data-loading workers. It staggers worker initialization, not every image or database operation. Numerical libraries may still manage their own internal threads.

When a task exhausts its normal attempts because of a recognized resource overload, spaCR keeps it for one final attempt in a separate serial queue. This queue starts only after the primary tasks finish. SQLite busy or locked errors, explicit memory exhaustion and exhausted operating-system resources qualify. Invalid inputs, cancellation and unexplained worker deaths do not. A final failure remains an error with its original evidence; it is not retried again.

Maturity labels¶

The API uses these labels consistently:

Stable: Supported entry points used by the principal Mask, Measure, Classify, barcode and regression workflows. Backward-incompatible changes require a deprecation period.
Advanced: Supported specialist functionality whose defaults or result schema may still evolve. Release notes describe material changes.
Experimental: Early interfaces intended for evaluation. They may change between minor releases and should be pinned before use in an automated workflow.
Internal: GUI widgets, workers and implementation helpers. They are documented for contributors but are not a compatibility promise.

Optional dependencies¶

The base package contains the Qt desktop interface and headless pipelines. Extras add OME-Zarr, OMERO, napari, attribution, tracking, Zernike measurements and vendor readers. Availability varies with Python version; the installer guide is the authoritative compatibility table.