From 64b1d84dfb012e91f81f0087bc2d8474ad6a6d44 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kai=20M=C3=BChlbauer?= Date: Wed, 31 Jul 2024 09:00:16 +0200 Subject: [PATCH 1/6] DOC: Add note to docs on DataTree root-group naming conventions (root group name is always "/"). --- xarray/core/datatree.py | 10 +++++++++- xarray/datatree_/docs/source/io.rst | 11 +++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/xarray/core/datatree.py b/xarray/core/datatree.py index 65ff8667cb7..4b059107555 100644 --- a/xarray/core/datatree.py +++ b/xarray/core/datatree.py @@ -1546,7 +1546,11 @@ 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`` + Additonal 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 @@ -1602,6 +1606,10 @@ 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..614d8971ce6 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. + From d1b29cb83497a96b10deb675e81767fadc80f9bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kai=20M=C3=BChlbauer?= Date: Wed, 31 Jul 2024 09:04:10 +0200 Subject: [PATCH 2/6] Update xarray/core/datatree.py --- xarray/core/datatree.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xarray/core/datatree.py b/xarray/core/datatree.py index 4b059107555..01160ee3458 100644 --- a/xarray/core/datatree.py +++ b/xarray/core/datatree.py @@ -1546,7 +1546,7 @@ def to_netcdf( ``dask.delayed.Delayed`` object that can be computed later. Currently, ``compute=False`` is not supported. kwargs : - Additonal 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 From 31199e6988bd9e3153647bc8da6e40c3f5a4256f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kai=20M=C3=BChlbauer?= Date: Thu, 1 Aug 2024 07:49:26 +0200 Subject: [PATCH 3/6] Update xarray/core/datatree.py Co-authored-by: Matt Savoie --- xarray/core/datatree.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/xarray/core/datatree.py b/xarray/core/datatree.py index 01160ee3458..10ea008b371 100644 --- a/xarray/core/datatree.py +++ b/xarray/core/datatree.py @@ -1548,9 +1548,10 @@ def to_netcdf( kwargs : Additional keyword arguments to be passed to ``xarray.Dataset.to_netcdf`` - .. note:: + Note + ---- Due to file format specifications the on-disk root group name - is always `/` overriding any given ``DataTree`` root node name. + is always ``"/"`` overriding any given ``DataTree`` root node name. """ from xarray.core.datatree_io import _datatree_to_netcdf From a297c9e9acc76be524977b7e8a0eb772491168a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kai=20M=C3=BChlbauer?= Date: Thu, 1 Aug 2024 07:49:38 +0200 Subject: [PATCH 4/6] Update xarray/core/datatree.py Co-authored-by: Matt Savoie --- xarray/core/datatree.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/xarray/core/datatree.py b/xarray/core/datatree.py index 10ea008b371..156f167d05f 100644 --- a/xarray/core/datatree.py +++ b/xarray/core/datatree.py @@ -1608,9 +1608,10 @@ def to_zarr( kwargs : Additional keyword arguments to be passed to ``xarray.Dataset.to_zarr`` - .. note:: + Note + ---- Due to file format specifications the on-disk root group name - is always `/` overriding any given ``DataTree`` root node name. + is always ``"/"`` overriding any given ``DataTree`` root node name. """ from xarray.core.datatree_io import _datatree_to_zarr From e68e470b04e2f0c9bdc1b3f4ff88ad27d0fe625c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kai=20M=C3=BChlbauer?= Date: Thu, 1 Aug 2024 07:49:47 +0200 Subject: [PATCH 5/6] Update xarray/datatree_/docs/source/io.rst Co-authored-by: Matt Savoie --- xarray/datatree_/docs/source/io.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xarray/datatree_/docs/source/io.rst b/xarray/datatree_/docs/source/io.rst index 614d8971ce6..7bf478fc7b4 100644 --- a/xarray/datatree_/docs/source/io.rst +++ b/xarray/datatree_/docs/source/io.rst @@ -60,6 +60,6 @@ To save a DataTree object as a zarr store containing many groups, use the :py:me 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 `/` + Due to file format specifications the on-disk root group name is always ``"/"`` overriding any given ``DataTree`` root node name. From fa32e0a1ef6ce15d0a786d1c22b2d8e3851aa78a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kai=20M=C3=BChlbauer?= Date: Thu, 1 Aug 2024 07:49:55 +0200 Subject: [PATCH 6/6] Update xarray/datatree_/docs/source/io.rst Co-authored-by: Matt Savoie --- xarray/datatree_/docs/source/io.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xarray/datatree_/docs/source/io.rst b/xarray/datatree_/docs/source/io.rst index 7bf478fc7b4..68ab6c18e12 100644 --- a/xarray/datatree_/docs/source/io.rst +++ b/xarray/datatree_/docs/source/io.rst @@ -27,7 +27,7 @@ To save a DataTree object as a netCDF file containing many groups, use the :py:m .. _netcdf.root_group.note: .. note:: - Due to file format specifications the on-disk root group name is always `/`, + Due to file format specifications the on-disk root group name is always ``"/"``, overriding any given ``DataTree`` root node name. .. _netcdf.group.warning: