Merge branch 'main' into 405_durack1_addESGF2-USLogoToSeaIceNotebook

PCMDI · Jan 31, 2024 · d91a47f · d91a47f
2 parents 16e81b7 + 3acf0f9
commit d91a47f
Show file tree

Hide file tree

Showing 8 changed files with 44 additions and 21 deletions.
diff --git a/docs/metrics.rst b/docs/metrics.rst
@@ -12,11 +12,11 @@ A suite of demo scripts and interactive Jupyter notebooks are provided with `thi
  :maxdepth: 1
 
  metrics_mean-clim
- subdaily-precipitation
- metrics_mov
  metrics_enso
+ metrics_mov
  metrics_mjo
  metrics_monsoon
  metrics_ext
  metrics_precip-variability
- metrics_precip-distribution
+ metrics_precip-distribution
+ metrics_subdaily-precipitation
diff --git a/docs/metrics_enso.rst b/docs/metrics_enso.rst
@@ -20,7 +20,7 @@ Demo
 * `PMP demo Jupyter notebook`_
 
 Results
-=========
+=======
 * `Interactive graphics for PMP-calculated ENSO Metrics`_
 * `Description for included metrics`_
 * `Description for the results`_

diff --git a/docs/metrics_mean-clim.rst b/docs/metrics_mean-clim.rst
@@ -22,6 +22,11 @@ Each of these steps is included in the
 along with a series of examples that demonstrate the options. 
 These steps are also summarized below.
 
+Demo
+====
+* `PMP demo Jupyter notebook1a`_ (Compute climatologies)
+* `PMP demo Jupyter notebook1b`_ (Run mean climate driver)
+
 
 Observational climatologies
 ###########################
@@ -102,3 +107,6 @@ In addition to the minimum set of parameters noted above, the following **additi
 * **save_test_clims** Select to save (or not) interpolated climatologies including masking
 * **case_id** Save JSON and netCDF files into a subdirectory so that results from multiple tests can be readily organized
 
+.. _PMP demo Jupyter notebook1a: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_1a_compute_climatologies.ipynb
+.. _PMP demo Jupyter notebook1b: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_1b_mean_climate.ipynb
+
diff --git a/docs/metrics_monsoon.rst b/docs/metrics_monsoon.rst
@@ -11,9 +11,13 @@ The PMP currently can be used to produce baseline metrics on the overall evoluti
 
 These evolution results are based on the work of Sperber and Annamalai (2014). Climatological pentads of precipitation in observations and CMIP5 for six monsoon-related domains (AIR: All-India Rainfall, AUS: Australian Monsoon, GoG: Gulf of Guinea, NAM: North American Monsoon, SAM: South American Monsoon, and Sahel). In the Northern Hemisphere the 73 climatological pentads run from January-December, while in the Southern Hemisphere the climatological pentads run from July-June. For each domain the precipitation is accumulated at each subsequent pentad and then divided by the total precipitation to give the fractional accumulation of precipitation as a function of pentad. Except for GoG, onset (decay) of monsoon occurs for a fractional accumulation of 0.2 (0.8). Between these fractional accumulations the accumulation of precipitation is nearly linear as the monsoon season progresses.
 
-
+Demo
+====
+* `PMP demo Jupyter notebook`_
 
 References
 ==========
+* Sperber, K.R. and Annamalai, H., 2014. The use of fractional accumulated precipitation for the evaluation of the annual cycle of monsoons. Climate Dynamics, 43, 3219-3244, doi:10.1007/s00382-014-2099-3
+
+.. _PMP demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_2b_monsoon_sperber.ipynb
 
-Sperber, K.R. and Annamalai, H., 2014. The use of fractional accumulated precipitation for the evaluation of the annual cycle of monsoons. Climate Dynamics, 43, 3219-3244, doi:10.1007/s00382-014-2099-3
diff --git a/docs/metrics_precip-distribution.rst b/docs/metrics_precip-distribution.rst
@@ -13,7 +13,7 @@ Demo
 In preparation
 
 Example parameter files
-======================
+=======================
 A set of example parameter files for models and observations can be viewed at `this link`_.
 
 Required data sets 

diff --git a/docs/metrics_precip-variability.rst b/docs/metrics_precip-variability.rst
@@ -13,7 +13,7 @@ Demo
 * `PMP demo Jupyter notebook`_
 
 Example parameter files
-======================
+=======================
 A set of example parameter files for models and observations can be viewed at `this link`_.
 
 Required data sets 

diff --git a/docs/subdaily-precipitation.rst → docs/metrics_subdaily-precipitation.rst b/docs/subdaily-precipitation.rst → docs/metrics_subdaily-precipitation.rst
@@ -11,14 +11,17 @@ The PMP can be used to compare observed and simulated sub-daily precipitation, i
 
 Analysis of higher frequency data often includes multiple stages of processing. `The flow diagram of the PMP's sub-daily precipitation <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/Diurnal%20Cycle%20Diagram.pdf>`_ shows that is the case here. Each of the steps highlighted in the flow diagram are included in `the diurnal cycle and intermittency Jupyter notebook demo <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_3_diurnal_cycle.ipynb>`_. 
 
+Demo
+====
+* `PMP demo Jupyter notebook`_
 
 References
 ==========
+* Covey, C, PJ Gleckler, C Doutriaux, DN Williams, A Dai, J Fasullo, K Trenberth, and A Berg. 2016. ”Metrics for the diurnal cycle of precipitation: Toward routine benchmarks for climate models.” Journal of Climate 29(12): 4461–4471, https://doi.org/10.1175/JCLI-D-15-0664.1
+* Covey, C, C Doutriaux, PJ Gleckler, KE Taylor, KE Trenberth, and Y Zhang. 2018. “High-frequency intermittency in observed and model-simulated precipitation.” Geophysical Research Letters 45(22): 12514–12522, https://doi.org/10.1029/2018GL078926
+* Dai, A. 2006. “Precipitation characteristics coupled climate models.” Journal of Climate 19(18): 4605–4630, https://doi.org/10.1175/JCLI3884.1
+* Trenberth, KE, Y Zhang, and M Gehne. 2017. ”Intermittency in precipitation: Duration, frequency, intensity, and amounts using hourly data.” Journal of Hydrometeorology 18(5): 1393–1412, https://doi.org/10.1175/JHM-D-16-0263.1
 
-Covey, C, PJ Gleckler, C Doutriaux, DN Williams, A Dai, J Fasullo, K Trenberth, and A Berg. 2016. ”Metrics for the diurnal cycle of precipitation: Toward routine benchmarks for climate models.” Journal of Climate 29(12): 4461–4471, https://doi.org/10.1175/JCLI-D-15-0664.1
 
-Covey, C, C Doutriaux, PJ Gleckler, KE Taylor, KE Trenberth, and Y Zhang. 2018. “High-frequency intermittency in observed and model-simulated precipitation.” Geophysical Research Letters 45(22): 12514–12522, https://doi.org/10.1029/2018GL078926
 
-Dai, A. 2006. “Precipitation characteristics coupled climate models.” Journal of Climate 19(18): 4605–4630, https://doi.org/10.1175/JCLI3884.1
-
-Trenberth, KE, Y Zhang, and M Gehne. 2017. ”Intermittency in precipitation: Duration, frequency, intensity, and amounts using hourly data.” Journal of Hydrometeorology 18(5): 1393–1412, https://doi.org/10.1175/JHM-D-16-0263.1
+.. _PMP demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_3_diurnal_cycle.ipynb
diff --git a/pcmdi_metrics/sea_ice/README.md b/pcmdi_metrics/sea_ice/README.md
@@ -2,13 +2,15 @@
 
 ## Summary
 
+The PCMDI Metrics Package (PMP) sea ice driver produces metrics that compare modeled and observed sea ice extent as shown in Ivanova (2016). These metrics are generated for total sea ice extent in eight preset sectors. They can be compared across models, realizations, and regions. 
+
 ## Demo
 
-* Link to notebook
+* [Sea ice demo notebook](https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_9_seaIceExtent_ivanova.ipynb)
 
 ## Inputs
 
-### Sectors
+The sea ice driver uses monthly mean sea ice concentration and grid area data to generate sea ice extent metrics. An unlimited number of test data sets (typically model data) may be provided if file names follow a common template. A single reference data set is required, which is typically a observational data set or a model control run. For best results, all data files should contain latitude and longitude variables that are named "latitude" and "longitude" or "lat" and "lon". Data may use an irregular grid if latitude and longitude variables are included, preferably as additional coordinates. If multiple realizations of a model are provided, all realizations must use the same grid. See the Parameters section for more details about inputs.
 
 ## Run
 
@@ -28,20 +30,26 @@ sea_ice_driver.py -p parameter_file.py --msyear 1991 --meyear 2020
 
 The driver produces a JSON file containing mean square error metrics for all input models and realizations relative to the reference data set. It also produces a bar chart displaying these metrics.
 
+### Sectors
+
+The metrics results are provided for eight different geographic regions. In the Northern Hemisphere there are the Arctic, North Pacific, North Atlantic, and Central Arctic regions. In the Southern Hemisphere there are the Antarctic, South Pacific, South Atlantic, and Indian Ocean regions. The region definitions can be found in [Ivanova (2016)](https://doi.org/10.1175/JCLI-D-16-0026.1).
+
 ## Parameters
 
+A [demo parameter file](https://github.com/PCMDI/pcmdi_metrics/blob/405_sic_ao/pcmdi_metrics/sea_ice/param/parameter_file.py) is provided in the sea ice code. 
+
 * **case_id**: Save JSON and figure files into this subdirectory so that results from multiple tests can be readily organized.
 * **test_data_set**: List of model names.
-* **realization**: List of realizations.
+* **realization**: List of realizations or "*" to use all realizations.
 * **test_data_path**: File path to directory containing model/test data.
-* **filename_template**: File name template for test data, e.g., "CMIP5.historical.%(model_version).r1i1p1.mon.%(variable).19810-200512.AC.v2019022512.nc" where "model_version" and "variable" will be analyzed for each of the entries in test_data_set and vars.
+* **filename_template**: File name template for test data, e.g., "%(variable)\_SImon_%(model_version)_historical_r1i2p2f1_gr_201001-201112.nc" where "model_version" and "variable" will be analyzed for each of the entries in test_data_set and vars.
 * **var**: Name of model sea ice variable
 * **msyear**: Start year for test data set.
 * **meyear**: End year for test data set.
 * **ModUnitsAdjust**: Factor to convert model sea ice data to fraction of 1. Uses format (flag (bool), operation (str), value (float)). Operation can be "add", "subtract", "multiply", or "divide". For example, use (True, 'multiply', 1e-2) to convert from percent concentration to decimal concentration.
 * **area_template**: File path of model grid area data.
 * **area_var**: Name of model area variable, e.g. "areacello"
-* **AreaUnitsAdjust**: Factor to convert model area data to units of km2. Uses format (flag (bool), operation (str), value (float)). Operation can be "add", "subtract", "multiply", or "divide". For example, use (True, 'multiply', 1e6) to convert from m2 to km2.
+* **AreaUnitsAdjust**: Factor to convert model area data to units of km2. Uses format (flag (bool), operation (str), value (float)). Operation can be "add", "subtract", "multiply", or "divide". For example, use (True, 'multiply', 1e-6) to convert from m2 to km2.
 * **metrics_output_path**: Directory path for metrics output in JSON files, e.g., '~/demo_data/PMP_metrics/'. The %(case_id) variable can be used here. If exists, should be empty before run.
 * **reference_data_path_nh**: The reference data file path for the northern hemisphere. If data is global, provide same path for nh and sh.
 * **reference_data_path_sh**: The reference data file path for the southern hemisphere. If data is global, provide same path for nh and sh.
@@ -50,12 +58,12 @@ The driver produces a JSON file containing mean square error metrics for all inp
 * **osyear**: Start year for reference data set.
 * **oeyear**: End year for reference data set.
 * **obs_var**: Name of reference sea ice variable.
-* **ObsAreaUnitsAdjust**: Factor to convert model area data to units of km2. Uses format (flag (bool), operation (str), value (float)). Operation can be "add", "subtract", "multiply", or "divide". For example, use (True, 'multiply', 1e6) to convert from m2 to km2.
+* **ObsAreaUnitsAdjust**: Factor to convert model area data to units of km2. Uses format (flag (bool), operation (str), value (float)). Operation can be "add", "subtract", "multiply", or "divide". For example, use (True, 'multiply', 1e-6) to convert from m2 to km2.
 * **obs_area_template**: File path of grid area data. If unavailalbe, skip and use "obs_cell_area".
 * **obs_area_var**: Name of reference area variable, if available. If unavailable, skip and use "obs_cell_area".
-* **obs_cell_area**: For equal area grids, the area of a single grid cell in units of km2.
+* **obs_cell_area**: For equal area grids, the area of a single grid cell in units of km2. Only required if obs area file is not available.
 
 
 ## Reference
 
-Ivanova, D. P., P. J. Gleckler, K. E. Taylor, P. J. Durack, and K. D. Marvel, 2016: Moving beyond the Total Sea Ice Extent in Gauging Model Biases. J. Climate, 29, 8965–8987, https://doi.org/10.1175/JCLI-D-16-0026.1. 
+Ivanova, D. P., P. J. Gleckler, K. E. Taylor, P. J. Durack, and K. D. Marvel, 2016: Moving beyond the Total Sea Ice Extent in Gauging Model Biases. J. Climate, 29, 8965–8987, https://doi.org/10.1175/JCLI-D-16-0026.1.