From 0bd69caf26a5a2c5981f9475e1acbbc0cb921327 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kai=20M=C3=BChlbauer?= Date: Fri, 2 Aug 2024 13:13:23 +0200 Subject: [PATCH] DOC: Add note to docs on DataTree root-group naming conventions (#9298) * DOC: Add note to docs on DataTree root-group naming conventions (root group name is always "/"). * Update xarray/core/datatree.py * Update xarray/core/datatree.py Co-authored-by: Matt Savoie * Update xarray/core/datatree.py Co-authored-by: Matt Savoie * Update xarray/datatree_/docs/source/io.rst Co-authored-by: Matt Savoie * Update xarray/datatree_/docs/source/io.rst Co-authored-by: Matt Savoie --------- Co-authored-by: Matt Savoie --- xarray/core/datatree.py | 12 +++++++++++- xarray/datatree_/docs/source/io.rst | 11 +++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/xarray/core/datatree.py b/xarray/core/datatree.py index f8a8a5fbc18..6289146308e 100644 --- a/xarray/core/datatree.py +++ b/xarray/core/datatree.py @@ -1551,7 +1551,12 @@ def to_netcdf( ``dask.delayed.Delayed`` object that can be computed later. Currently, ``compute=False`` is not supported. kwargs : - Addional keyword arguments to be passed to ``xarray.Dataset.to_netcdf`` + Additional keyword arguments to be passed to ``xarray.Dataset.to_netcdf`` + + Note + ---- + Due to file format specifications the on-disk root group name + is always ``"/"`` overriding any given ``DataTree`` root node name. """ from xarray.core.datatree_io import _datatree_to_netcdf @@ -1607,6 +1612,11 @@ def to_zarr( supported. kwargs : Additional keyword arguments to be passed to ``xarray.Dataset.to_zarr`` + + Note + ---- + Due to file format specifications the on-disk root group name + is always ``"/"`` overriding any given ``DataTree`` root node name. """ from xarray.core.datatree_io import _datatree_to_zarr diff --git a/xarray/datatree_/docs/source/io.rst b/xarray/datatree_/docs/source/io.rst index 2f2dabf9948..68ab6c18e12 100644 --- a/xarray/datatree_/docs/source/io.rst +++ b/xarray/datatree_/docs/source/io.rst @@ -24,6 +24,12 @@ To open a whole netCDF file as a tree of groups use the :py:func:`open_datatree` To save a DataTree object as a netCDF file containing many groups, use the :py:meth:`DataTree.to_netcdf` method. +.. _netcdf.root_group.note: + +.. note:: + Due to file format specifications the on-disk root group name is always ``"/"``, + overriding any given ``DataTree`` root node name. + .. _netcdf.group.warning: .. warning:: @@ -52,3 +58,8 @@ To save a DataTree object as a zarr store containing many groups, use the :py:me .. note:: Note that perfect round-tripping should always be possible with a zarr store (:ref:`unlike for netCDF files `), as zarr does not support "unused" dimensions. + + For the root group the same restrictions (:ref:`as for netCDF files `) apply. + Due to file format specifications the on-disk root group name is always ``"/"`` + overriding any given ``DataTree`` root node name. +