fix: update notebooks

Author: lewisjared

notebooks/01-ref-concepts.ipynb

@@ -8,12 +8,11 @@
     "# 01 — REF concepts\n",
     "\n",
     "This notebook introduces the core vocabulary of the **Rapid Evaluation Framework (REF)**.\n",
-    "By the end you will know what a *diagnostic*, *provider*, *execution*, *metric* and *dataset* are,\n",
-    "and how they fit together.\n",
+    "By the end you will know what a *diagnostic*, *provider*, *execution*, *metric* and *dataset* are, and how they fit together.\n",
     "\n",
     "**Prerequisites:** none. This is the place to start.\n",
     "\n",
-    "**What you need:** an internet connection — we read live examples from the public REF API."
+    "**What you need:** an internet connection as we read from the public REF API."
    ]
   },
   {
@@ -23,20 +22,22 @@
    "source": [
     "## What is the REF?\n",
     "\n",
-    "The REF runs calculations against climate datasets, much like a CI/CD pipeline runs tests\n",
-    "against code. As new climate model output is published, the REF evaluates it against\n",
-    "reference data and produces figures and metrics — in near-real time.\n",
+    "The REF performs evaluation of climate datasets, much like a CI/CD pipeline runs tests against code. \n",
+    "As new climate model output is published, the REF evaluates it against reference data \n",
+    "and produces figures and metrics — in near-real time.\n",
     "\n",
-    "The public deployment evaluates CMIP7 Assessment Fast Track data. Its results are served\n",
-    "from a website (<https://climate-ref.org>) and a public API (<https://api.climate-ref.org>).\n",
+    "The public deployment currently evaluates CMIP6 dataset, but will include CMIP7 Assessment Fast Track data\n",
+    "as they become available.\n",
+    "Results are served from a website (<https://dashboard.climate-ref.org>) and a public API (<https://api.climate-ref.org>).\n",
     "\n",
-    "Throughout these notebooks we talk to that API. The `ref_tutorials` helper package (shipped\n",
-    "with this repository) builds the API client for us:"
+    "Throughout these notebooks we talk to the API via an \"SDK\".\n",
+    "This SDK allows us to make requests to the API without having to directly make HTTP requests.\n",
+    "The `ref_tutorials` helper package (shipped with this repository) builds the API client for us."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 2,
    "id": "05ac27ad",
    "metadata": {},
    "outputs": [
@@ -46,7 +47,7 @@
        "Client(raise_on_unexpected_status=False, _base_url='https://api.climate-ref.org', _cookies={}, _headers={}, _timeout=None, _verify_ssl=True, _follow_redirects=False, _httpx_args={}, _client=None, _async_client=None)"
       ]
      },
-     "execution_count": 1,
+     "execution_count": 2,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -65,15 +66,15 @@
    "source": [
     "## Diagnostics\n",
     "\n",
-    "A **diagnostic** is a single, well-defined evaluation — for example \"the global mean\n",
-    "surface temperature timeseries\" or \"the Atlantic overturning circulation strength\".\n",
+    "A **diagnostic** is a single, well-defined evaluation to understand a component of the earth system.\n",
+    "For example \"the global mean surface temperature timeseries\" or \"the Atlantic overturning circulation strength\".\n",
     "\n",
     "Let's list the diagnostics the REF currently provides:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 3,
    "id": "8196f36e",
    "metadata": {},
    "outputs": [
@@ -116,7 +117,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 4,
    "id": "3389ca04",
    "metadata": {},
    "outputs": [
@@ -144,16 +145,23 @@
    "source": [
     "## Providers\n",
     "\n",
-    "Diagnostics are grouped into **providers**. A provider is a package that knows how to\n",
-    "compute a family of diagnostics — examples include ESMValTool, the PCMDI Metrics Package\n",
-    "(PMP), and ILAMB. The REF orchestrates providers; it does not compute diagnostics itself.\n",
+    "Diagnostics are grouped into **providers**. A **provider** is a package that knows how to compute a family of diagnostics.\n",
+    "\n",
+    "For the Assessment Fast Track we use:\n",
+    "\n",
+    "- ESMValTool\n",
+    "- PCMDI Metrics Package (PMP)\n",
+    "- ILAMB/IOMB\n",
+    "\n",
+    "The REF orchestrates providers and does not compute diagnostics itself.\n",
+    "Each provider is a thin wrapper around the upstream diagnostics package.\n",
     "\n",
     "Each diagnostic tells you which provider it belongs to:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 5,
    "id": "45bfc188",
    "metadata": {},
    "outputs": [
@@ -181,11 +189,10 @@
    "source": [
     "## Datasets\n",
     "\n",
-    "A diagnostic needs **datasets** to run against: the climate model output under evaluation,\n",
-    "and the reference (often observational) data it is compared to. The REF tracks which\n",
-    "datasets are available and which combinations a diagnostic requires.\n",
+    "A diagnostic needs **datasets** to run against: the climate model output under evaluation, and the reference data it is compared to.\n",
+    "The REF tracks which datasets are available and which diagnostics have already been run.\n",
     "\n",
-    "For the public API we do not handle raw datasets directly — the evaluations have already\n",
+    "For the public API we do not handle raw CMIP6 datasets directly the evaluations have already\n",
     "been run. We will see locally fetched datasets in notebook 04."
    ]
   },
@@ -197,15 +204,17 @@
     "## Executions\n",
     "\n",
     "An **execution** is one run of a diagnostic against one specific group of datasets.\n",
-    "A single diagnostic is typically executed many times — once per model, experiment, or\n",
-    "scenario — so it has many executions, organised into *execution groups*.\n",
+    "\n",
+    "A single diagnostic is typically executed many times. This generally depends what is being calculated, but this is often once per model variant.\n",
+    "Each of these individual groups is an *execution group*.\n",
+    "If any datasets in an execution group change, then a new execution is performed.\n",
     "\n",
     "Here are the execution groups of one diagnostic:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 6,
    "id": "e06e64b8",
    "metadata": {},
    "outputs": [
@@ -233,13 +242,14 @@
     "\n",
     "An execution produces output. That output comes in two main shapes:\n",
     "\n",
-    "- **Metric values** — numbers that summarise a property of a model. A *scalar* is a single\n",
-    "  number (e.g. a root-mean-square error); a *series* is a number per index point\n",
+    "- **Metric values** — numbers that summarise a property of a model. \n",
+    "  A *scalar* is a single number (e.g. a root-mean-square error) or a *series* is a number per index point\n",
     "  (e.g. a seasonal cycle).\n",
     "- **Files** — NetCDF data and figures for deeper analysis or custom plotting.\n",
     "\n",
-    "Notebook 02 shows how to retrieve metric values, and notebook 03 turns them into a\n",
-    "publication-ready figure."
+    "The REF ingests all of these outputs into its database so they can be queried by the API.\n",
+    "\n",
+    "Notebook 02 shows how to retrieve metric values, and notebook 03 turns them into a figure."
    ]
   },
   {
@@ -249,13 +259,13 @@
    "source": [
     "## Recap\n",
     "\n",
-    "| Term | Meaning |\n",
-    "|------|---------|\n",
-    "| **Provider** | A package that computes a family of diagnostics (ESMValTool, PMP, ILAMB, ...) |\n",
-    "| **Diagnostic** | A single well-defined evaluation |\n",
-    "| **Dataset** | Climate model output or reference data a diagnostic runs against |\n",
-    "| **Execution** | One run of a diagnostic against one group of datasets |\n",
-    "| **Metric value** | A scalar or series result summarising a model |\n",
+    "| Term                | Meaning                                                                       |\n",
+    "| ------------------- | ----------------------------------------------------------------------------- |\n",
+    "| **Provider**        | A package that computes a family of diagnostics (ESMValTool, PMP, ILAMB, ...) |\n",
+    "| **Diagnostic**      | A single well-defined evaluation                                              |\n",
+    "| **Dataset**         | Climate model output or reference data a diagnostic runs against              |\n",
+    "| **Execution**       | One run of a diagnostic against one group of datasets                         |\n",
+    "| **Metric value**    | A scalar or series result summarising a model                                 |\n",
     "\n",
     "**Next:** [02 — Querying the REF API](02-querying-the-api.ipynb)."
    ]
@@ -271,7 +281,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "climate-ref-tutorials (3.14.4)",
    "language": "python",
    "name": "python3"
   },