Refactor polygon_query()

[LucaMarconato]

Made on top of #409, which should be merged first.

Closes#255.

The PR does the following:

• improved comments
• polygon_query doesn't transform the data but back-transforms the polygon/multipolyon. This is essential for having good performance with multiscale raster data.
• unifies the polygon_query and bounding_box_query APIs. In particular
  • Uses single dispatch for polygon_query()
  • Add sdata.query.polygon_query
• makes the functionality of polygon_query complete
• unifies and adds more tests, in particular:
  • tests polygon_query and bounding_box_query within the same test
  • checks that the results are identical
  • tests 3D bounding boxes with polygons
  • tests multipolygons
  • tests different coordinate systems via affine transformations
  • tests Dask dataframes with multiple partitions.
• bounding_box_query for points now doesn't reset indices
• the transformation of queried elements was passed by reference instead of copy, now fixed

Minor:

• PointsModel.validate() (which is also called by the parser) now checks that no radius value is <= 0. Added also a test for this.

[codecov]

Codecov Report

Attention: 10 lines in your changes are missing coverage. Please review.

Comparison is base (9f188f9) 91.78% compared to head (9db42a8) 92.13%.

Additional details and impacted files

@@ Coverage Diff @@## main #422 +/- ##
==========================================
+ Coverage 91.78% 92.13% +0.34% 
==========================================
Files 37 37 Lines 5052 5073 +21 ==========================================
+ Hits 4637 4674 +37 + Misses 415 399 -16 

Files	Coverage Δ
src/spatialdata/_core/spatialdata.py	93.40% <100.00%> (+0.05%)	⬆️
src/spatialdata/models/models.py	86.36% <88.88%> (+0.14%)	⬆️
src/spatialdata/_core/query/spatial_query.py	95.73% <94.76%> (+2.81%)	⬆️

... and 2 files with indirect coverage changes

[giovp]

small things around documentation

[giovp]

min_coordinate and max_coordinate are with respect to axes right? If so

idx_bb=np.in1d(axes, output_axes_without_c)
idx_out=np.in1d(output_axes_without_c, axes)
min_coordinate=min_coordinate[idx_out]
max_coordinate=max_coordinate[idx_out]

[giovp]

if yes, I would change axes to axes_bb and maybe output_axes_without_c to axes_out_without_x to anyway make them consistent

[giovp]

also, do you need to check (maybe done outside) that min/max coordinate matches in len with some axes (either bb or out)

[LucaMarconato]

min_coordinate and max_coordinate are with respect to axes right? If so

idx_bb = np.in1d(axes, output_axes_without_c)
idx_out = np.in1d(output_axes_without_c, axes)

this still returns a boolean mask, so it's basically equivalent to what I wrote; I'll keep the old code.

min_coordinate = min_coordinate[idx_out]
max_coordinate = max_coordinate[idx_out]

[LucaMarconato]

if yes, I would change axes to axes_bb and maybe output_axes_without_c to axes_out_without_x to anyway make them consistent

good idea, I have renamed these two variables

[LucaMarconato]

yes, we check that it matches with bb, and we do it BoundingBoxRequest.__post_init__()

[kevinyamauchi]

Thanks, @LucaMarconato . I think this looks pretty good. I've left some comments below, mostly related to code clarity.

I am okay with the refactors in test_spatial_query. I see that they likely reduce the amount of code. However, I think this is at the cost of being able to quickly understand the intention of the test. If that's the trade-off we want, I am fine with it. I would add some comments and docstrings to make it easier to understand though.

[kevinyamauchi]

what is the reason for this change? so you don't have to maintain two docstrings? I think it's fine, but I'm curious

[kevinyamauchi]

I see you did the same below for polygon. I would keep in mind that this is going to be a really common way that users interact with the query interface. With this change, I don't think they will have access to the docstring when they are using an IDE (e.g., inspecting sdata.query.polygon()`

[LucaMarconato]

Exactly, I would like to have it only in one place because it's easy to forget to update the other (happened). Is there any Sphinx trick we can use here? Asking also @giovp. For this PR I'll keep it like this because I'd like to merge some other PRs dependent on this.

[LucaMarconato]

I see also torch has something similar to what is in this PR: https://pytorch.org/docs/stable/generated/torch.Tensor.sum.html