deprecate scaler class

[jo-mueller]

Title. Since the scaling functionality is currently scattered across a few places (Scaler class and dask_utils), I discussed with @will-moore that it could be a could thing to deprecate one of them.

In this PR, I

• added a deprecation warning to the Scaler class
• Wrote a separate function to create dask-backed pyramidal images (scale.build_pyramid)
• Replaced the scaler-based functionality everywhere in the writing API.
• Removed deprecated chunks kwarg from write_image, write_labels, write_multiscale_image and write_multiscale_labels

TODOs:

• Make sure tests pass
• Document build_pyramid somewhere or make private
• Replace CLI scaling tool with new functionality

[will-moore]

I see that some of the failing tests are for writing v0.1 - v0.3 of OME-Zarr. I think we could drop support for these and focus on v0.4+. No-one needs to write v0.1-0.3 now. If they do then they can use an older version of ome-zarr-py.

[jo-mueller]

Hi @will-moore thanks again for the feedback. I have refactored the scale test yet a bit more. I figured it would be better to use write_image as an entrypoint to the test, because a lot of the internal wrangling scales to the correct format for _build_pyramid (which is list[dict[str, int]] is happening in there.

For instance, if [2, 4, 8] is passwed as scale factors, that gets coerced to the list of dict in the write_image function, and not in the _build_pyramid function but I think that's an important part of the testing here.

Edit: I think it would have been nice to parse the scale factors in a central place (i.e., inside build_pyramid, but that's essentially what #531 is about.

[jo-mueller]

@will-moore all good points.

I added another test function that passed only different instances of Scaler to the write_image functions. I then check whether the correct amount of layers is produced. I also coerce the passed method of the Scaler class to the respective kind of Method .

I also moved all the deprecation warnings into a single place - them being still there was probably the result of some botched merge conflict.

[will-moore]

Tests look good, thanks. Just the one minor comment above.

In testing this, the only issue that I'd like to re-affirm (discuss again) is the default z-downsampling behaviour. It's a tricky decision which we may want to consult about more widely...

Is 3D downsampling considered "more correct" than 2D downsampling by the community (and our users) in general?
I guess that depends on your point of view - and we certainly have users in both the 2D and 3D camps.

It's a bit less verbose to specify 2D (if the default is 3D) than vice-versa. scale_factors = [{"x": 2, "y":2},...].

Making 3D downsampling the default is more of a breaking change.

#262 is a long-standing request for 3D downsampling, but I guess it doesn't need to be the default.

[jo-mueller]

@will-moore I think my overall stance would be that I would downsample in z by default. When I first used ome-zarr-py it seemed a bit arbitrary why the z-dimension would specifically be excluded from downsampling by default.

But this PR is not about this matter, imho. It only makes it possible to apply equal/custom downsampling along all axes but you still have to make that choice yourself as a user. The reason for this PR is more to consolidate code (with #531 and #527 coming up in the wake of that) to make the repo ready for some bigger architectural changes later on (i.e., RFC5 and #515).

For the sake of going forward I would keep the default as it is (do not downsample in z) and then send a smaller PR that would change the default behavior which can then contain the discussion around #262 that may or may not evolve around it.