diff --git a/_toc.yml b/_toc.yml index 69ff42e4..e9197c7b 100644 --- a/_toc.yml +++ b/_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 diff --git a/fundamentals/01_datatree_hierarchical_data.ipynb b/fundamentals/01_datatree_hierarchical_data.ipynb new file mode 100644 index 00000000..5ca76bff --- /dev/null +++ b/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 +}