Skip to content

Commit 9849bdf

Browse files
authored
Add content to Index page xarray-contrib/datatree#182
* Joe's suggestions for index page * whatsnew
1 parent f922182 commit 9849bdf

File tree

2 files changed

+34
-1
lines changed

2 files changed

+34
-1
lines changed

docs/source/index.rst

+32-1
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,38 @@ Datatree
33

44
**Datatree is a prototype implementation of a tree-like hierarchical data structure for xarray.**
55

6+
Why Datatree?
7+
~~~~~~~~~~~~~
8+
9+
Datatree was born after the xarray team recognised a `need for a new hierarchical data structure <https://github.com/pydata/xarray/issues/4118>`_,
10+
that was more flexible than a single :py:class:`xarray.Dataset` object.
11+
The initial motivation was to represent netCDF files / Zarr stores with multiple nested groups in a single in-memory object,
12+
but :py:class:`~datatree.DataTree` objects have many other uses.
13+
14+
You might want to use datatree for:
15+
16+
- Organising many related datasets, e.g. results of the same experiment with different parameters, or simulations of the same system using different models,
17+
- Analysing similar data at multiple resolutions simultaneously, such as when doing a convergence study,
18+
- Comparing heterogenous but related data, such as experimental and theoretical data,
19+
- I/O with nested data formats such as netCDF / Zarr groups.
20+
21+
Development Roadmap
22+
~~~~~~~~~~~~~~~~~~~
23+
24+
Datatree currently lives in a separate repository to the main xarray package.
25+
This allows the datatree developers to make changes to it, experiment, and improve it faster.
26+
27+
Eventually we plan to fully integrate datatree upstream into xarray's main codebase, at which point the `github.com/xarray-contrib/datatree <https://github.com/xarray-contrib/datatree>`_ repository will be archived.
28+
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``).
29+
30+
However, until this full integration occurs, datatree's API should not be considered to have the same `level of stability as xarray's <https://docs.xarray.dev/en/stable/contributing.html#backwards-compatibility>`_.
31+
32+
User Feedback
33+
~~~~~~~~~~~~~
34+
35+
We really really really want to hear your opinions on datatree!
36+
At this point in development, user feedback is critical to help us create something that will suit everyone's needs.
37+
Please raise any thoughts, issues, suggestions or bugs, no matter how small or large, on the `github issue tracker <https://github.com/xarray-contrib/datatree/issues>`_.
638

739
.. toctree::
840
:maxdepth: 2
@@ -18,7 +50,6 @@ Datatree
1850
Terminology <terminology>
1951
How do I ... <howdoi>
2052
Contributing Guide <contributing>
21-
Development Roadmap <roadmap>
2253
What's New <whats-new>
2354
GitHub repository <https://github.com/xarray-contrib/datatree>
2455

docs/source/whats-new.rst

+2
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,8 @@ Documentation
6060
By `Tom Nicholas <https://github.com/TomNicholas>`_.
6161
- Added page on ``Working with Hierarchical Data`` (:pull:`179`)
6262
By `Tom Nicholas <https://github.com/TomNicholas>`_.
63+
- Added context content to ``Index`` page (:pull:`182`)
64+
By `Tom Nicholas <https://github.com/TomNicholas>`_.
6365

6466
Internal Changes
6567
~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)