DataTree requirements

[melonora]

It is stated in the documentation that with the newest Xarray release, for DataTree the dimensions and indices need to be aligned across parents / children in the DataTree. However, in multiscale-spatial-image we end up having a DataTree with a root node not having any dimensions, while the children do. Is this intended behaviour or should this be considered as a bug?

In case of a bug, MultiscaleSpatialImage is depending on it right now and with that also SpatialData.

[keewis]

can you give an example of what you get vs. what you'd expect? Just from the description alone I don't quite understand what is wrong. Edit: given the example in the readme of multiscale-spatial-image I assume the question is answered below.

Or is it that you have an image pyramid (the same image at different resolutions / pixel size), currently put them as siblings and would like to verify whether that is supported behavior? If so: yes, the restriction only applies to parent-child relationships, siblings are intentionally not included in that rule. So while the parent node must align with its children, siblings don't have to:

root = xr.Dataset(coords={"x": range(10)})

group1 = xr.Dataset(coords={"x": range(5)})
group2 = xr.Dataset(coords={"x": range(10)})

xr.DataTree.from_dict({"/": root1, "/group1": group1})  # parent conflicts with a child, error
xr.DataTree.from_dict({"/": root1, "/group/subgroup": group1})  # parent conflicts with a descendant, error
xr.DataTree.from_dict({"/": root1, "/group": group2})  # no conflicts, allowed

xr.DataTree.from_dict({"/group1": group1, "/group2": group2})  # empty parent, allowed
xr.DataTree.from_dict({"/": root, "/group1": group1, "/group2": group2})  # parent conflicts with a child, error

[melonora]

<xarray.DataTree>
Group: / # you see that the root node does not contain dims etc. See comment below the code block.
├── Group: /scale0
│       Dimensions:  (y: 128, x: 128)
│       Coordinates:
│         * y        (y) float64 1kB 0.0 1.0 2.0 3.0 4.0 ... 124.0 125.0 126.0 127.0
│         * x        (x) float64 1kB 0.0 1.0 2.0 3.0 4.0 ... 124.0 125.0 126.0 127.0
│       Data variables:
│           image    (y, x) uint8 16kB dask.array<chunksize=(128, 128), meta=np.ndarray>
├── Group: /scale1
│       Dimensions:  (y: 64, x: 64)
│       Coordinates:
│         * y        (y) float64 512B 0.5 2.5 4.5 6.5 8.5 ... 120.5 122.5 124.5 126.5
│         * x        (x) float64 512B 0.5 2.5 4.5 6.5 8.5 ... 120.5 122.5 124.5 126.5
│       Data variables:
│           image    (y, x) uint8 4kB dask.array<chunksize=(64, 64), meta=np.ndarray>
└── Group: /scale2
        Dimensions:  (y: 16, x: 16)
        Coordinates:
          * y        (y) float64 128B 3.5 11.5 19.5 27.5 35.5 ... 99.5 107.5 115.5 123.5
          * x        (x) float64 128B 3.5 11.5 19.5 27.5 35.5 ... 99.5 107.5 115.5 123.5
        Data variables:
            image    (y, x) uint8 256B dask.array<chunksize=(16, 16), meta=np.ndarray>

From my understanding we have a DataTree here that does not have the dimensions etc aligned with the siblings which are the different scales, because the root node does not have dimensions. We indeed have the scales as siblings for the reason of not requiring the alignment. If this is not a bug and is thus intended behaviour then I guess there is a bit of confusion of what is really meant with alignment of dimensions and indices.

[keewis]

If you have a suggestion on how to make the documentation clearer, we're happy to take a PR!

cc @TomNicholas and @shoyer

[melonora]

ok I will open one later:)

[TomNicholas]

The text here tries to make it clear that the requirement is for alignment between parents and children - alignment between siblings is not required. If you don't think that's clear from this page, or you didn't find that page because of poor advertising of it, please help us improve it :)

https://docs.xarray.dev/en/stable/user-guide/hierarchical-data.html#alignment-and-coordinate-inheritance