Merge pull request #1218 from PCMDI/doc/1217_clean_up_notebooks

Demo notebook clean up

doc/jupyter/Demo/Demo_0_download_data.ipynb

@@ -130,7 +130,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "pmp_devel_20241106_xcdat0.7.3",
+   "display_name": "pmp_devel_20241202",
    "language": "python",
    "name": "python3"
   },

doc/jupyter/Demo/Demo_1a_compute_climatologies.ipynb

@@ -13,6 +13,14 @@
    "id": "de63a73f",
    "metadata": {},
    "source": [
+    "This notebook introduces PCDMI mean climate driver.\n",
+    "\n",
+    "**Reference**\n",
+    "\n",
+    "* Gleckler, P. J., Taylor, K. E., and Doutriaux, C.: Performance metrics for climate models, J. Geophys. Res., 113, D06104, https://doi.org/10.1029/2007jd008972, 2008. \n",
+    "\n",
+    "* Lee, J., Gleckler, P. J., Ahn, M.-S., Ordonez, A., Ullrich, P. A., Sperber, K. R., Taylor, K. E., Planton, Y. Y., Guilyardi, E., Durack, P., Bonfils, C., Zelinka, M. D., Chao, L.-W., Dong, B., Doutriaux, C., Zhang, C., Vo, T., Boutte, J., Wehner, M. F., Pendergrass, A. G., Kim, D., Xue, Z., Wittenberg, A. T., and Krasting, J.: Systematic and objective evaluation of Earth system models: PCMDI Metrics Package (PMP) version 3, Geosci. Model Dev., 17, 3919–3948, https://doi.org/10.5194/gmd-17-3919-2024, 2024.\n",
+    "\n",
     "Model output and observations must be converted into annual climatologies for use with the mean climate driver. This has already been done for the observations provided by PCMDI. PMP provides a script for generating these input climatologies from other data. For more information about using the script, see [the documentation](https://github.com/PCMDI/pcmdi_metrics/tree/main/sample_setups/pcmdi_parameter_files/mean_climate/make_clims). The basic use is shown here:   \n",
     "```\n",
     "python pcmdi_compute_climatologies.py \\  \n",

doc/jupyter/Demo/Demo_1b_mean_climate.ipynb

@@ -2563,7 +2563,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Land/sea masks  \n",
+    "### Land/sea masks  \n",
     "Land/Sea masking is required for some regions (e.g. \"land\"). This is controlled by variables `sftlf_filename_template` and `generate_sftlf`. The metrics package expects the land/sea mask files to be located with the model data under a fixed field variable ('fx') with a file name that follows the pattern in `sftlf_filename_template`. The example data does not come with a land/sea mask, so we set `generate_sftlf` to `True` in the basic parameter file to have the PMP generate a land/sea mask where 0 represents ocean and 100 represents land."
    ]
   },

doc/jupyter/Demo/Demo_6_ENSO.ipynb

@@ -13,9 +13,13 @@
    "id": "161973d0",
    "metadata": {},
    "source": [
-    "This notebook provides an overview of running the [ENSO Metrics package](https://github.com/CLIVAR-PRP/ENSO_metrics) through the PMP. More information can be found in the [README]( ). Example parameter files are located in the [PMP sample setups]( ). \n",
+    "This notebook provides an overview of running the [ENSO Metrics package](https://github.com/CLIVAR-PRP/ENSO_metrics) through the PMP.\n",
     "\n",
-    "**Reference**: Planton, Y., E. Guilyardi, A. T. Wittenberg, J. Lee, P. J. Gleckler, T. Bayr, S. McGregor, M. J. McPhaden, S. Power, R. Roehrig, A. Voldoire, 2020: Evaluating El Niño in climate models with the CLIVAR 2020 ENSO metrics package. Bulletin of the American Meteorological Society. [doi: 10.1175/BAMS-D-19-0337.1](https://doi.org/10.1175/BAMS-D-19-0337.1)\n",
+    "**Reference**\n",
+    "\n",
+    "* Planton, Y., E. Guilyardi, A. T. Wittenberg, J. Lee, P. J. Gleckler, T. Bayr, S. McGregor, M. J. McPhaden, S. Power, R. Roehrig, A. Voldoire, 2020: Evaluating El Niño in climate models with the CLIVAR 2020 ENSO metrics package. Bulletin of the American Meteorological Society. [doi: 10.1175/BAMS-D-19-0337.1](https://doi.org/10.1175/BAMS-D-19-0337.1)\n",
+    "\n",
+    "* Lee, J., P. J. Gleckler, M.-S. Ahn, A. Ordonez, P. Ullrich, K. R. Sperber, K. E. Taylor, Y. Y. Planton, E. Guilyardi, P. Durack, C. Bonfils, M. D. Zelinka, L.-W. Chao, B. Dong, C. Doutriaux, C. Zhang, T. Vo, J. Boutte, M. F. Wehner, A. G. Pendergrass, D. Kim, Z. Xue, A. T. Wittenberg, and J. Krasting, 2024: Systematic and Objective Evaluation of Earth System Models: PCMDI Metrics Package (PMP) version 3. Geoscientific Model Development, 17, 3919–3948, [doi: 10.5194/gmd-17-3919-2024](https://doi.org/10.5194/gmd-17-3919-2024)\n",
     "\n",
     "Description for individual metrics can be found at https://github.com/CLIVAR-PRP/ENSO_metrics/wiki."
    ]

doc/jupyter/Demo/Demo_8_extremes.ipynb

@@ -9,7 +9,11 @@
     "\n",
     "This notebook shows users how to run the PMP Extremes metrics driver. This driver can produce annual and seasonal block extremes and return values for temperature or precipitation data.\n",
     "\n",
-    "This notebook should be run in an environment with python, jupyterlab, pcmdi metrics package, and cdat installed. It is expected that you have downloaded the sample data as demonstrated in the download notebook.\n"
+    "This notebook should be run in an environment with python, jupyterlab, pcmdi metrics package, and cdat installed. It is expected that you have downloaded the sample data as demonstrated in the download notebook.\n",
+    "\n",
+    "**Reference**\n",
+    "\n",
+    "* Lee, J., P. J. Gleckler, M.-S. Ahn, A. Ordonez, P. Ullrich, K. R. Sperber, K. E. Taylor, Y. Y. Planton, E. Guilyardi, P. Durack, C. Bonfils, M. D. Zelinka, L.-W. Chao, B. Dong, C. Doutriaux, C. Zhang, T. Vo, J. Boutte, M. F. Wehner, A. G. Pendergrass, D. Kim, Z. Xue, A. T. Wittenberg, and J. Krasting, 2024: Systematic and Objective Evaluation of Earth System Models: PCMDI Metrics Package (PMP) version 3. Geoscientific Model Development, 17, 3919–3948, [doi: 10.5194/gmd-17-3919-2024](https://doi.org/10.5194/gmd-17-3919-2024)"
    ]
   },
   {
@@ -2219,7 +2223,7 @@
    "source": [
     "## Other options\n",
     "\n",
-    "Consult the [README file]() for the extremes metrics to find the full set of user options. "
+    "Consult the [README file](https://github.com/PCMDI/pcmdi_metrics/blob/main/pcmdi_metrics/extremes/README.md) for the extremes metrics to find the full set of user options. "
    ]
   },
   {

doc/jupyter/Demo/Demo_9_seaIceExtent_ivanova.ipynb

@@ -66,17 +66,29 @@
     "**Table of Contents**\n",
     "\n",
     "Note: Links to the sections work best when viewing this notebook via [nbviewer](https://nbviewer.org/github/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_9_seaIceExtent_ivanova.ipynb).\n",
+    "\n",
     "- [1. Demo data](Demo_9_seaIceExtent_ivanova.ipynb#data)\n",
+    "\n",
     "  * [1.1 Model output](Demo_9_seaIceExtent_ivanova.ipynb#mo)\n",
+    "\n",
     "  * [1.2 Reference dataset](Demo_9_seaIceExtent_ivanova.ipynb#ref)\n",
+    "\n",
     "- [2. Sectors](Demo_9_seaIceExtent_ivanova.ipynb#sector)\n",
+    "\n",
     "- [3. Basic Example](Demo_9_seaIceExtent_ivanova.ipynb#basic)\n",
+    "\n",
     "  * [3.1.1 Introducing the PMP parameter file](Demo_9_seaIceExtent_ivanova.ipynb#param)\n",
+    "\n",
     "  * [3.1.2 Introducing the PMP driver file](Demo_9_seaIceExtent_ivanova.ipynb#driver)\n",
+    "\n",
     "  * [3.1.2 Running the PMP sea ice demo](Demo_9_seaIceExtent_ivanova.ipynb#run)\n",
+    "\n",
     "- [4. Working with multiple realizations](Demo_9_seaIceExtent_ivanova.ipynb#multi)\n",
+    "\n",
     "- [5. Working with multiple models](Demo_9_seaIceExtent_ivanova.ipynb#mm)\n",
+    "\n",
     "- [6. Further exploration](Demo_9_seaIceExtent_ivanova.ipynb#further)\n",
+    "\n",
     "- [7. Debugging the LLNL Nimbus binder environment](Demo_9_seaIceExtent_ivanova.ipynb#debug)"
    ]
   },

doc/jupyter/Demo/Demo_9b_seaIce_data_explore.ipynb

@@ -63,20 +63,35 @@
     "**Table of Contents**\n",
     "\n",
     "Note: Links to the sections work best when viewing this notebook via [nbviewer](https://nbviewer.org/github/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_9b_seaIce_data_explore.ipynb).\n",
+    "\n",
     "- [1. Environment setup](Demo_9b_seaIce_data_explore.ipynb#env)\n",
+    "\n",
     "- [2. Model Data](Demo_9b_seaIce_data_explore.ipynb#model)\n",
+    "\n",
     "  * [2.1 Load data](Demo_9b_seaIce_data_explore.ipynb#model_load)\n",
+    "\n",
     "    - [2.1.1 Open dataset](Demo_9b_seaIce_data_explore.ipynb#model_open_ds)\n",
+    "\n",
     "    - [2.1.2 Visualize the data](Demo_9b_seaIce_data_explore.ipynb#model_vis)\n",
+    "\n",
     "  * [2.2 Sea ice extent](Demo_9b_seaIce_data_explore.ipynb#model_sie)\n",
+    "\n",
     "- [3. Reference Data](Demo_9b_seaIce_data_explore.ipynb#obs)\n",
+    "\n",
     "  * [3.1 Load data](Demo_9b_seaIce_data_explore.ipynb#obs_load)\n",
+    "\n",
     "    - [3.1.1 Open Reference Dataset for Arctic](Demo_9b_seaIce_data_explore.ipynb#obs_open_ds1)\n",
+    "\n",
     "    - [3.1.2 Open Reference Dataset for Antartica](Demo_9b_seaIce_data_explore.ipynb#obs_open_ds2)\n",
+    "\n",
     "  * [3.2 Sea ice extent](Demo_9b_seaIce_data_explore.ipynb#obs_sie)\n",
+    "\n",
     "- [4. Diagnostics: Climatology Annual Cycle](Demo_9b_seaIce_data_explore.ipynb#diags)\n",
+    "\n",
     "- [5. Evaluation Metrics](Demo_9b_seaIce_data_explore.ipynb#metric)\n",
+    "\n",
     "  * [5.1 Mean Square Error (Annual Mean)](Demo_9b_seaIce_data_explore.ipynb#mse)\n",
+    "\n",
     "  * [5.2 Temporal Mean Square Error (Annual Cycle)](Demo_9b_seaIce_data_explore.ipynb#tmse)\n",
     "\n",
     "---\n",