From 50df616693091c4ec74017683aa26dac7cfbc173 Mon Sep 17 00:00:00 2001 From: Thomas Nicholas Date: Thu, 5 Jan 2023 11:22:07 -0500 Subject: [PATCH 1/2] Joe's suggestions for index page --- docs/source/index.rst | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index e0e39de7..9fd21c95 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,6 +3,38 @@ Datatree **Datatree is a prototype implementation of a tree-like hierarchical data structure for xarray.** +Why Datatree? +~~~~~~~~~~~~~ + +Datatree was born after the xarray team recognised a `need for a new hierarchical data structure `_, +that was more flexible than a single :py:class:`xarray.Dataset` object. +The initial motivation was to represent netCDF files / Zarr stores with multiple nested groups in a single in-memory object, +but :py:class:`~datatree.DataTree` objects have many other uses. + +You might want to use datatree for: + +- Organising many related datasets, e.g. results of the same experiment with different parameters, or simulations of the same system using different models, +- Analysing similar data at multiple resolutions simultaneously, such as when doing a convergence study, +- Comparing heterogenous but related data, such as experimental and theoretical data, +- I/O with nested data formats such as netCDF / Zarr groups. + +Development Roadmap +~~~~~~~~~~~~~~~~~~~ + +Datatree currently lives in a separate repository to the main xarray package. +This allows the datatree developers to make changes to it, experiment, and improve it faster. + +Eventually we plan to fully integrate datatree upstream into xarray's main codebase, at which point the `github.com/xarray-contrib/datatree `_ repository will be archived. +This should not cause much disruption to code that depends on datatree - you will likely only have to change the import line (i.e. from ``from datatree import DataTree`` to ``from xarray import DataTree``). + +However, until this full integration occurs, datatree's API should not be considered to have the same `level of stability as xarray's `_. + +User Feedback +~~~~~~~~~~~~~ + +We really really really want to hear your opinions on datatree! +At this point in development, user feedback is critical to help us create something that will suit everyone's needs. +Please raise any thoughts, issues, suggestions or bugs, no matter how small or large, on the `github issue tracker `_. .. toctree:: :maxdepth: 2 @@ -18,7 +50,6 @@ Datatree Terminology How do I ... Contributing Guide - Development Roadmap What's New GitHub repository From 45c32a5ae5b750a5143e8c9d0f3428a343e49b65 Mon Sep 17 00:00:00 2001 From: Thomas Nicholas Date: Thu, 5 Jan 2023 11:23:20 -0500 Subject: [PATCH 2/2] whatsnew --- docs/source/whats-new.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/whats-new.rst b/docs/source/whats-new.rst index 0d59e0e7..93fad0e1 100644 --- a/docs/source/whats-new.rst +++ b/docs/source/whats-new.rst @@ -60,6 +60,8 @@ Documentation By `Tom Nicholas `_. - Added page on ``Working with Hierarchical Data`` (:pull:`179`) By `Tom Nicholas `_. +- Added context content to ``Index`` page (:pull:`182`) + By `Tom Nicholas `_. Internal Changes ~~~~~~~~~~~~~~~~