Some figure updates

.gitignore

@@ -4,6 +4,7 @@ MPAS_data.nc
 MPAS_unstructured_data.nc
 docs/api/
 docs/examples/*.pdf
+docs/examples/*.png
 docs/examples/*.txt
 docs/examples/tb.gif
 mosa3.o*

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

@@ -27,6 +27,7 @@
     "import cartopy\n",
     "import cartopy.crs as ccrs\n",
     "import cartopy.feature as cfeature\n",
+    "import geopandas as gpd\n",
     "import matplotlib as mpl\n",
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
@@ -162,7 +163,7 @@
     "%%time\n",
     "\n",
     "# `tams.identify` does the above but also for the core threshold and does size filtering by default\n",
-    "cs_ug, cs_ug_core = list(zip(*tams.identify(ds.tb.isel(time=10))))[0]"
+    "cs_ug, cs_ug_core = list(zip(*tams.identify(ds.tb.isel(time=itime))))[0]"
    ]
   },
   {
@@ -264,6 +265,85 @@
     "\n",
     "![tricontour comparison zoomed](../_static/tri-compare_zoom.png)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "13",
+   "metadata": {},
+   "source": [
+    "## Precip inside CE\n",
+    "\n",
+    "This figure is intended to demonstrate what {func}`tams.data_in_contours` does."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "14",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ce = cs_ug.cx[138:145, -4:3]\n",
+    "assert len(ce) == 1, \"just one CE\"\n",
+    "\n",
+    "fig, ax = plt.subplots(figsize=(5, 4), subplot_kw=dict(projection=proj), constrained_layout=True)\n",
+    "\n",
+    "ax.gridlines(draw_labels=True)\n",
+    "ax.set_extent([137.5, 148, -4, 3], crs=tran)\n",
+    "ax.add_feature(cfeature.LAND)\n",
+    "\n",
+    "# tcs = ax.tricontourf(tri, ds.tb.isel(time=itime), levels=20, cmap=\"viridis_r\", transform=tran)\n",
+    "\n",
+    "pr = ds.precip.isel(time=itime)\n",
+    "s = ax.scatter(pr.lon, pr.lat, c=pr,\n",
+    "    ec=\"none\", s=7,\n",
+    "    cmap=\"viridis\", vmin=0, vmax=5, alpha=0.35,\n",
+    "    transform=tran,\n",
+    ")\n",
+    "\n",
+    "within = (\n",
+    "    gpd.GeoDataFrame({\"pr\": pr}, geometry=gpd.points_from_xy(pr.lon, pr.lat, crs=4326))\n",
+    "    .sjoin(ce[[\"geometry\"]], predicate=\"within\", how=\"left\")\n",
+    "    .dropna(subset=\"index_right\")\n",
+    ")\n",
+    "within.plot(ax=ax, column=\"pr\", cmap=\"viridis\", vmin=0, vmax=5, markersize=12, edgecolor=\"none\")\n",
+    "\n",
+    "ce.plot(ax=ax, fc=\"none\", ec=\"magenta\", lw=2)\n",
+    "\n",
+    "# ce.set_geometry(\"cs219\").plot(ax=ax, fc=\"none\", ec=\"cyan\", lw=1.5)\n",
+    "\n",
+    "fig.colorbar(s, orientation=\"horizontal\", extend=\"max\", shrink=0.7, label=\"Precipitation rate [mm/hr]\")\n",
+    "\n",
+    "fig.savefig(f\"mpas-ug-points-within-example_{stime}.png\", dpi=200, bbox_inches=\"tight\", pad_inches=0.05, transparent=False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "15",
+   "metadata": {},
+   "source": [
+    "## Versions"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "16",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%load_ext watermark"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "17",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%watermark -v -w -p cartopy,dask,gdown,geopandas,joblib,matplotlib,netCDF4,numpy,pandas,pygeos,regionmask,scipy,seaborn,shapely,skimage,xarray"
+   ]
   }
  ],
  "metadata": {

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,

docs/index.md

@@ -14,7 +14,7 @@ The original TAMS is described in {cite:t}`TAMS1.0`.
 {cite:t}`AEW-MCS` applied TAMS to African Easterly Wave research.
 
 ```{note}
-A paper describing _this_ implementation of TAMS {cite:p}`TAMS2.0` in Python is currently under review for publication in _GMD_.
+A paper describing _this_ implementation of TAMS {cite:p}`TAMS2.0` in Python has been accepted for publication in _GMD_.
 ```
 
 Datasets used in the examples can be retrieved with

docs/refs.bib

@@ -25,7 +25,7 @@ @article { AEW-MCS
 }
 
 @article { TAMS2.0,
-      author = {N\'u\~nez Ocasio, K. M. and Moon, Z. L.},
+      author = {Núñez Ocasio, Kelly M. and Moon, Zachary L.},
       title = {{TAMS}: A Tracking, Classifying, and Variable-Assigning Algorithm for Mesoscale Convective Systems in Simulated and Satellite-Derived Datasets},
       journal = {EGUsphere},
       year = {2024},

environment-dev.yml

@@ -43,6 +43,7 @@ dependencies:
   - sphinx-copybutton
   - sphinx-togglebutton
   - sphinxcontrib-bibtex
+  - watermark
   - pip:
       - sphinx-prompt <1.6
       - sphinxext-opengraph

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`