[ieivanov]

Closes #458.

What

Adds a shards argument to iohub's array-creation API so callers state the shard intent and iohub derives a chunk-aligned geometry. It accepts three forms, following the way TiffConverter already accepts either explicit chunks or a keyword:

Form	Meaning
shards="2GB", "512MiB", "1.5GB", "1048576"	Largest chunk-aligned shard whose nominal (uncompressed) size stays under the target
shards="XY" / shards="XYZ"	One shard per plane / per ZYX volume (any letter order, case-insensitive)
shards=(2, 1, 96, 1792, 1280)	Explicit TCZYX shard shape in elements, rounded up to whole chunks

Available on create_empty_plate, Position.create_zeros / create_image / create_label, and PositionLabel.create_zeros / create_label.

The mantis-v2 example from the issue — shape [T, 6, 86, 1664, 1193], chunks (1, 1, 16, 256, 256), uint16 — no longer needs the hand-computed ceil() arithmetic:

create_empty_plate(..., shards="XYZ")  # -> shards (1, 1, 96, 1792, 1280)
create_empty_plate(..., shards="2GB")  # -> shards (4, 1, 96, 1792, 1280), 1.76 GB

Constraints encoded in the sizer

• C is never grown. A channel-spanning shard cannot be written a channel at a time (process_single_position rejects it), so the channel axis stays at one chunk in every derived form. That footgun is no longer reachable without writing an explicit shape.
• Spatial before time. A byte target fills X, then Y, then Z, and only then spends budget on T, so blast radius grows last. Per the issue discussion T is allowed to grow freely once space is full, which is what makes ~2 GB targets reachable on small volumes.
• Growth is greedy and exact: once an axis is partially filled the remaining budget cannot fit a second multiple of any outer axis, so no better packing exists in this ordering.
• The target is compared against nominal (uncompressed) bytes, so compressed shards land under it. Documented rather than estimated.

shards_ratio

Still works, now emits a DeprecationWarning; passing both shards and shards_ratio raises ValueError. The legacy path keeps its exact chunks * ratio semantics (uncapped), so existing geometries are byte-for-byte unchanged. create_empty_plate's v0.5 default is unchanged, just spelled shards="XYZ" instead of a computed ratio.

Callers to update eventually: biahub's ConcatenateSettings.shards_ratio and the other per-position writers.

Incidental fix

initialize_pyramid derived each level's ratio with floor division over downscaled shards and chunks, which could round a shard axis down to zero chunks (e.g. chunk 3 → 2, shard 3 → 1 → ratio 0) and write an invalid array. It now passes the downscaled shard shape and lets resolution round it back onto the chunk grid.

Tests

• tests/core/test_sharding.py (new, 62 cases): size-string parsing incl. SI vs binary units and garbage; extent keywords, order/case insensitivity, rank guard; byte targets — never exceeded, chunk-aligned, within the array extent, dtype-scaled, C never grown, sub-chunk target falls back to one chunk with a warning; explicit shapes — round-up warning, may exceed the array, validation; deprecation and conflict handling.
• tests/ngff/test_ngff.py: create_zeros with each form, round-up on the real store, v0.4 rejection for all forms, deprecation warning, and sharded pyramid levels staying chunk-aligned.
• tests/ngff/test_ngff_utils.py: create_empty_plate with a size target (the issue's shape), "XYZ" matching the default, explicit shape, and the conflict error.

Full tests/ngff tests/core tests/cli tests/fov run is clean apart from 11 failures that also fail on main (missing local test data / fixtures), verified by re-running them on a stashed tree.

🤖 Generated with Claude Code

Pyramid levels (second commit)

initialize_pyramid / compute_pyramid (images and labels, via the MultiscaleNode of #488) now lay the coarser levels out as:

• Chunks keep the level-0 chunk shape at every level, clamped to the level's shape, so a viewer reads same-sized tiles at every zoom and the coarse levels stay above the DCA level-0 chunk sizes.
• Shards are sized per level by the sizer above. New shards argument, same forms as create_zeros; default None is a size target equal to the level-0 shard's nominal bytes when level 0 is sharded (else unsharded levels). The target fills X, Y, Z first and then T, and never grows C, so shard files keep roughly the level-0 size down the pyramid instead of shrinking eightfold per level (the previous behaviour halved chunks and shards together).

For the mantis-v2 assembled plate above (level-0 shards (5, 1, 96, 1792, 1280) = 4.1 GiB float32), levels 1 and 2 become (40, 1, 48, 896, 640) = 4.1 GiB and (67, 1, 24, 448, 320) = 0.86 GiB (the whole level per channel); the projected plate's (16, 1, 1, 1792, 1280) = 0.14 GiB becomes (64, 1, 1, 896, 640) and (67, 1, 1, 448, 320).

Rebase and merge order

Rebased onto feat/label-pyramid (#488) after main's lazy iohub.core loader (#427), batched create_empty_plate (#479) and label scaffolding (#486): the sharding API is exported through core/__init__.pyi, shards flows into the batched position creation, label images default to shards="XYZ" and create_label_zeros gains shards. process_single_position is untouched. #489 reworks the same label-scaffolding block of create_empty_plate, so: merge #489 and #488 (independent), then rebase this onto main and re-apply the label-scaffolding hunk against #489's _create_missing_labels / create_empty_labels.