| CI |    |
|---|---|
| Docs |  |
| Package |   |
| License |  |
Datatree is a prototype implementation of a tree-like hierarchical data structure for xarray.
Datatree was born after the xarray team recognised a need for a new hierarchical data structure,
that was more flexible than a single xarray.Dataset object.
The initial motivation was to represent netCDF files / Zarr stores with multiple nested groups in a single in-memory object,
but datatree.DataTree objects have many other uses.
Datatree is in the process of being merged upstream into xarray (as of v0.0.14, see xarray issue #8572). We are aiming to preserve the record of contributions to this repository during the migration process. However whilst we will hapily accept new PRs to this repository, this repo will be deprecated and any PRs since v0.0.14 might be later copied across to xarray without full git attribution.
Hopefully for users the disruption will be minimal - and just mean that in some future version of xarray you only need to do from xarray import DataTree rather than from datatree import DataTree. Once the migration is complete this repository will be archived.
You can install datatree via pip:
pip install xarray-datatreeor via conda-forge
conda install -c conda-forge xarray-datatreeYou 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.
Talk slides on Datatree from AMS-python 2023
The approach used here is based on benbovy's DatasetNode example - the basic idea is that each tree node wraps a up to a single xarray.Dataset. The differences are that this effort:
- Uses a node structure inspired by anytree for the tree,
- Implements path-like getting and setting,
- Has functions for mapping user-supplied functions over every node in the tree,
- Automatically dispatches some of
xarray.Dataset's API over every node in the tree (such as.isel), - Has a bunch of tests,
- Has a printable representation that currently looks like this:
You can create a DataTree object in 3 ways:
- Load from a netCDF file (or Zarr store) that has groups via
open_datatree(). - Using the init method of
DataTree, which creates an individual node. You can then specify the nodes' relationships to one other, either by setting.parentand.childrenattributes, or through__get/setitem__access, e.g.dt['path/to/node'] = DataTree(). - Create a tree from a dictionary of paths to datasets using
DataTree.from_dict().
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.
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.