Validate axes for writer

[will-moore]

Fixes #122

This uses @constantinpape code from https://github.com/ome/ome-ngff-prototypes/blob/05b55d2516941e2eaf8fa82b722cad4371f99b5f/single_image/prototypes/v03.py#L19 to validate axes.

Also adds the required dimension order to the docstring for write_image() and write_multiscale()

cc @k-dominik

To test, try the code sample below: #123 (comment) as it is, and with various shapes and valid/invalid axes. (invalid axes are not in the tczyx order, e.g. xyz. This should throw an AssertionError).
NB: This previously failed to scale with unhelpful error message (since the sizeX is 1), but error should now be improved.

[codecov]

Codecov Report

Merging #123 (af4f882) into master (bf9b3d2) will increase coverage by 0.93%.
The diff coverage is 91.66%.

@@            Coverage Diff             @@
##           master     #123      +/-   ##
==========================================
+ Coverage   70.10%   71.04%   +0.93%     
==========================================
  Files          11       11              
  Lines        1104     1126      +22     
==========================================
+ Hits          774      800      +26     
+ Misses        330      326       -4     

Impacted Files	Coverage Δ
ome_zarr/writer.py	93.24% <91.66%> (+10.55%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update bf9b3d2...af4f882. Read the comment docs.

[k-dominik]

Hello @will-moore,

that was quick, thank you for having a look!
I of course ignored the example you're linking to, and tried the same thing as yesterday:

from ome_zarr.writer import write_image
import numpy
import zarr


store = zarr.DirectoryStore("/tmp/blah.zarr")
img_group = zarr.group(store=store)
img = numpy.zeros((123, 456, 1), dtype="uint8")

# now knowing that this axisorder is not supported
# I'd still expect a meaningful Exception here...
# not LinAlgError: SVD did not converge
write_image(img, img_group, axes="yxc")

while naive, I think this looks like a totally innocent usage of the library.

Adding the note in the documentation is of course an improvement that could potentially save some users of the library of running into the same problem.

[will-moore]

@k-dominik Thanks for testing.
The issue there is that the scaling is trying to down-sample the xy dimensions (last 2 dimensions), and y is size of 1 in your image. This fails before the check on valid axes.
I probably just need to do the axes validation in write_image() before the scaling...

[will-moore]

@k-dominik I pushed a fix where I test for size_x or size_y being 1 before scaling.
Your example code now fails with:

ValueError: Can't downsample if size of x or y dimension is 1. Shape: (123, 456, 1)

[sbesson]

A few minor suggestions mostly revolving around providing user feedback otherwise I think this is a useful feature as it isolate the axes metadata validation and adds some coverage of the various scenarios.

@k-dominik do you also want to have a look and confirm this addresses #122 ?

In terms of releases, this effectively adds a new public API so that would be 0.3.0 or should we make the validation API internal for now with a leading underscore and call this 0.2.1?

[will-moore]

@sbesson fixes pushed, except for validate_axes_names() not renamed

[k-dominik]

Hello @will-moore and @sbesson,

thank you guys so much for looking into it. I checked out the latest changes and now if I come with my little badly ordered array I get

ValueError: Can't downsample if size of x or y dimension is 1. Shape: (1344, 1024, 1)

Disclaimer: I know I'm doing it wrong :) I don't expect it to work. What I would prefer though, would be a more informative error message.

I guess the point I would like to mention here is that imo, if the downsampling operation assumes a certain order, then one should make sure that the array is in the right axisorder. And a function to do this is there: _validate_axes_names, there are the error messages that I would like to see :)

[will-moore]

@k-dominik OK, I included the axes validation before scaling which will give the nicer error.

[joshmoore]

Barring feedback from @k-dominik, is this waiting on anything?

[will-moore]

No, I think it's good to go

[k-dominik]

Awesome, I really like the early failing with a super helpful error message! thx a lot!

[sbesson]

Thanks @k-dominik and @will-moore