Support DataArray objects and nested dicts in DataTree.from_dict

[shoyer]

This PR adds three features to the DataTree.from_dict constructor:

1. It supports DataArray objects and anything that can be coerced into a DataArray via the Dataset constructor.
2. It adds a coords argument for explicitly specifying coordinates.
3. It adds support for nested dictionary values, which are automatically unflattened if nested=True is passed to from_dict().

Explicitly requiring nested=True could potentially be relaxed, now or in the future. The main advantage is that it keeps the core signature simpler (allowing for more type safety), and avoids potential overlap in type signatures with "native" dict format (#9074).

Fixes #9539, #9486

• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst

[eni-awowale]

Thanks for adding this at @shoyer! Do you think it would be worth adding another round trip test for DataArray.from_dict and DataTree.from_dict?

Here is what I did based on DataArray.from_dict

d = {
    "coords": {
        "t": {"dims": "t", "data": [0, 1, 2], "attrs": {"units": "s"}}
    },
    "attrs": {"title": "air temperature"},
    "dims": "t",
    "data": [10, 20, 30],
    "name": "a",
}
da = xr.DataArray.from_dict(d)

dt = xr.DataTree.from_dict({'/a': da}
xr.testing.assert_identical(dt.a, da)

[eni-awowale]

Is this supposed to create a group with the name"/a"? On my end I am just seeing ('/', '/b') and the data variable with the name "a".

[shoyer]

This example was supposed to show creating a variable "a". I've replaced this with something a bit more concrete to illustrate the intended usage.

[shoyer]

Thanks for adding this at @shoyer! Do you think it would be worth adding another round trip test for DataArray.from_dict and DataTree.from_dict?

So unfortunately this doesn't work. The issue is that DataTree.from_dict works fundamentally different from Dataset.from_dict and DataArray.from_dict: #9074

• Dataset.from_dict and DataArray.from_dict parse "pure" Python dictionaries in the form you show above (e.g., {"coords": ..., "data": ..., "dims": ...})
• In contrast, DataArray.from_dict expects xarray data structures in values.

I'm not sure it makes sense to combine both in a single function. In particular, there is some ambiguity about whether dict value should be flattened (which I've added here), e.g., does {"foo": {"data": 1}} mean a DataArray at /foo/data or at /foo?

Instead, I think we should have a dedicated methods to_pure_dict()/from_pure_dict() or add pure keyword argument for controlling the output argument. Ideally we would make this consistent across DataTree/Dataset/DataArray, too. Given that pure dictionaries are relatively niche compared to this alternate constructor, I would lean towards renaming the Dataset/DataArray methods.

[shoyer]

I've changed DataTree.from_dict() to require explicitly passing nested=True to unflatten nested items. This is easily discoverable, type-checkable and avoids precluding the possiblity of passing "pure" dictionary arguments like {"coords": ..., "data": ..., "dims": ...}.

[shoyer]

@TomNicholas any thoughts?

[etienneschalk]

Some general comments and questions out of curiosity

[shoyer]

@TomNicholas I would really appreciate your feedback on the API here, even just the docstring for DataTree.from_dict(). I am pretty happy with the implementation and that's had a few looks now, but I don't want to merge this until you're comfortable with the end-user API -- that's harder to fix later!

[shoyer]

Last call for review here!

[eni-awowale]

I like the addition of the nested flag and the dt2 example!