[guijacquemet]

@IvanHCenalmor, could you review this? Please merge it yourself if you're happy with it; we won't merge it. Once it is merged, could you tag a release? MorphoRelate will pin to that tag, and MorphoRelate 1.0 needs one.

Every finding from an independent adversarial review is fixed below. Each fix has a test that fails without it.

Why

MorphoRelate's milestone M3 ("Easy input": morphorelate init, inspect reading headers, a "your data" notebook, OME-Zarr input) makes this package a core dependency, pinned by commit until it has a tag (owner, 2026-10-26). It reuses this package's discovery, header reading, physical sizes, OME-Zarr reading and notebook steps.

Changes

• discovery: a lowercase folder named single is read as that level's value single (the MorphoBricks one-member level, as in <condition>/single/<images>), when it is the only folder in its place. Two cases stay reserved_folder_name:
  • Single or SINGLE;
  • a single folder beside other folders.
• physical_sizes (new module; PhysicalSizes and read_physical_sizes moved here and stay importable from zarr_export and the package):
  • Each space axis has its own unit: x_unit, y_unit, z_unit. None means space_unit; unit(role) resolves it.
  • Equality and hash compare the resolved units, so dataclasses.replace and old pickles stay consistent.
  • OME PhysicalSizeYUnit and PhysicalSizeZUnit are honoured.
  • ImageJ yunit and zunit are honoured, including the escaped micro sign µ.
  • Ångström is recognised.
  • Booleans are not sizes.
• metadata: inspect_image / TiffMetadata gains physical_sizes, for TIFF and OME-Zarr images, read from the header that is already open. Existing fields are unchanged.
• zarr_input: NgffImage.physical_sizes is the NGFF level-0 coordinateTransformations scale times the multiscale-level scale (0.4 and 0.5). Axis units are normalised to UDUNITS-2 names.
  • Malformed, file-stored or wrong-length scales give no sizes.
  • Errors are logged and never make an image unreadable.
  • A scale too large for a float gives no size for that axis.
  • A unitless scale is kept, with unit None.
• zarr_export / run:
  • Copies write each axis's own unit.
  • Copies an earlier version wrote with other axis units are converted again once, on the next run. The table does not change.
• notebook_ui:
  • folder_step and axis_step take optional title, purpose, intro and show_next.
  • folder_step takes show_output: the output card is hidden, and comes back when the check reports output_inside_experiment.
  • The defaults are unchanged.

Behaviour changes for review

• OME-TIFF Y and Z units now follow the OME schema. A file that sets only PhysicalSizeXUnit="nm" used to report Y (and Z) in nanometres. They now default to micrometres, as the schema says: a silent 1000× change in Y and Z for such files. It is deliberate and documented (plan §12 Q22). Z behaves the same way when only X and Y carry units.
• Copies of such images are converted again once, on the next run. The rows are identical; the run reports these images as converted.
• A lowercase single folder that is the only folder in its place is no longer an error.
• PhysicalSizes(space_unit=..., x_unit=...) with differing values no longer raises: x_unit wins.

Decisions

Recorded as plan §12 questions 21–24. Contract §1, §2, §8 and §10, the user guide and AGENTS.md are updated. The CSV, the manifest and their versions are unchanged.

Notes for review

• Left as they are, on purpose:
  • Single beside single gives two errors, reserved_folder_name and case_conflict.
  • An empty folder beside single blocks the run.
  • The long-s spelling of single is not handled.
• single was reserved by the initial plan, with no recorded reason. The two cases that still give an error keep single unambiguous.
• The notebook changes were tested headless and rendered with embed_minimal_html. They were not checked in a browser or JupyterLab.
• No version bump and no tag.

Tests (head cf4ef21)

• Python 3.11 + zarr 2.18.7: 806 passed, 18 skipped. The skips are NGFF 0.5 cases that need zarr 3, and one permissions case.
• Python 3.13 + zarr 3.4.1: 823 passed, 1 skipped.
• ruff check .: all checks passed. ruff format --check .: 55 files already formatted.

🤖 Generated with Claude Code

https://claude.ai/code/session_017TP44aBCGzyksTpPS2FFmQ

[IvanHCenalmor]

I merged main into this branch (commit 0894b59) to resolve the conflicts with follow-ups P2 (dataset consistency warnings) and P3 (experiment design). This PR's decisions are kept:

• Physical sizes: physical_sizes.py, with a unit per axis, is now the only home of PhysicalSizes.
  • P2 had moved the same code into a pixel_sizes.py. That module is removed; it was never released.
  • Its micrometers() helper, which the folder check uses to compare pixel sizes, is now a method of PhysicalSizes and uses each axis's own unit.
• OME-Zarr sizes: TiffMetadata and NgffImage get physical_sizes the way this PR reads them. A unitless OME-Zarr scale is kept, with no unit, so the folder check reports it as missing_pixel_size.
• Notebook step 1: it keeps P2's "Dataset consistency" panel and this PR's hidden output card, which comes back for output_inside_experiment.
• Embedded steps: they keep the same gating, so they now also ask P3's biological-repeat confirmation. The two embedding tests answer those questions.
• Plan numbering: questions 21–22 in docs/plan.md §12 are now P2 and P3, so this PR's questions 21–24 are now 23–26. All references in the docs and code are updated; the description above still uses the old numbers. The OME unit change ("Q22" above) is now question 24.

Locally on Windows (Python 3.12, zarr 3.4.1, with the notebook extras), ruff check and ruff format --check are clean, and pytest gives 883 passed, 2 skipped.

🤖 Generated with Claude Code