Tracking options nb

.gitignore

@@ -2,11 +2,12 @@
 Satellite_data.nc
 MPAS_data.nc
 docs/api/
+docs/examples/*.pdf
+docs/examples/*.txt
 mosa3.o*
 mosa2.o*
 mosa1.o*
 
-
 # GitHub Python default gitignore below:
 
 # Byte-compiled / optimized / DLL files

.pre-commit-config.yaml

@@ -43,3 +43,4 @@ repos:
     rev: "0.6.1"
     hooks:
       - id: nbstripout
+        exclude: ^docs/examples/tracking-options.ipynb

docs/conf.py

@@ -26,7 +26,6 @@
     "**.ipynb_checkpoints",
     # "api/**/*",
     "examples/t2.ipynb",
-    "examples/t3.ipynb",
 ]
 
 html_theme = "sphinx_book_theme"
@@ -73,7 +72,10 @@
 }
 
 nb_execution_mode = "cache"
-nb_execution_excludepatterns = exclude_patterns
+nb_execution_excludepatterns = exclude_patterns + [
+    "examples/tracking-options.ipynb",
+]
+nb_execution_raise_on_error = True
 
 myst_enable_extensions = [
     "dollarmath",

docs/examples/sample-satellite-data.ipynb

@@ -17,11 +17,14 @@
    "source": [
     "import warnings\n",
     "\n",
+    "import cartopy\n",
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
     "import xarray as xr\n",
     "\n",
-    "import tams"
+    "import tams\n",
+    "\n",
+    "warnings.filterwarnings(\"ignore\", category=cartopy.io.DownloadWarning)"
    ]
   },
   {

docs/examples/t3.ipynb → docs/examples/tams-run.ipynb

@@ -5,7 +5,17 @@
    "id": "6922ca63-d1a4-43f7-8fc2-68e6851984c4",
    "metadata": {},
    "source": [
-    "# Testing the new `run` fn for MPAS sample"
+    "# {func}`tams.run`\n",
+    "\n",
+    "{func}`tams.run` is a convenience function that does\n",
+    "\n",
+    "1. {func}`tams.identify`\n",
+    "2. {func}`tams.track`\n",
+    "3. {func}`tams.classify`\n",
+    "4. aggregation and statistics\n",
+    "\n",
+    "Using a selection of the {func}`example post-processed MPAS data <tams.load_example_mpas>`,\n",
+    "we investigate its outputs."
    ]
   },
   {
@@ -15,8 +25,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import sys; sys.path.append(\"../\")\n",
-    "\n",
     "import xarray as xr\n",
     "\n",
     "import tams"
@@ -26,28 +34,60 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "e528969a-592a-4d67-9296-3b3ff0b5d032",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": [
+     "remove-output"
+    ]
+   },
    "outputs": [],
    "source": [
     "xr.set_options(display_expand_data=False)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "daee10a9-849a-483a-b2de-0e78e20b467f",
+   "metadata": {},
+   "source": [
+    "{func}`tams.run` expects certain variable names."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "id": "9357c333-56fa-4e6e-9199-4e9b43725c4d",
    "metadata": {},
    "outputs": [],
    "source": [
-    "ds = tams.load_example_mpas().rename({\"tb\": \"ctt\", \"precip\": \"pr\"}).isel(time=slice(1, 20))\n",
+    "ds = tams.load_example_mpas().rename({\"tb\": \"ctt\", \"precip\": \"pr\"}).isel(time=slice(1, 13))\n",
     "ds"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "c392020f-4ec0-4ede-8d49-6858a5a8e92f",
+   "metadata": {},
+   "source": [
+    "{func}`tams.run` produces three output datasets."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "id": "b893bba8-3603-446f-8609-cc39e9a504a3",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": [
+     "hide-output"
+    ]
+   },
    "outputs": [],
    "source": [
     "%%time\n",
@@ -61,7 +101,10 @@
    "metadata": {},
    "source": [
     "## CE dataset\n",
-    "\n"
+    "\n",
+    "Identified cloud elements (CEs). Tracking has added `mcs_id`; classification has added `mcs_class`.\n",
+    "\n",
+    "Each row corresponds to a CE--time that belongs to an MCS. A certain MCS at a given time may include multiple CEs.  "
    ]
   },
   {
@@ -84,12 +127,28 @@
     "ce.info()"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dcb6b436-c0ee-4f8a-b117-a90ddc41f588",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ce.area_km2.describe()"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "2bf1e67c-1774-457e-bd9b-ef87f06bfc5d",
    "metadata": {},
    "source": [
-    "## MCS dataset"
+    "## MCS dataset\n",
+    "\n",
+    "At each time, CEs with the same MCS ID are combined into one.\n",
+    "\n",
+    "Some statistics of precip (`pr`) and cloud-top temperature (`ctt`) within the MCS areas are included.\n",
+    "\n",
+    "Each row corresponds to an MCS--time."
    ]
   },
   {
@@ -117,7 +176,11 @@
    "id": "12b3a841-a75f-4295-90cf-cbb693545cfd",
    "metadata": {},
    "source": [
-    "## MCS summary dataset"
+    "## MCS summary dataset\n",
+    "\n",
+    "No more shapes (just first and last centroid points).\n",
+    "\n",
+    "Each row corresponds to an MCS, including some statistics for the track such as the MCS's duration and initial and final coordinates."
    ]
   },
   {
@@ -139,6 +202,16 @@
    "source": [
     "mcs_summary.info()"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dad5a677-1699-41d1-8e1b-93a36128577a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mcs_summary.describe()"
+   ]
   }
  ],
  "metadata": {
@@ -157,7 +230,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.10"
+   "version": "3.10.13"
   }
  },
  "nbformat": 4,