Hierarchical trees of related groups (DataTree) for SciPy35

_toc.yml

@@ -18,6 +18,7 @@ parts:
           - file: fundamentals/01_datastructures
           - file: fundamentals/01.1_creating_data_structures
           - file: fundamentals/01.1_io
+          - file: fundamentals/01_datatree_hierarchical_data.ipynb
       - file: fundamentals/02_labeled_data.md
         sections:
           - file: fundamentals/02.1_indexing_Basic.ipynb

fundamentals/01_datatree_hierarchical_data.ipynb

@@ -0,0 +1,186 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# `xarray.DataTree` and hierarchical data\n",
+    "\n",
+    "In this lesson, we will learn how to use `xarray.DataTree` with hierarchical data. By the end of the lesson, we will be able to:\n",
+    "\n",
+    ":::{admonition} Learning Goals\n",
+    "- Understand a basic `DataTree` structure (nodes, parents and children)\n",
+    "- Selecting `DataTree`\n",
+    "- Understand coordinate inheritance :::"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Opening a dataset with `open_datatree()`\n",
+    "\n",
+    "Let's open up a precipitation dataset. This dataset was derived from \"GPM_3IMERGHH_07\" and \"M2T1NXFLX_5.12.4\" products."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "precipitation = xr.tutorial.open_datatree('precipitation.nc4')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Nodes\n",
+    "Groups in a netcdf4 or hdf5 file in the DataTree model are represented as \"nodes\" in the DataTree model.\n",
+    "We can list all of the groups with `.groups`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "precipitation.groups"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Accessing variables in a nested groups\n",
+    "Nested variables and groups can be accessed with either dict-like syntax or method based syntax."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "precipitation['observed']\n",
+    "\n",
+    "# Returns a DataTree object, containing the variables, dimensions, and coordinates in the \"observed\" node"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "precipitation['/observed/precipitation']"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "precipitation.reanalysis.precipitation\n",
+    "\n",
+    "# Method based syntax"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Get the parent and child nodes from a group"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "precipitation['reanalysis'].parent"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "precipitation.children"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Inheritance\n",
+    "DataTree implements a simple inheritance mechanism. Coordinates, dimensions and their associated indices are propagated downward from the root node to all descendent nodes.\n",
+    "\n",
+    "Let's take a look at some inherited coordinates with our precipitation dataset"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "precipitation.time"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `\"time\"` dimension is defined at the root node of our dataset and is propagated downward to the \"observed\" and \"reanalysis\" group"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "precipitation.observed"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "precipitation.reanalysis"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}