diff --git a/docs/source/index.rst b/docs/source/index.rst index f3e12e09..0f28aa60 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,6 +12,7 @@ Datatree Quick Overview Tutorial Data Model + Reading and Writing Files API Reference How do I ... Contributing Guide diff --git a/docs/source/io.rst b/docs/source/io.rst new file mode 100644 index 00000000..be43f851 --- /dev/null +++ b/docs/source/io.rst @@ -0,0 +1,52 @@ +.. _data structures: + +Reading and Writing Files +========================= + +.. note:: + + This page builds on the information given in xarray's main page on + `reading and writing files `_, + so it is suggested that you are familiar with those first. + + +netCDF +------ + +Groups +~~~~~~ + +Whilst netCDF groups can only be loaded individually as Dataset objects, a whole file of many nested groups can be loaded +as a single ``:py:class::DataTree`` object. +To open a whole netCDF file as a tree of groups use the ``:py:func::open_datatree()`` function. +To save a DataTree object as a netCDF file containing many groups, use the ``:py:meth::DataTree.to_netcdf()`` method. + + +.. _netcdf.group.warning: + +.. warning:: + ``DataTree`` objects do not follow the exact same data model as netCDF files, which means that perfect round-tripping + is not always possible. + + In particular in the netCDF data model dimensions are entities that can exist regardless of whether any variable possesses them. + This is in contrast to `xarray's data model `_ + (and hence :ref:`datatree's data model`) in which the dimensions of a (Dataset/Tree) + object are simply the set of dimensions present across all variables in that dataset. + + This means that if a netCDF file contains dimensions but no variables which possess those dimensions, + these dimensions will not be present when that file is opened as a DataTree object. + Saving this DataTree object to file will therefore not preserve these "unused" dimensions. + +Zarr +---- + +Groups +~~~~~~ + +Nested groups in zarr stores can be represented by loading the store as a ``:py:class::DataTree`` object, similarly to netCDF. +To open a whole zarr store as a tree of groups use the ``:py:func::open_datatree()`` function. +To save a DataTree object as a zarr store containing many groups, use the ``:py:meth::DataTree.to_zarr()`` method. + +.. 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. diff --git a/docs/source/whats-new.rst b/docs/source/whats-new.rst index daee3fd8..f79d9834 100644 --- a/docs/source/whats-new.rst +++ b/docs/source/whats-new.rst @@ -40,6 +40,9 @@ Bug fixes Documentation ~~~~~~~~~~~~~ +- Added ``Reading and Writing Files`` page. (:pull:`158`) + By `Tom Nicholas `_. + Internal Changes ~~~~~~~~~~~~~~~~