disc of mean options

docs/Supporting-data.html

@@ -157,8 +157,7 @@
  <div class="section" id="retrieving-data-for-demos-and-use-of-the-pmp">
 <h1>Retrieving data for demos and use of the PMP<a class="headerlink" href="#retrieving-data-for-demos-and-use-of-the-pmp" title="Permalink to this headline">¶</a></h1>
 <p>Sample model and observational data are provided 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>. 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 <a class="reference external" href="https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/README.md">preparing to run these notebooks</a>.</p>
-<p>For users that are unfamiliar with Jupyter notebooks or just want to download the sample data without interactively running the demo, you can download the data by launching python from a PMP environment created from conda.</p>
-<p>you can then enter the following</p>
+<p>For users that are unfamiliar with Jupyter notebooks or just want to download the sample data without interactively running the demo, you can download the data by launching python from a PMP environment created from conda. You can then enter the following form the python command prompt</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">requests</span>
 <span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;https://pcmdiweb.llnl.gov/pss/pmpdata/cmec_tutorial_files.txt&quot;</span><span class="p">)</span>
 <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s2">&quot;data_files.txt&quot;</span><span class="p">,</span><span class="s2">&quot;wb&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>

docs/_sources/Supporting-data.rst.txt

@@ -5,9 +5,7 @@ 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>`_. 
 
-For users that are unfamiliar with Jupyter notebooks or just want to download the sample data without interactively running the demo, you can download the data by launching python from a PMP environment created from conda. 
-
-you can then enter the following :: 
+For users that are unfamiliar with Jupyter notebooks or just want to download the sample data without interactively running the demo, you can download the data by launching python from a PMP environment created from conda. You can then enter the following form the python command prompt :: 
 
  import requests
  r = requests.get("https://pcmdiweb.llnl.gov/pss/pmpdata/cmec_tutorial_files.txt")

docs/_sources/index.rst.txt

@@ -14,7 +14,7 @@ The PMP is used to provide "quick-look" objective comparisons of Earth System Mo
 PCMDI uses the PMP to produce `quick-look simulation summaries across generations of CMIP <https://cmec.llnl.gov/results/physical.html>`_
 
 
-The PMP expects model data to be `CF-compliant <http:https://cfconventions.org/>`_, otherwise, to successfully use the package may require some input data "conditioning". 
+The PMP expects model data to be `CF-compliant <http:https://cfconventions.org/>`_, otherwise, to successfully use the package may require some input data conditioning. 
 
 A suite of demo scripts and interactive Jupyter notebooks are provided with this documentation. 
 

docs/_sources/mean-climate.rst.txt

@@ -7,13 +7,13 @@ Mean Climate
 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:
+The mean climate summary statistics are some of the most routine analysis available from the PMP. Because it is 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 for the following: 
 
 * Setting-up observational climatologies
 
-* Preparation of model climatologies 
+* Construction of model climatologies 
 
-* Construction of an input parameter file 
+* 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.
@@ -22,9 +22,11 @@ Each of these steps are included in the `mean climate notebook <https://github.c
 Observational climatologies
 ###########################
 
-A database of `observational climatologies is available to users of the PMP. To obtain this, please contact the PMP user group (pcmdi-metrics@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 <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 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 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 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://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. 
+
+The latest observational climatology catalogue is included as part of the PMP 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 path to the observational database is located. As indicated in the catalogue, the actual database does incorporate a directory structure and defined filenames - these should not be modified. 
 
 
 
@@ -50,12 +52,12 @@ where the list of variables (vars) to run the analysis on includes 'rlut' (outgo
 
 * **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.
+* **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 be analyzed for each of the entries 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 
+* **reference_data_path**: the root path to the observational climatology database, e.g., '~/demo_data/PCMDIobs2_clims/'
+* **target_grid**: '2.5x2.5' or an actual cdms2 grid object
+* **regrid_tool**: options include 'esmf' and 'regrid2' 
 * **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. 

docs/index.html

@@ -158,7 +158,7 @@ <h1>PCMDI Metrics Package (PMP)<a class="headerlink" href="#pcmdi-metrics-packag
 <p><em>The content of this site is currently being expanded to include examples for all of the PMP summary statistic functionality</em></p>
 <p>The PMP is used to provide “quick-look” objective comparisons of Earth System Models (ESMs) with one another and available observations. Results are produced in the context of all model simulations contributed to CMIP6 and earlier CMIP phases. Currently, the comparisons emphasize metrics of large- to global-scale annual cycle and both tropcial and extra-tropical modes of variability. Ongoing work in v1.x development branches include established statistics for ENSO, MJO, regional monsoons, and high frequency characteristics of simulated precipitation.</p>
 <p>PCMDI uses the PMP to produce <a class="reference external" href="https://cmec.llnl.gov/results/physical.html">quick-look simulation summaries across generations of CMIP</a></p>
-<p>The PMP expects model data to be <a class="reference external" href="http:https://cfconventions.org/">CF-compliant</a>, otherwise, to successfully use the package may require some input data “conditioning”.</p>
+<p>The PMP expects model data to be <a class="reference external" href="http:https://cfconventions.org/">CF-compliant</a>, otherwise, to successfully use the package may require some input data conditioning.</p>
 <p>A suite of demo scripts and interactive Jupyter notebooks are provided with this documentation.</p>
 <div class="toctree-wrapper compound">
 <p class="caption"><span class="caption-text">Contents:</span></p>

docs/mean-climate.html

@@ -172,17 +172,18 @@
 <span id="using-the-package"></span><h1>Mean Climate<a class="headerlink" href="#mean-climate" title="Permalink to this headline">¶</a></h1>
 <div class="section" id="overview">
 <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>
+<p>The mean climate summary statistics are some of the most routine analysis available from the PMP. Because it is 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 for the following:</p>
 <ul class="simple">
 <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>
+<li><p>Construction of model climatologies</p></li>
+<li><p>Construction of an input parameter file to run the desired operations</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/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>
+<p>A subset of the observational climatologies used for the PMP’s mean climate metrics is available 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 run this demo or downloaded this demo data you can interactively run the mean climate and other demos. The complete database of <a href="#id1"><span class="problematic" id="id2">`</span></a>observational climatologies 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.</p>
+<p>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 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’. 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.</p>
+<p>The latest observational climatology catalogue is included as part of the PMP 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 path to the observational database is located. As indicated in the catalogue, the actual database does incorporate a directory structure and defined filenames - these should not be modified.</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>
@@ -202,12 +203,12 @@ <h3>Construction of an input paramater file<a class="headerlink" href="#construc
 <ul class="simple">
 <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>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 be analyzed for each of the entries 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>reference_data_path</strong>: the root path to the observational climatology database, e.g., ‘~/demo_data/PCMDIobs2_clims/’</p></li>
+<li><p><strong>target_grid</strong>: ‘2.5x2.5’ or an actual cdms2 grid object</p></li>
+<li><p><strong>regrid_tool</strong>: options include ‘esmf’ and ‘regrid2’</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>