{ "cells": [ { "cell_type": "markdown", "id": "d00bb4bd", "metadata": {}, "source": [ "# Getting started\n", "\n", "\n", "```{note}\n", "\n", "Feel free to click through the individual tutorials, some of them are already finished!\n", "```\n", "\n", "```{warning}\n", "\n", "This **\"Getting started\"** tutorial will give a brief general overview and then link to the specific tutorials on each major concept. It is still work-in-progress and will be finalized as the other more specific tutorials mature.\n", "```" ] }, { "cell_type": "markdown", "id": "ea52397a", "metadata": {}, "source": [ "## 1. The `xsnowDataset` data model\n", "Unlike data models that treat each *single snow profile* as a standalone object, `xsnow` organizes data on a labeled grid. That means one dataset can hold:\n", "\n", "- multiple locations,\n", "- multiple times,\n", "- multiple slope/aspect configurations per location and time,\n", "- multiple realizations (e.g. different weather forcings, ensemble members), and\n", "- each full stratigraphy (layered snow profile) underneath those.\n", "\n", "Formally, the core dimensions are:\n", "\n", "1. **`location`**\n", " Where is this profile? We typically attach geographic metadata as *coordinates* on this dimension (e.g. `latitude`, `longitude`, `easting`, `northing`, `altitude`).\n", "\n", "2. **`time`**\n", " When is this profile valid?\n", " Note: `time` is *timezone-naive* and reflects whatever the data source used. How to handle time zones correctly is covered in [Handling timezones](./timezones).\n", "\n", "3. **`slope`**\n", " Same physical location and time, but different terrain orientation. xsnow attaches the coordinates\n", " - `inclination` (degrees from horizontal)\n", " - `azimuth` (degrees from north; e.g., 180° = south)\n", " \n", " If you only have one slope/aspect, the dimension length is 1.\n", " \n", "\n", "4. **`realization`**\n", " Parallel \"versions\" of the snowpack for the same `(location, time, slope)` — for example:\n", " - different weather inputs (multi model, or ensemble model members),\n", " - different physical parametrizations,\n", " - observed vs. modeled,\n", " - different land cover classes, etc. \n", " If you don't use this dimension, it's still present but length 1.\n", " \n", "5. **`layer`**\n", " The vertical snow stratigraphy. Variables defined along `layer` describe per-layer properties: density, grain size, temperature, etc. There is also a vertical coordinate variable like `z` (zero at the snow surface, positive upward, negative downward).\n", "\n", "\n", "Those five dimensions give you a consistent, rectangular grid. On top of them, we store two broad kinds of variables:\n", "\n", "| Kind of variable | Typical dims |\n", "|------------------------------------------|----------------------------------------------------------|\n", "| **Profile-level / scalar per profile** | `(location, time, slope, realization)` |\n", "| **Layer-level / stratigraphy variable** | `(location, time, slope, realization, layer)` |\n", "\n", "Example:\n", "- `HS` (total snow height) is profile-level and therefore does not have a `layer` dimension.\n", "- `density` is a layer property and therefore it *does* have the `layer` dimension.\n", "\n", "\n", "**Why this structure?**\n", "\n", "- You can run fully vectorized analysis and statistics across large subsets of the data. \n", " For example: *“Give me all weak layers with poor stability on north-facing slopes after a certain date”* becomes a straightforward selection and filter on the dataset---no manual loops, no filename parsing, no ad hoc per-station scripts.\n", "\n", "- The entire dataset can be serialized to (and restored from) NetCDF efficiently, lazily, and it can be subset on parsing.\n", "\n", "- By adopting this data model, `xsnow` can directly leverage the high-performance [`xarray`](https://docs.xarray.dev/en/stable/) ecosystem. \n", " This not only gives us convenient labeled indexing, resampling, and computation, but also sets up `xsnow` for future-friendly storage formats like *zarr* / *geozarr*, which are increasingly used for scalable, cloud-native geoscience data.\n" ] }, { "cell_type": "markdown", "id": "9bcb7568", "metadata": {}, "source": [ "```{admonition} An xsnowDataset feels like an xarray.Dataset\n", ":class: note\n", "\n", "While `xsnow` introduces its own class, `xsnowDataset`, we’ve taken meticulous care to make an `xsnowDataset` *behave and feel* just like an `xarray.Dataset`.\n", "\n", "- **Full compatibility:** \n", " Any method you can call on an `xarray.Dataset` can also be called on an `xsnowDataset`.\n", "\n", "- **Underlying xarray object:** \n", " Every `xsnowDataset` contains a regular `xarray.Dataset` holding the actual data, accessible via the attribute `ds.data`. \n", " If you want to explicitly export to a pure `xarray.Dataset`, simply call:\n", "\n", " ds.to_xarray()\n", "\n", "- **Automatic method forwarding:** \n", " Any attribute or method that’s not part of `xsnowDataset` is automatically forwarded to the underlying `xarray.Dataset`. \n", " For example:\n", "\n", " ds.info() # under the hood calls ds.data.info()\n", " ds['density'] # under the hood calls ds.data['density']\n", "\n", "- **Helpful auto-complete organization:** \n", " Python’s tab completion works seamlessly and is structured to help you explore:\n", "\n", " ds. # + TAB: shows xsnow-native methods and coordinates\n", " ds.data. # + TAB: shows all xarray.Dataset methods available on ds as well\n", "\n", "This design keeps the workflow intuitive: you get all the power of `xarray`, plus the specialized snow science functionality of `xsnow`.\n", "```" ] }, { "cell_type": "markdown", "id": "7d938650", "metadata": {}, "source": [ "```{warning}\n", "\n", "More coming soon!\n", "```" ] } ], "metadata": { "language_info": { "name": "python" } }, "nbformat": 4, "nbformat_minor": 5 }