Introduction to backends

_toc.yml

@@ -86,6 +86,7 @@ parts:
           - file: advanced/map_blocks/simple_map_blocks
       - file: advanced/backends/backends.md
         sections:
+          - file: advanced/backends/intro-backends.ipynb
           - file: advanced/backends/1.Backend_without_Lazy_Loading.ipynb
           - file: advanced/backends/2.Backend_with_Lazy_Loading.ipynb
       - file: advanced/accessors/accessors.md

advanced/backends/intro-backends.ipynb

@@ -0,0 +1,182 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# Introduction to Xarray Backends\n",
+    "In this lesson, we will learn about and how to use xarray's backends\n",
+    "\n",
+    ":::{admonition} Learning Goals\n",
+    "- Learn about xarray's internal and external backends\n",
+    "- Learn how xarray selects backend engines\n",
+    "- Learn how to specify backend engines\n",
+    ":::\n",
+    "\n",
+    "## What are Xarray Backends\n",
+    "\n",
+    "Xarray supports direct serialization and IO to several file formats, through the use of internal and external backends. Xarray's internal backends cover many common data formats such as \"netCDF4\", \"h5netcdf\", and \"zarr\". These backends provide a set of instructions that tells xarray how read data and store it into a `Dataset`, `DataTree` or `DataTree` model and are stored in the underlying “backend”. \n",
+    "\n",
+    "Xarray also supports external backends such as \"rioxarray\" and \"cfgrib\" and even creating your own backend.\n",
+    "\n",
+    "\n",
+    ":::{admonition} See also\n",
+    "You can learn more about xarray's [internal](https://tutorial.xarray.dev/advanced/backends/backends.html#links-to-internal-backends) and [external](https://tutorial.xarray.dev/advanced/backends/backends.html#links-to-external-backends-not-comprehensive) with our [guide](https://docs.xarray.dev/en/latest/user-guide/io.html) to backends.\n",
+    "\n",
+    ":::"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1",
+   "metadata": {},
+   "source": [
+    "## Reading a dataset with the netCDF4 engine\n",
+    "\n",
+    "We can read in a dataset by selecting the \"netcdf4\" engine"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "\n",
+    "xr.tutorial.open_dataset(\"air_temperature\", engine=\"netcdf4\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3",
+   "metadata": {},
+   "source": [
+    "## Internal Backend Selection\n",
+    "\n",
+    "When opening a file or URL without explicitly specifying the ``engine`` parameter,\n",
+    "xarray automatically selects an appropriate backend based on the file path or URL.\n",
+    "The backends are tried in order: **netcdf4 → h5netcdf → scipy → pydap → zarr**.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4",
+   "metadata": {},
+   "source": [
+    "## Check for available backends\n",
+    "\n",
+    "We can get a list of our available engines with `list_engines`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "\n",
+    "xr.backends.list_engines()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6",
+   "metadata": {},
+   "source": [
+    "## Reading without specifying engine\n",
+    "\n",
+    "When opening a file or URL without explicitly specifying the ``engine`` parameter,\n",
+    "xarray automatically selects an appropriate backend based on the file path or URL.\n",
+    "The backends are tried in order: **netcdf4 → h5netcdf → scipy → pydap → zarr**.\n",
+    "\n",
+    "In the following example this dataset is read with the \"netcdf4\" engine without explicitly setting the `\"engine=netcdf4\"`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "xr.tutorial.open_dataset(\"air_temperature\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8",
+   "metadata": {},
+   "source": [
+    "## Setting engine order\n",
+    "\n",
+    "You can customize the order in which netcdf4 backends are resolved using `xr.set_options(netcdf_engine_order=)`\n",
+    "\n",
+    "Let's update our engine order to have \"h5netcdf\" and the \"netCDF4\" and reopening the dataset"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "xr.set_options(netcdf_engine_order=[\"h5netcdf\", \"netcdf4\", \"scipy\"])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "10",
+   "metadata": {},
+   "source": [
+    "## Specifying the wrong backend"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "11",
+   "metadata": {},
+   "source": [
+    "Lets trying specifying a bad engine for opening our dataset\n",
+    "\n",
+    ":::{warning}\n",
+    "This will fail because we cannot use the \"pydap\" engine to read this dataset\n",
+    ":::"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "12",
+   "metadata": {
+    "tags": [
+     "raises-exception"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "xr.tutorial.open_dataset(\"air_temperature\", engine=\"pydap\")"
+   ]
+  }
+ ],
+ "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": 5
+}