src - Document HRRR data access

Add docstring throughout much of the HRRR code and add a sample notebook
showing a use case.

notebooks/HRRR-data-acess.ipynb

@@ -0,0 +1,306 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cbcff1c1-f1e0-4982-a8ea-8b3dc31f79a2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from datetime import datetime, timedelta\n",
+    "from dask.distributed import LocalCluster\n",
+    "\n",
+    "from hrrr_db.db.models import Site \n",
+    "from hrrr_db.hrrr import HRRR, HRRRGrid, VariableInfo"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f28a11f3-a527-4c54-85e6-ab121145b730",
+   "metadata": {},
+   "source": [
+    "# References\n",
+    "https://mesowest.utah.edu/html/hrrr/zarr_documentation/html/python_data_loading.html"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "42260c2e-40dd-44a2-b184-642a043a40fc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cluster = LocalCluster(n_workers=6, threads_per_worker=1, memory_limit='4GB')\n",
+    "client = cluster.get_client()\n",
+    "client"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "30a3f0ea-56c9-44b3-9649-d4af74e83da6",
+   "metadata": {},
+   "source": [
+    "## Dates of interest"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2066cd16-43ac-4c04-9ca5-d88c436af482",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "october_1st = datetime.fromisoformat('2023-10-01T00:00:00')\n",
+    "date_list = [october_1st + timedelta(days=x) for x in range(10)]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "719c28d9-a8d5-4034-b88f-38fb837417df",
+   "metadata": {},
+   "source": [
+    "## Mores Creek"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "eb693bbc-eeb4-4f50-a677-63bca29d0c97",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "MCS_record = Site.load('Mores Creek Summit')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b031bfcc-0a0b-44b6-8d0b-bb643a64bfb0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mcs_HRRR = HRRR(True)\n",
+    "mcs_variable = VariableInfo(\n",
+    "    run_hour=date_list[0], \n",
+    "    level='surface', \n",
+    "    name='TMP'\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fcce6128-d5bd-4e13-8486-a49dffeb1cac",
+   "metadata": {},
+   "source": [
+    "# HRRR AWS"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2e833117-de2a-40f5-9b2a-6f80d6b62c2a",
+   "metadata": {},
+   "source": [
+    "### Single point"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "428254ba-0724-4f60-9a76-a319202d421a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mcs_HRRR.set_chunk_info_for_lon_lat(MCS_record.geom.x, MCS_record.geom.y)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7a7aa2f1-4626-4ab9-8bb2-434d71e6c2fc",
+   "metadata": {},
+   "source": [
+    "### Single value"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0b2114c6-d6cb-47df-b7ca-14a7290fcc50",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data = mcs_HRRR.load_tile(mcs_variable, forecast_hour=6)\n",
+    "data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9bab1b08-3891-48f7-90f0-36c26e61c694",
+   "metadata": {},
+   "source": [
+    "### Whole grid chunk containing the point"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "55935cf0-53d1-42f1-b56b-9945aa9470e8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "whole_grid = mcs_HRRR.load_dataset(mcs_variable)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1aa85af6-5432-46ba-af94-fe2e0c594c44",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "x, y = HRRRGrid.transform_lon_lat(\n",
+    "    MCS_record.geom.x, MCS_record.geom.y\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a707fb34-e836-4b4d-b28c-c9f584bb4cb0",
+   "metadata": {},
+   "source": [
+    "### Grab the point from the chunk"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "04a9e2ef-375a-4957-86b1-dfffeea03c02",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mcs_point = whole_grid.sel(\n",
+    "    x=x, y=y, method=\"nearest\"\n",
+    ")\n",
+    "\n",
+    "mcs_point"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ada28691-55a6-48be-a65f-96485e3e20f0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mcs_point.TMP.values[5]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9dba7355-21f7-43b1-b4b9-7903163e3472",
+   "metadata": {},
+   "source": [
+    "# Local File (slow)\n",
+    "\n",
+    "Requires to manually download the desired day from AWS or Google"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c6a12b92-ebff-4947-adbd-f01a8039c633",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fb3478e3-1df0-4412-9994-8d077753dee4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "grib_f = xr.open_mfdataset(\n",
+    "    '/path/to/file.grib',\n",
+    "    filter_by_keys={\n",
+    "        'stepType': 'instant', \n",
+    "        'typeOfLevel': 'surface'\n",
+    "    },\n",
+    "    parallel=True\n",
+    ")\n",
+    "grib_f = grib_f.drop_vars(['time'])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3862bf6a-98b3-43ad-b2a7-2239b36145da",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "grib_f = grib_f.metpy.assign_crs(HRRRGrid.CRS.to_cf())\n",
+    "grib_f = grib_f.metpy.assign_y_x()\n",
+    "grib_f = grib_f.set_coords(\"valid_time\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "19b6ecb4-3064-45dc-892d-161a6bf8de12",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "x, y = HRRRGrid.transform_lon_lat(\n",
+    "     MCS_record.geom.x, MCS_record.geom.y\n",
+    ")\n",
+    "\n",
+    "mcs_grib_f = grib_f.sel(\n",
+    "    x=x, y=y, method=\"nearest\"\n",
+    ")\n",
+    "mcs_grib_f"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "472b5e3c-8879-4e1b-adbf-faf105494037",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mcs_grib_f.t.values"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7c4cf74f-03a3-4156-a68c-e69e6fb5e820",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "client.shutdown()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "python3 (micromamba-HRRR-s3)",
+   "language": "python",
+   "name": "conda-env-micromamba-HRRR-s3-py"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}