[ieivanov]

Related issue

Supports Biohub/biahub#360 (DCA v0.2 compliance, Biohub/biahub#363).

Builds on #485 (merged): the labels list on the labels group is what this PR's scaffolded labels rely on. The branch has been updated from main.

Summary

Adds label scaffolding to iohub.ngff.utils.create_empty_plate:

label_names: list[str] | None = None
label_dtype: DTypeLike = np.uint32
label_chunks: tuple[int, ...] | None = None        # TZYX
label_shards_ratio: tuple[int, ...] | None = None  # TZYX

For every position in position_keys it creates an empty multiscale label image <fov>/labels/<name>/ that mirrors the image pyramid, one TZYX level per image level with the same path:

• shape, scale and translation of each level come from the position's image level minus the channel axis. For a new position that is the plate shape/scale minus C. For an existing position they are read from its image, so the label always lines up with the image, including existing pyramids;
• image-label metadata with source.image = "../../", and the labels list on the labels group;
• chunks/shards default to the same version defaults the image uses, computed per position and level from that image level's shape (and version), at label_dtype and without the channel axis: _default_chunks(image_shape, label_dtype, version), and for v0.5 _default_shards_ratio over the label chunks (one shard per time chunk, spanning ZYX). v0.4 caps the Z chunk to 500 MB at label_dtype and never shards, as for images. Explicit image chunks/shards_ratio are not inherited: they describe the image. Deriving the default shards from the label chunks also means a caller who passes only label_chunks gets shards that fit them, rather than the image's ratio, which was sized for the image chunks;
• only metadata is written (fill value 0). Fill a label later with pos.get_label(name)["0"][...] = data.

On an existing plate it only creates labels that are missing. Existing image arrays and existing labels are left untouched, so a second call is a no-op. It works when every channel_names entry already exists, and alongside extra_metadata/metadata_sources.

The per-label work goes through a new Position.create_label_zeros (the label counterpart of Position.create_zeros) and runs inside the per-position thread pool of the batched path from #479. Rough timing for 500 positions (1×2×16×256×256): 2.8 s without labels, 12.9 s with 2 labels per position; a rerun takes 0.3 s without labels and 1.6 s with them.

Testing

New tests in tests/ngff/test_ngff_utils.py:

• test_create_empty_plate_with_labels[0.4|0.5]: new plate. Checks labels group content, shape/dtype/chunks/shards/axes/scale, image-label source, zero fill, get_label(name) reads and ["0"][...] = arr writes and reads back.
• test_create_empty_plate_labels_explicit_layout: label_dtype/label_chunks/label_shards_ratio are used as given.
• test_create_empty_plate_label_shards_follow_label_chunks: with only label_chunks given, the default shard spans the whole ZYX of the label chunks. It fails on the previous revision, which reused the image's ratio.
• test_create_empty_plate_labels_ignore_explicit_image_layout[0.4|0.5]: explicit image chunks/shards_ratio are not inherited by default labels.
• test_create_empty_plate_label_defaults_follow_each_position_shape: a position created by an earlier call with another shape gets label chunks and shards sized for its own image, not the call's shape.
• test_create_empty_plate_labels_refuse_path_backed_transforms: an image with a transform stored at path gets a ValueError and no label. Such a transform can't have its channel component removed, and a relative path wouldn't resolve from labels/<name>; iohub never writes them.
• test_create_empty_plate_appends_labels_to_existing_plate[0.4|0.5]: existing plate with image data, an existing label and a translated transform. Existing channels are passed again, together with extra_metadata and one new position. Image data and the existing label are preserved, the missing label is added everywhere, and the translation carries over.
• test_create_empty_plate_labels_second_call_is_noop[0.4|0.5]: no byte under labels/ changes on a rerun.
• test_create_empty_plate_labels_mirror_image_pyramid[0.4|0.5]: a label added to an image with 3 pyramid levels gets the same 3 levels, with each level's shape, scale and default layout taken from the matching image level.
• test_create_empty_plate_labels_pyramid_clamps_explicit_chunks: explicit label_chunks are clamped to the shape of each level, and the default shards follow.
• test_create_empty_plate_label_layout_requires_label_names: label_dtype/label_chunks/label_shards_ratio without label_names raise instead of being silently ignored.
• test_create_empty_plate_label_argument_refusals: a non-integer dtype, a non-TZYX chunks/shards argument, or label_shards_ratio with version "0.4" fails before anything is written.

uv run pytest tests/ngff -q: 231 passed, 1 skipped, 2 failed. The 2 failures (test_apply_transform_to_{czyx,tczyx}_and_save, a hypothesis example with C-chunk 2 over 3 channels) fail the same way on main, so this PR does not cause them.

Also checked by hand with ome-zarr-models: a scaffolded position opens as Image with Labels, and the plate opens as HCS.

Checklist

• I added or updated tests, or this change does not require tests.
• I updated the documentation, or this change does not require documentation.
• I confirmed this change does not include confidential or sensitive information.

Used by Biohub/biahub#413, which pins this branch.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Labels omit whole-position transforms, causing misalignment with images that use them.

1 open finding

• Preserve whole-position transforms when adding labels · New

What changed in this PR

Adds empty NGFF label-image scaffolding to plate creation.

Changes:

• Adds configurable label dtype, chunking, and sharding.
• Adds Position.create_label_zeros.
• Tests creation, layouts, existing plates, and idempotency.

File	Description
src/​iohub/​ngff/​utils.py	Integrates label scaffolding into plate creation.
src/​iohub/​ngff/​nodes.py	Adds zero-filled label creation API.
tests/​ngff/​test_ngff_utils.py	Covers label scaffolding behavior.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

Layout defaults can use the wrong position shape, and invalid sharding can leave unrecoverable partial label groups.

0 open findings

1 resolved since last review

• Preserve whole-position transforms when adding labels

Previously missed (3)

In code that hasn't changed since last review

Validate label chunks and shards before group creation

src/​iohub/​ngff/​nodes.py:2024

Validate chunks/shards_ratio before creating the label group. A direct call with a dimensionality mismatch, or any non-None shard ratio on v0.4, currently creates labels/<name> first and then raises in _create_zarr_array; the dangling group is reported by label_names() and prevents a clean retry. Moving these deterministic checks ahead of create_labels_group() avoids corrupting the position on invalid input.

Reject v0.4 label shard ratios before writing

src/​iohub/​ngff/​utils.py:338

Reject an explicit label_shards_ratio for version 0.4 during this preflight. A valid four-element ratio currently passes here; workers then create the image and labels/<name> group before _create_zarr_array rejects sharding for Zarr v2. This leaves a partial store, and a retry skips the empty label group because its name already exists, contrary to the fail-before-write behavior of label argument validation.

Compute label defaults from each position's shape

src/​iohub/​ngff/​utils.py:345

These defaults are bound to the call's shape, but _create_missing_labels deliberately derives each existing label's shape from that position's level 0. If an existing position has different dimensions (which this API otherwise supports), its v0.5 chunks are clamped and its default shard ratio is calculated against the wrong volume, so the promised one-shard-per-T ZYX layout is not produced (and the v0.4 chunk cap is likewise based on the wrong shape). Keep only explicit layout arguments shared, and compute missing defaults from each position's image_shape/label_shape inside _create_missing_labels.

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Default label layouts are incorrectly reused for existing positions whose image shape differs from the call’s shape.

1 open finding

• Recompute omitted label layout defaults per position shape · New

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

OME-Zarr 0.4 sharding input fails only after partially creating the output store.

1 open finding

• Reject label sharding for OME-Zarr 0.4 before store creation · New

1 resolved since last review

• Recompute omitted label layout defaults per position shape

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Path-backed transformations can produce incorrectly aligned label metadata.

1 open finding

• Path-backed transforms are copied without axis adjustment · New

1 resolved since last review

• Reject label sharding for OME-Zarr 0.4 before store creation

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Existing-store version handling and transform composition can produce broken or misaligned labels.

1 open finding

• Preserve dataset-before-multiscale transform ordering for labels · New

1 resolved since last review

• Path-backed transforms are copied without axis adjustment

Previously missed (1)

In code that hasn't changed since last review

Validate label shards against the opened store's actual NGFF version

src/​iohub/​ngff/​utils.py:341

For an existing store, open_ome_zarr infers the actual NGFF version from metadata, but this check uses the caller's version before the store is opened. Calling the documented existing-plate path on a v0.4 plate with the default version="0.5" therefore accepts an explicit label shard ratio; creation then fails only after labels/<name> has been created, and the leftover group is subsequently treated as an existing label and skipped. Validate against each opened position/store's actual version before creating any label group (and do not reject shards for an existing v0.5 store merely because the caller passed version="0.4").

🧠 Review effort: Balanced

[srivarra]

Besides the comments left by copilot, I have just one additional comment.

[srivarra]

Do we still want to support shards_ratio here if #461 is going to deprecate it anyways?

[ieivanov]

For now let's keep shards_ratio since are are still using it. We can deprecate it once I get around to #461 😆

[srivarra]

yee sounds good!