update and clean up

docs/metrics_mean-clim.rst

@@ -5,7 +5,10 @@ Mean Climate
 Overview
 ========
 
-The mean climate summary statistics are the most routine analysis available from the PMP. Because they are quasi-operationally applied to large numbers of simulations and under different conditions, the current mode of opertation is fairly general. Before it can be applied some prepration is needed including: 
+The mean climate summary statistics are the most routine analysis available from the PMP.
+Because they are quasi-operationally applied to large numbers of simulations and under 
+different conditions, the current mode of opertation is fairly general. 
+Before it can be applied some prepration is needed including: 
 
 * Setting-up observational climatologies
 
@@ -14,23 +17,47 @@ The mean climate summary statistics are the most routine analysis available from
 * Construction of an input parameter file to run the desired operations 
 
 
-Each of these steps are included in the `mean climate notebook <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_1_mean_climate.ipynb>`_ along with a series of examples that demonstrate the options. These steps are also summarized below.
+Each of these steps are included in the 
+`mean climate notebook <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_1_mean_climate.ipynb>`_ 
+along with a series of examples that demonstrate the options. 
+These steps are also summarized below.
 
 
 Observational climatologies
 ###########################
 
-A subset of the observational climatologies used for the PMP's mean climate metrics is available via a `jupyter notebook demo <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_0_download_data.ipynb>`_. Once you have run this demo or downloaded this demo data you can interactively run the mean climate and other demos. The complete database of `observational climatologies is available to users of the PMP. To obtain this, please contact the PMP user group ([email protected]) and you will be promptly provided with the database.
-
-The PMP's mean climate summary statistics can be applied to many fields and in most cases there is more than one reference data set available. To accomodate this, the observational climatologies used by the PMP are managed via `a simple catalogue in the form of a JSON file <https:https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/pcmdiobs2_clims_byVar_catalogue_v20201210.json>`_. For many of the variables there are 'default' and 'alternate1' datasets and for some there is also an 'alternate2'. To simplify the use of the different options in the mean climate, the mean_climate_driver.py (see below) expects to be pointed to observational catalogue. Currently, if a user wants to add additional observational data this can be done by including it in the JSON cataloge. However, this most be done carefully to ensure the file retains JSON compliant structure. 
+A subset of the observational climatologies used for the PMP's 
+mean climate metrics is available via a `jupyter notebook demo <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_0_download_data.ipynb>`_.
+Once you have run this demo or downloaded this demo data you can interactively 
+run the mean climate and other demos. 
+The complete database of observational climatologies is available to users of the PMP. 
+To obtain this, please contact the PMP user group ([email protected]) 
+and you will be promptly provided with the database.
+
+The PMP's mean climate summary statistics can be applied to many fields and 
+in most cases there is more than one reference data set available. 
+To accomodate this, the observational climatologies used by the PMP a
+re managed via `a simple catalogue in the form of a JSON file <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/pcmdiobs2_clims_byVar_catalogue_v20201210.json>`_. 
+For many of the variables there are 'default' and 'alternate1' 
+datasets and for some there is also an 'alternate2'. 
+To simplify the use of the different options in the mean climate, 
+the mean_climate_driver.py (see below) expects to be pointed to observational catalogue. 
+Currently, if a user wants to add additional observational data this can be done by 
+including it in the JSON cataloge. However, this most be done carefully to ensure 
+the file retains JSON compliant structure. 
 
 A recent observational climatology catalogue is included as part of the PMP as a default, so it does not need to be explicitly idenified when using the mean_climate_driver.py (unless the catalogue has been modified to include new observations). However, as described below, the user must provide the base path to the observational database. As indicated in the catalogue, the actual database does incorporate futher directory structure and defined filenames which should not be modified. If changes are made to the catalogue, this can be done with input parameter settings (below) using the "custom_observations" option. 
 
 
 Preparation of model climatologies
 ##################################
 
-Sample model climatologies are available as part of the PMP demo database noted above and are used for the mean climate notebook. However, if a user wants to create and use their own model climatologies with the PMP a simple example is provide in a stand alone `climatology notebook <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_1a_compute_climatologies.ipynb>`_, via the `mean climate metrics notebook <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_1_mean_climate.ipynb>`_, or the `PMP github repository <https://github.com/PCMDI/pcmdi_metrics/tree/master/sample_setups/pcmdi_parameter_files/mean_climate/make_clims>`_. 
+Sample model climatologies are available as part of the PMP demo database noted above 
+and are used for the mean climate notebook. However, if a user wants to create and use 
+their own model climatologies with the PMP a simple example is provide in a stand 
+alone `climatology notebook <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_1a_compute_climatologies.ipynb>`_, 
+via the `mean climate metrics notebook <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_1_mean_climate.ipynb>`_, 
+or the `PMP github repository <https://github.com/PCMDI/pcmdi_metrics/tree/master/sample_setups/pcmdi_parameter_files/mean_climate/make_clims>`_. 
 
 
 Construction of an input paramater file
@@ -62,7 +89,6 @@ In addition to the above required input parameters, if the default cataolgue of
  custom_observations = './pcmdiobs2_clims_byVar_catalogue_v20200615.json'
 
 
-
 The output of the mean climate summary statistics are saved in a JSON file. `An example result <https://github.com/PCMDI/pcmdi_metrics/blob/master/sample_setups/jsons/mean_climate/CMIP5/historical/v20190724/tas/ACCESS1-0.tas.CMIP5.historical.regrid2.2p5x2p5.v20190724.json>`_ demonstrates that multiple statistics are computed for different conditions including regions and seasons. The resulting JSON files include the data, software and hardware information on how the summary statistics. 
 
 

docs/pmp-using-cdp-guide.rst

@@ -1,3 +1,4 @@
+*******************
 PMP using CDP Guide
 *******************
 

docs/resources.rst

@@ -1,12 +1,13 @@
 .. _metrics-overview:
 
-*****************
+*********
 Resources
-*****************
+*********
 
 .. toctree::
  :maxdepth: 1
 
+ pmp-using-cdp-guide
  pmpparser
 
 

docs/subdaily-precipitation.rst

@@ -1,8 +1,8 @@
 .. _subdaily-precipitation:
 
-*****************
+***********************
 Sub-daily precipitation
-*****************
+***********************
 
 Overview
 ========

docs/supporting-data.rst

@@ -1,6 +1,6 @@
-*****************
+********************************************
 Retrieving data for demos and use of the PMP
-*****************
+********************************************
 
 
 Sample model and observational data are provided via a `jupyter notebook demo <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_0_download_data.ipynb>`_. This is the first of multiple PMP demos. It enables a user to download all sample data before running the other demos that provide interactive examples of the different summary statistics provided by the PMP. More info is available for `preparing to run these notebooks <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/README.md>`_.