DOC Add DataTree.dataset setter documentation

doc/user-guide/data-structures.rst

@@ -558,7 +558,8 @@ specifying the nodes' relationship to one another as you create each one.
 The :py:class:`~xarray.DataTree` constructor takes:
 
 - ``dataset``: The data that will be stored in this node, represented by a single
-  :py:class:`xarray.Dataset`, or a named :py:class:`xarray.DataArray`.
+  :py:class:`xarray.Dataset`, or a named :py:class:`xarray.DataArray`. The dataset
+  can be set by the user directly.
 - ``children``: The various child nodes (if there are any), given as a mapping
   from string keys to :py:class:`~xarray.DataTree` objects.
 - ``name``: A string to use as the name of this node.
@@ -571,6 +572,16 @@ Let's make a single datatree node with some example data in it:
     dt = xr.DataTree(name="root", dataset=ds1)
     dt
 
+We can set the dataset of the DataTree object.
+
+.. ipython:: python
+
+    ds2 = xr.Dataset({"foo": "apple"})
+    dt.dataset = ds2
+    dt
+    # reset the dataset
+    dt.dataset = ds1
+
 At this point we have created a single node datatree with no parent and no children.
 
 .. ipython:: python
@@ -628,7 +639,6 @@ For data files with groups that do not not align see
 more information about coordinate alignment see :ref:`datatree-inheritance`
 
 
-
 DataTree Contents
 ~~~~~~~~~~~~~~~~~
 

doc/user-guide/hierarchical-data.rst

@@ -458,6 +458,24 @@ have children (i.e. Abe and Homer).
 
     simpsons.is_hollow
 
+Dataset
+~~~~~~~
+
+The data stored in each node of a tree is stored in a :py:class:`~xarray.Dataset` object.
+This is a dictionary-like object that stores data variables and coordinates.
+One can access the dataset stored in a node using the :py:class:`~xarray.DataTree.dataset` property:
+
+.. ipython:: python
+
+    simpsons["Homer"].dataset
+
+Similarly, one can overwrite the dataset stored in a node using the :py:class:`~xarray.DataTree.dataset` property:
+
+.. ipython:: python
+
+    simpsons["Homer"].dataset = xr.Dataset({"age": 40})
+
+
 .. _tree computation:
 
 Computation

xarray/core/datatree.py

@@ -607,6 +607,10 @@ def dataset(self) -> DatasetView:
         For a mutable Dataset containing the same data as in this node, use
         `.to_dataset()` instead.
 
+        Though the dataset is immutable, it is possible to assign a new dataset
+        to this node, which will replace the existing data. One can use
+        `.dataset = new_dataset` to do this.
+
         See Also
         --------
         DataTree.to_dataset