minor mean climate edits

docs/_sources/mean-climate.rst.txt

@@ -9,18 +9,24 @@ Overview
 
 The mean climate summary statistics are some of the most routine analysis available from the PMP. At the same time, because of the number of options available they do require some preparation in advance of the analysis, including:
 
-* Setting observational climatologies
+* Setting-up observational climatologies
 
 * Preparation of model climatologies 
 
 * Construction of an input parameter file 
 
+
+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 database of `observational climatologies <https://github.com/PCMDI/PCMDIobs-cmor-tables/blob/master/catalogue/pcmdiobs2_clims_byVar_catalogue_v20201210.json>`_ 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. A subset of this database is available via the demo data made available for the PMP tutorials via a `jupyter notebook demo <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_0_download_data.ipynb>`_. Once you have downloaded this demo data you can interactively run the mean climate and other demos. 
+A 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. A subset of this database is available via the demo data made available for the PMP tutorials via a `jupyter notebook demo <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_0_download_data.ipynb>`_. Once you have downloaded this demo data you can interactively run the mean climate and other demos. 
+
+The PMP's mean climate summary statistics can be applied many fields and in most cases there is more than one reference data set available. To accomodate this, as noted above the observational climatologies used by the PMP are 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'. Note: To simplify the use of the different options in the mean climate, the mean_climate_driver.py (see below) expects to be pointed to such a JSON file that summarizes the database. Currently, if a user wants to add additional observational data this can be done by including it in the JSON cataloge. Note: this most be done carefully to ensure the file retains compliant JSON structure. 
+
 
-The `mean climate notebook <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_1_mean_climate.ipynb>`_ provides a series of examples that demonstrate the options available. 
 
 Preparation of model climatologies
 ##################################
@@ -40,24 +46,23 @@ or as a combination of an input parameter file and the command line, e.g.: ::
 
  mean_climate_driver.py -p basic_param.py --vars rlut pr 
 
-where the list of variables to run the analysis on includes the variables 'rlut' (outgoing TOA longwave radiation) and 'pr' (precipitation). The following parameters need to be set by the user either in a parameter file or on the command line: 
+where the list of variables (vars) to run the analysis on includes 'rlut' (outgoing TOA longwave radiation) and 'pr' (precipitation). The following parameters need to be set by the user either in a parameter file or on the command line: 
 
-* test_data_set
-* vars
-* reference_data_set
-* target_grid
-* regrid_tool
-* filename_template
-* test_data_path
-* reference_data_path
-* metric_output_path
+* **vars**: a python list of variables to apply the summary statistics, e.g., ['pr', 'rlut', 'tas']
+* **test_data_set**: a python list of runs or models, e.g., ['ACCESS-1-0', 'CESM1']
+* **filename_template**: template that is applicable for the runs in test_data_set, e.g., "CMIP5.historical.%(model_version).r1i1p1.mon.%(variable).198101-200512.AC.v20190225.nc" where "model_version" and "variable" will include the lists in test_data_set and vars.
+* **test_data_path**: the path/template where the test_data resides, e.g.: 
+* **reference_data_set**: a python list that specifies 'default', 'alternate1', 'alternate2' or 'all', e.g., ['default']
+* **reference_data_path**: the root path to the PMP climatology database
+* **target_grid**:
+* **regrid_tool**: options include 
+* **metric_output_path**:
 
 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. 
 
 
 In addition to the minimum set of parameters noted above, the following additional options than can be controlled for the mean climate:
 
-* Select regridding method option
 * Define a different set of regions to compute the statistics.
 * Provide or estimate a land-sea mask 
 * Define regional masking (e.g., global land-only, global ocean-only,tropical land)

docs/mean-climate.html

@@ -174,14 +174,15 @@
 <h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
 <p>The mean climate summary statistics are some of the most routine analysis available from the PMP. At the same time, because of the number of options available they do require some preparation in advance of the analysis, including:</p>
 <ul class="simple">
-<li><p>Setting observational climatologies</p></li>
+<li><p>Setting-up observational climatologies</p></li>
 <li><p>Preparation of model climatologies</p></li>
 <li><p>Construction of an input parameter file</p></li>
 </ul>
+<p>Each of these steps are included in the <a class="reference external" href="https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_1_mean_climate.ipynb">mean climate notebook</a> along with a series of examples that demonstrate the options. These steps are also summarized below.</p>
 <div class="section" id="observational-climatologies">
 <h3>Observational climatologies<a class="headerlink" href="#observational-climatologies" title="Permalink to this headline">¶</a></h3>
-<p>A database of <a class="reference external" href="https://github.com/PCMDI/PCMDIobs-cmor-tables/blob/master/catalogue/pcmdiobs2_clims_byVar_catalogue_v20201210.json">observational climatologies</a> is available to users of the PMP. To obtain this, please contact the PMP user group (<a class="reference external" href="mailto:pcmdi-metrics&#37;&#52;&#48;llnl&#46;gov">pcmdi-metrics<span>&#64;</span>llnl<span>&#46;</span>gov</a>) and you will be promptly provided with the database. A subset of this database is available via the demo data made available for the PMP tutorials via a <a class="reference external" href="https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_0_download_data.ipynb">jupyter notebook demo</a>. Once you have downloaded this demo data you can interactively run the mean climate and other demos.</p>
-<p>The <a class="reference external" href="https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_1_mean_climate.ipynb">mean climate notebook</a> provides a series of examples that demonstrate the options available.</p>
+<p>A database of <a class="reference external" href="https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_0_download_data.ipynb">observational climatologies is available to users of the PMP. To obtain this, please contact the PMP user group (pcmdi-metrics&#64;llnl.gov) and you will be promptly provided with the database. A subset of this database is available via the demo data made available for the PMP tutorials via a `jupyter notebook demo</a>. Once you have downloaded this demo data you can interactively run the mean climate and other demos.</p>
+<p>The PMP’s mean climate summary statistics can be applied many fields and in most cases there is more than one reference data set available. To accomodate this, as noted above the observational climatologies used by the PMP are managed via <a class="reference external" href="https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/pcmdiobs2_clims_byVar_catalogue_v20201210.json">a simple catalogue in the form of a JSON file</a>. For many of the variables there are ‘default’ and ‘alternate1’ datasets and for some there is also an ‘alternate2’. Note: To simplify the use of the different options in the mean climate, the mean_climate_driver.py (see below) expects to be pointed to such a JSON file that summarizes the database. Currently, if a user wants to add additional observational data this can be done by including it in the JSON cataloge. Note: this most be done carefully to ensure the file retains compliant JSON structure.</p>
 </div>
 <div class="section" id="preparation-of-model-climatologies">
 <h3>Preparation of model climatologies<a class="headerlink" href="#preparation-of-model-climatologies" title="Permalink to this headline">¶</a></h3>
@@ -197,22 +198,21 @@ <h3>Construction of an input paramater file<a class="headerlink" href="#construc
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mean_climate_driver</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">p</span> <span class="n">basic_param</span><span class="o">.</span><span class="n">py</span> <span class="o">--</span><span class="nb">vars</span> <span class="n">rlut</span> <span class="n">pr</span>
 </pre></div>
 </div>
-<p>where the list of variables to run the analysis on includes the variables ‘rlut’ (outgoing TOA longwave radiation) and ‘pr’ (precipitation). The following parameters need to be set by the user either in a parameter file or on the command line:</p>
+<p>where the list of variables (vars) to run the analysis on includes ‘rlut’ (outgoing TOA longwave radiation) and ‘pr’ (precipitation). The following parameters need to be set by the user either in a parameter file or on the command line:</p>
 <ul class="simple">
-<li><p>test_data_set</p></li>
-<li><p>vars</p></li>
-<li><p>reference_data_set</p></li>
-<li><p>target_grid</p></li>
-<li><p>regrid_tool</p></li>
-<li><p>filename_template</p></li>
-<li><p>test_data_path</p></li>
-<li><p>reference_data_path</p></li>
-<li><p>metric_output_path</p></li>
+<li><p><strong>vars</strong>: a python list of variables to apply the summary statistics, e.g., [‘pr’, ‘rlut’, ‘tas’]</p></li>
+<li><p><strong>test_data_set</strong>: a python list of runs or models, e.g., [‘ACCESS-1-0’, ‘CESM1’]</p></li>
+<li><p><strong>filename_template</strong>: template that is applicable for the runs in test_data_set, e.g., “CMIP5.historical.%(model_version).r1i1p1.mon.%(variable).198101-200512.AC.v20190225.nc” where “model_version” and “variable” will include the lists in test_data_set and vars.</p></li>
+<li><p><strong>test_data_path</strong>: the path/template where the test_data resides, e.g.:</p></li>
+<li><p><strong>reference_data_set</strong>: a python list that specifies ‘default’, ‘alternate1’, ‘alternate2’ or ‘all’, e.g., [‘default’]</p></li>
+<li><p><strong>reference_data_path</strong>: the root path to the PMP climatology database</p></li>
+<li><p><strong>target_grid</strong>:</p></li>
+<li><p><strong>regrid_tool</strong>: options include</p></li>
+<li><p><strong>metric_output_path</strong>:</p></li>
 </ul>
 <p>The output of the mean climate summary statistics are saved in a JSON file. <a class="reference external" href="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">An example result</a> 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.</p>
 <p>In addition to the minimum set of parameters noted above, the following additional options than can be controlled for the mean climate:</p>
 <ul class="simple">
-<li><p>Select regridding method option</p></li>
 <li><p>Define a different set of regions to compute the statistics.</p></li>
 <li><p>Provide or estimate a land-sea mask</p></li>
 <li><p>Define regional masking (e.g., global land-only, global ocean-only,tropical land)</p></li>