Add some notes

suggested by K

docs/examples/sample-mpas-ug-data.ipynb

@@ -271,7 +271,9 @@
    "id": "13",
    "metadata": {},
    "source": [
-    "## Precip inside CE"
+    "## Precip inside CE\n",
+    "\n",
+    "This figure is intended to demonstrate what {func}`tams.data_in_contours` does."
    ]
   },
   {

docs/examples/sample-satellite-data.ipynb

@@ -84,6 +84,16 @@
     "contour_sets[0].head()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "```{note}\n",
+    "`inds219` gives the indices of 219 (cold-core) shapes in a `contour_sets_219` dataframe that are inside a certain 235 shape (row in a `contour_sets` dataframe).\n",
+    "This is for internal debugging purposes and may be removed in the future.\n",
+    "```"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

tams/data.py

@@ -181,7 +181,7 @@ def load_example_tb() -> xarray.DataArray:
 
 
 def load_example_mpas() -> xarray.Dataset:
-    """Load the example MPAS dataset.
+    r"""Load the example MPAS dataset.
 
     This is a spatial and variable subset of native MPAS output,
     Furthermore, it has been regridded to a regular lat/lon grid (0.25°)
@@ -197,6 +197,16 @@ def load_example_mpas() -> xarray.Dataset:
     and ``precip`` (precipitation rate, derived by summing the MPAS accumulated
     grid-scale and convective precip variables ``rainnc`` and ``rainc`` and differentiating).
 
+    ``tb`` was estimated using the (black-body) Stefan--Boltzmann law:
+
+    .. math::
+       E = \sigma T^4
+       \implies T = (E / \sigma)^{1/4}
+
+    where :math:`E` is the OLR (outgoing longwave radiation, ``olrtoa`` in MPAS output)
+    in W m\ :sup:`-2`
+    and :math:`\sigma` is the Stefan--Boltzmann constant.
+
     This dataset contains 127 time steps of hourly data:
     2006-09-08 12 -- 2006-09-13 18.
 
@@ -226,7 +236,7 @@ def load_example_mpas() -> xarray.Dataset:
 
 
 def load_example_mpas_ug() -> xarray.Dataset:
-    """Load the example MPAS unstructured grid dataset.
+    r"""Load the example MPAS unstructured grid dataset.
 
     This is a spatial and variable subset of native 15-km global mesh MPAS output.
 
@@ -242,6 +252,17 @@ def load_example_mpas_ug() -> xarray.Dataset:
     for the period
     2006-09-08 12 -- 2006-09-13 18.
 
+    Like the regridded MPAS dataset,
+    ``tb`` was estimated using the (black-body) Stefan--Boltzmann law:
+
+    .. math::
+       E = \sigma T^4
+       \implies T = (E / \sigma)^{1/4}
+
+    where :math:`E` is the OLR (outgoing longwave radiation, ``olrtoa`` in MPAS output)
+    in W m\ :sup:`-2`
+    and :math:`\sigma` is the Stefan--Boltzmann constant.
+
     See Also
     --------
     :func:`tams.data.download_examples`