spacr.ops_engine

Workflow inputs and outputs

OPS

Use sequencing-cycle images and phenotype alignment to decode barcodes per nucleus. Aggregate/join the decoded identities to compatible phenotype inputs before Regression; the OPS database is not a drop-in FASTQ count CSV.

Open: Mask → OPS.

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

Inputs

  • Microscope images — Source image folder; original files, supported vendor files or imported TIFFs.

  • Aligned mosaic and coordinates — Align & Stitch destination: composed image and the tile-coordinate/layout records needed to interpret it.

Outputs

  • Optical barcode assignments — OPS destination measurements.db: per-well geometry, phenotype alignment, nuclei and barcode tables; optional per-cycle reads. Relevant tables, depending on the route: ops_geometry, ops_phenotype, ops_objects, ops_barcodes, ops_reads.

Before this module

  • Align & Stitch: Carry tile coordinates and original sequencing cycles into OPS; a flattened mosaic alone is insufficient.

After this module

  • Regression: Join/aggregate decoded objects to phenotype and guide inputs explicitly before Regression; this is not a direct CSV handoff.

API reference.

Module tutorial.

Run an optical pooled screen’s sequencing acquisition from tiles to tables.

One call takes each well from its tile files to the tables of measurements.db: ops_geometry, where each nuclear tile sits in the well frame; ops_phenotype, where each field of the high-magnification phenotype acquisition lands on that frame and which tile covers it; ops_objects, one row per nucleus, segmented on the composed nuclear map and numbered once for the well; ops_barcodes, one row per nucleus whose attributed reads agree; and, when asked for, ops_reads, one row per read per cycle behind those barcodes.

A file that cannot be read costs one cycle of the field it belongs to and is listed in the report; it does not cost the well.

Functions

run_ops(→ Dict[str, Any])

Stitch, place, segment and decode the wells of one sequencing acquisition.

Module Contents

spacr.ops_engine.run_ops(settings: Mapping[str, Any], *, wells: Sequence[str] | None = None, phases: Sequence[str] = _PHASES, library=None) → Dict[str, Any][source]

Stitch, place, segment and decode the wells of one sequencing acquisition.

Parameters:

  • settings –

    the OPS settings. Read here: genotype_source, the folder of sequencing tiles, searched recursively; phenotype_source, the folder of the high-magnification phenotype acquisition, which the phenotype phase places on the stitched well and which an empty value skips; dst_root, where measurements.db and the per-well reports go, the source folder when empty; plate, the source folder’s name when empty; ops_gpu; n_workers, how many fields decode at once; cellpose_model and cellpose_diameter; ops_library, a guide library CSV the library keyword overrides; and the five measured numbers ops_base_channels, ops_read_threshold, ops_raster_overlap, ops_window_overlap and ops_footprint, each of which falls back to the value this plate was validated at. ops_store_reads writes ops_reads.

    EITHER FOLDER MAY BE A PARENT OF BOTH HALVES, and each setting still reads its own: genotype_source indexes only names that carry a cycle and phenotype_source only names that do not, falling back to cycled names for a phenotype acquisition that carries them. Pointing both at 20200202_6W-LaC024A therefore runs the plate, rather than filing 1,281 phenotype fields and 333 sequencing ones as one acquisition – see _index_tiles().

  • wells – which wells to run; every well found when None.

  • phases – any of "stitch", "phenotype", "objects" and "decode", run in that order. A phase left out reads what it needs from the database, so a well can be stitched once and decoded again.

  • library – the guide barcodes, as a sequence or the path of a CSV with a prefix, barcode or sequence column. When given, each barcode is also mapped to its closest guide. Overrides the ops_library setting.

Returns:

{"db": path, "wells": {well: {phase: report}}}.

Raises:

ValueError – when the source holds no tiles this can name, an unknown phase or well is asked for, or a phase’s input is missing.

Nested helpers

_decode_field.load_slot(slot)

Read one original source with the shared deferred overload policy.

spacr/ops_engine.py:1381

_largest_component.find(site: int) → int

The representative of site’s component.

Parameters:

site – a site.

Returns:

its root.

spacr/ops_engine.py:432

_phenotype.seed_of(site: int) → Tuple[float, float]

Where a phenotype field’s centre is expected, before aligning it.

Parameters:

site – the phenotype site.

Returns:

the (y, x) seed in the well frame.

spacr/ops_engine.py:889

_phenotype.usable_under(window) → Dict[int, Tuple[float, float]]

The placed tiles that touch window and read.

Parameters:

window – the rectangle about to be composed.

Returns:

site -> (y, x) for compose_window().

A WELL IS NOT OPENED TO COMPOSE A WINDOW OF IT. Six anchors need about nine tiles each; testing readability over every placement instead pulled all 333 of the reference well’s sequencing tiles, and tifffile reads the whole five-plane 1,480 px file for one plane of it – 22 MB each, about 7 GB over NFS per well, before compose_window then re-read the nine it wanted. The overlap test is the same rounding compose_window uses, so a tile is offered here exactly when it would have been used there; a tile that will not read is dropped so the composer never sees a None.

spacr/ops_engine.py:910

_st_register_intensity.shrink(image)

Return the grayscale registration image and its reduction factor.

spacr/ops_engine.py:2337