spacr.omero¶

OMERO import / export — a spaCR project out of a server, and results back in.

A large share of imaging labs never see a filesystem. Their images live in an OMERO server, they are addressed by id, and the only way anyone looks at a result is the right-hand panel in OMERO.web. spaCR, by contrast, is built around a flat folder of Yokogawa-named TIFFs. This module is the bridge, in both directions, and it is deliberately two directions rather than one: a one-way copy out of OMERO leaves the answers stranded in a folder nobody on the microscope side will ever open.

What it does¶

Import. import_dataset() and import_plate() take an OMERO Dataset or Plate id and write a spaCR source folder:

plate1_A01_T0001F001L01A01Z01C01.tif plate1_A01_T0001F001L01A01Z01C02.tif plate1_A01_T0001F002L01A01Z01C01.tif …

That is spacr.convert.target_name() verbatim — the exact shape spacr.utils._get_regex('cellvoyager', 'tif') parses — so the output folder is handed straight to Mask/Measure with metadata_type='cellvoyager' and nothing else. No new layout is invented here. The one thing that must survive the trip is the plate geometry, because spaCR keys every measurement, every plot and every well-level statistic off plateID / rowID / columnID / fieldID; well_position() is where OMERO’s 0-based (row, column) becomes spaCR’s ('r1', 'c1') and the well name A01.

Export. export_map_annotation(), export_file_annotation() and export_tag_annotation() push spaCR’s own output back onto the OMERO objects it came from: a key/value MapAnnotation per image or per well (what OMERO.web actually renders), a FileAnnotation for the results CSV or the figure PDF, and a TagAnnotation for a categorical verdict.

Why the logic is not in the adapter¶

Everything that is easy to get wrong here is arithmetic and string formatting, not RPC: the row/column mapping, the filename, the id parsing, the float formatting, the decision to replace rather than append. All of it lives in pure functions over plain data — well_position(), plane_filename(), parse_object_ref(), format_map_value(), measurement_pairs(), plan_annotation() — and the BlitzGateway calls are confined to a thin layer that only walks containers and moves bytes. That is why this module has a real test suite on a machine with no OMERO server and no omero-py installed: the fake gateway in tests/test_omero.py implements about a dozen methods, and everything worth testing is reachable through it.

Every adapter function takes gateway as its first argument. There is no module-level connection and no implicit session — a caller that wants one calls connect(), and a test passes its own object.

The well mapping, stated¶

OMERO’s WellWrapper.getRow() and .getColumn() are 0-based. well_position() adds one and hands the result to spacr.schema.well_id(), which is spaCR’s own definition of a well name. Consequences worth writing down because they are the ones that get fumbled:

row 0 -> A, row 7 -> H (a 96-well plate), row 15 -> P (384).
row 25 -> Z.
row 26 -> AA, not [ (which is what chr(65 + 26) gives) and not an IndexError (which is what string.ascii_uppercase[26] gives). This is bijective base 26, and it is not a hypothetical: a 1536-well plate has 32 rows and runs A..Z, AA..AF. Column 47 -> 48, for the same plate, so nothing here caps the column at 24 either.
the column is zero padded to two digits (A01, never A1) because spaCR’s strict Yokogawa regex is [A-Z]\d{2}.

Sizes and units¶

ImageWrapper.getPixelSizeX() returns a length object with a unit, not a number of micrometres. This module never assumes µm: pixel_size_from() carries the value and the unit symbol together in a PixelSize and writes both into the import sidecar. A pixel size recorded in nm that is read back as µm is a 1000x error in every area in the database and it is silent.

What is written alongside the images¶

Two sidecars, in the destination folder, both of which spaCR itself is happy to ignore:

omero_import.csv: one row per plane: the target filename, the OMERO image id and name, the spaCR keys (plateID/rowID/columnID/fieldID/prc), the channel index and its OMERO name, z/t, the pixel size and its unit, and where the well came from (see well_source below).
omero_import.json: one object per import: server host and port, container kind/id/name, plate token, counts, channel names, pixel size, the spaCR version and a UTC timestamp.

Neither ever contains a password or a session key. That is asserted by a test, along with the fact that OmeroConnection will not print one either.

Not downloading a 100 GB plate to answer “what is in it”¶

inspect_container() reports the image count, the wells, the dimensions and the channel names without ever calling getPlane — a fact the test suite pins by counting calls on the fake gateway. The importers additionally take limit (stop after N OMERO images) and dry_run (build the complete plan, list every filename that would be written, touch no pixels).

Replace or append, and what is never done¶

Annotations are written under a spaCR-owned namespace (NAMESPACE_ROOT), which is what makes a second run able to find its own previous output instead of piling up a fifth copy of the same key/value table.

The default is REPLACE, implemented as update-in-place, and it is the safe option rather than a compromise: an existing MapAnnotation whose namespace is exactly spaCR’s has its value overwritten. Nothing is created, nothing is unlinked, nothing is deleted, and no annotation outside spaCR’s namespaces is so much as read for its value. APPEND is available and explicit for anyone who wants a history of runs on the object.

Three consequences are stated rather than hidden:

This module never deletes anything. There is no call to deleteObjects in it, under any mode, for any object. If a previous APPEND run left three copies, REPLACE updates the oldest and reports the rest in AnnotationResult.duplicates — removing them is a decision for a human with the OMERO.web UI, not for an importer.
FileAnnotations always append. The bytes of an OriginalFile cannot be rewritten in place through the gateway, and the alternative — delete the old attachment — is exactly the destructive behaviour ruled out above. The namespace plus the timestamp in the description identify the newest.
TagAnnotations are never edited. In OMERO a tag is a shared object; renaming the tag linked to this image renames it on every other object in the group that carries it. So export_tag_annotation() links a tag when the verdict is new, does nothing when the identical verdict is already linked, and reports the previous tag when the verdict has changed — it never unlinks and never renames.

Connection settings and secrets¶

connection_settings() reads arguments first and the environment second: OMERO_HOST, OMERO_PORT, OMERO_USER, OMERO_PASSWORD (or OMERO_PASS), OMERO_SESSION_KEY, OMERO_GROUP, OMERO_SECURE. OmeroConnection is frozen and redacts both secrets from repr(), str() and OmeroConnection.redacted(), and no log record in this module carries one.

The optional dependency¶

omero-py is an extra: pip install "spacr[omero]". It is deliberately not part of spacr[all], because it depends on zeroc-ice, a compiled C++ Ice runtime whose wheels lag Python releases and which otherwise needs a C++ toolchain (see the comment beside the extra in setup.py).

So import spacr.omero must work without it, and it does: the import is function-local, behind require_omero(), and a missing install produces one actionable sentence naming pip install "spacr[omero]" rather than a ModuleNotFoundError six frames deep inside Ice’s own import machinery. This follows spacr.qt._QT_MISSING_MESSAGE and spacr.anndata_export.require_anndata().

Two details of that guard are worth knowing:

A missing Ice counts as a missing omero extra. A half-built zeroc-ice is the single most likely way this fails in the field, and No module named 'Ice' mentions neither OMERO nor spaCR. missing_omero_message() says what happened.
This module is called spacr/omero.py and does not shadow the third-party omero package. Absolute imports have been the default since Python 3, so a module inside the spacr package that asks for omero gets the top-level distribution, not its own sibling. That is verified rather than assumed — see tests/test_omero.py::test_spacr_omero_does_not_shadow_the_third_party_package, which puts a decoy omero package on sys.path and checks which one arrives — because a self-import here would be silent and would look like a broken OMERO install.

The import is written as importlib.import_module(OMERO_GATEWAY_MODULE) rather than as a literal import omero.gateway for that same reason: the one place the name is resolved is a named constant next to the guard that checks what came back, instead of a bare statement in a file of the same name. The cost is that tests/test_declared_dependencies_match_imports.py — which reads import statements out of the AST — cannot see it, exactly as it cannot see umap. That blind spot is pinned from the other side by tests/test_omero.py::test_omero_py_is_reached_through_a_string_literal_and_must_not_be_removed, so the next dependency census that reads “omero-py: unused” finds the answer instead of deleting the extra.

Attributes¶

OMERO_MISSING_MESSAGE

Exceptions¶

`OmeroConnectionError`	Connection settings are incomplete, or the server refused the login.
`OmeroContainerError`	The id resolved to nothing, or to a container with nothing usable in it.
`OmeroError`	Base class for every refusal this module makes.
`OmeroExtraMissing`	`omero-py` (or the Ice runtime under it) is not installed.
`OmeroIdError`	An object id could not be read, or names the wrong kind of object.
`OmeroWellError`	A well's row/column indices are not a position on a plate.

Classes¶

`AnnotationPlan`	What an export is about to do, decided before anything is touched.
`AnnotationResult`	What one annotation write did.
`ContainerListing`	The answer to "what is in this container", with no pixels fetched.
`ExportResult`	What a multi-target export did.
`ImageInfo`	What is known about one OMERO image without reading a single pixel.
`ImportResult`	What an import did, or (with `dry_run`) what it would have done.
`OmeroConnection`	Everything needed to open a session, with the secrets kept out of sight.
`OmeroRef`	A parsed reference to one OMERO object.
`PixelSize`	A physical pixel size together with the unit it was recorded in.
`PlanePlan`	One 2-D plane that would be, or was, written.
`WellPosition`	One well, in both vocabularies at once.

Functions¶

`connect`(→ Any)	Open a session and return the connected gateway.
`connection_settings`(→ OmeroConnection)	Build an `OmeroConnection` from arguments, then the environment.
`export_file_annotation`(→ AnnotationResult)	Attach a results CSV or a figure PDF to an OMERO object.
`export_map_annotation`(→ AnnotationResult)	Write spaCR measurements onto an OMERO object as key/value pairs.
`export_plate_summaries`(→ ExportResult)	Write one per-well MapAnnotation per well of an OMERO Plate.
`export_tag_annotation`(→ AnnotationResult)	Attach a categorical verdict — `'hit'`, `'QC fail'` — as a tag.
`format_map_value`(→ str)	Render `value` as the string an OMERO map annotation stores.
`have_omero`(→ bool)	Report whether the `omero` extra can be imported, without raising.
`import_container`(→ ImportResult)	Import a Dataset or a Plate, dispatching on what `ref` says it is.
`import_dataset`(→ ImportResult)	Import an OMERO Dataset into a spaCR source folder.
`import_plate`(→ ImportResult)	Import an OMERO Plate into a spaCR source folder.
`inspect_container`(→ ContainerListing)	Report what a Dataset or Plate contains, without fetching pixels.
`is_missing`(→ bool)	Return whether `value` represents missing annotation data.
`is_spacr_namespace`(→ bool)	Report whether `namespace` is one spaCR owns and may write to.
`list_spacr_annotations`(→ Tuple[Tuple[int, ...)	Return the `(id, namespace)` of every spaCR annotation on `target`.
`measurement_pairs`(→ Tuple[Tuple[str, str], ...])	Project one measurement row onto the key/value pairs OMERO stores.
`missing_omero_message`(→ str)	Return the full "install the extra" text naming `module`.
`omero_indices`(→ Tuple[int, int])	Invert `well_position()`: `'A01'` -> `(0, 0)`.
`parse_object_id`(→ int)	Parse `value` to a positive OMERO id, checking the type it names.
`parse_object_ref`(→ OmeroRef)	Parse an OMERO object reference into a kind and a positive id.
`pixel_size_from`(→ PixelSize)	Read a `PixelSize` out of whatever `getPixelSizeX()` returned.
`plan_annotation`(→ AnnotationPlan)	Decide whether to overwrite spaCR's previous annotation or add one.
`plan_tag`(→ AnnotationPlan)	Decide what to do about a categorical verdict tag.
`plane_filename`(→ str)	Return the Yokogawa filename spaCR expects for one plane.
`plate_token`(→ str)	Reduce `name` to a plate token that survives spaCR's filename regex.
`require_omero`(→ Any)	Import and return `omero.gateway`, or raise a message worth reading.
`summarise_rows`(→ Dict[str, Any])	Reduce many object rows to one per-well summary, in plain Python.
`well_from_image_name`(→ Optional[str])	Recover a well name from an OMERO image name, or return `None`.
`well_position`(→ WellPosition)	Map OMERO's 0-based `(row, column)` onto spaCR's well keys.
`well_summary_pairs`(→ Tuple[Tuple[str, str], ...])	Summarise object rows and project them onto key/value pairs.