Merge branch 'main' into ao_sic_parallel

.gitattributes

@@ -0,0 +1,7 @@
+doc/jupyter/Demo/* linguist-vendored
+doc/jupyter/Jsons/* linguist-vendored
+docs/examples/* linguist-vendored
+*.html linguist-detectable=false
+*.css linguist-detectable=false
+*.ipynb linguist-detectable=false
+*.sh linguist-detectable=false

.github/workflows/build_workflow.yml

@@ -27,7 +27,7 @@ jobs:
 
   pre-commit-hooks:
     needs: check-jobs-to-skip
-    if: ${{ needs.check-jobs-to-skip.outputs.should_skip != 'true'}} || ${{ github.event_name == 'push' }}
+    if: ${{ needs.check-jobs-to-skip.outputs.should_skip != 'true' }} || ${{ github.event_name == 'push' }}
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
@@ -44,7 +44,7 @@ jobs:
 
   build:
     needs: check-jobs-to-skip
-    if: ${{ needs.check-jobs-to-skip.outputs.should_skip != 'true'}} || ${{ github.event_name == 'push' }}
+    if: ${{ needs.check-jobs-to-skip.outputs.should_skip != 'true' }} || ${{ github.event_name == 'push' }}
     runs-on: ubuntu-latest
     defaults:
       run:
@@ -54,15 +54,15 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Conda Environment
-        uses: conda-incubator/setup-miniconda@v2
+        uses: conda-incubator/setup-miniconda@v3
         with:
-          activate-environment: "pcmdi_metrics_dev"
-          miniforge-variant: Mambaforge
+          miniforge-variant: Miniforge3
           miniforge-version: latest
-          use-mamba: true
-          mamba-version: "*"
+          activate-environment: "pcmdi_metrics_ci"
+          environment-file: conda-env/ci.yml
           channel-priority: strict
           auto-update-conda: true
+          python-version: ${{ matrix.python-version }}
 
       # Used for refreshing the cache every 24 hours to avoid inconsistencies of package
       # versions between the CI pipeline and local installations.
@@ -78,16 +78,11 @@ jobs:
           key:
             conda-${{ runner.os }}--${{ runner.arch }}--${{
             steps.get-date.outputs.today }}-${{
-            hashFiles('conda-env/dev.yml') }}-${{ env.CACHE_NUMBER}}
+            hashFiles('conda-env/ci.yml') }}-${{ env.CACHE_NUMBER}}
         env:
           # Increase this value to reset cache if conda/dev.yml has not changed in the workflow
           CACHE_NUMBER: 0
 
-      - name: Update environment
-        run:
-          mamba env update -n pcmdi_metrics_dev -f conda-env/dev.yml
-        if: steps.cache.outputs.cache-hit != 'true'
-
       - name: Install pcmdi_metrics
         # Source: https://github.com/conda/conda-build/issues/4251#issuecomment-1053460542
         run: |
@@ -96,3 +91,58 @@ jobs:
       - name: Run Tests
         run: |
           pytest
+
+      - name: Run Unit Tests
+        run: pytest tests
+
+
+  publish-docs:
+    if: ${{ github.event_name == 'push' }} ||  ${{ github.event_name == 'pull_request' }}
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Cache Conda
+        uses: actions/cache@v3
+        env:
+          # Increase this value to reset cache if conda-env/ci.yml has not changed in the workflow
+          CACHE_NUMBER: 0
+        with:
+          path: ~/conda_pkgs_dir
+          key: ${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{
+            hashFiles('conda-env/dev.yml') }}
+
+      - name: Set up Conda Environment
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          activate-environment: "pcmdi_metrics_dev"
+          miniforge-variant: Miniforge3
+          miniforge-version: latest
+          environment-file: conda-env/dev.yml
+          channel-priority: strict
+          auto-update-conda: true
+
+      - name: Install pcmdi_metrics
+        # Source: https://github.com/conda/conda-build/issues/4251#issuecomment-1053460542
+        run: |
+            python -m pip install --no-build-isolation --no-deps -e .
+
+      - name: Sphinx build
+        run: |
+          sphinx-build docs _build
+          
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages 
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/
+          force_orphan: true

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 # Configuration file for `pre-commit` tool.
 # Source: https://pre-commit.com/#pre-commit-configyaml---top-level
 exclude: "docs|node_modules|migrations|.git|.tox|README.md|sample_setups/(external-setups|jsons)|tests/deprecated"
-default_stages: [commit]
+default_stages: [pre-commit]
 fail_fast: true
 
 repos:

README.md

@@ -7,19 +7,22 @@
 
 # PCMDI Metrics Package (PMP)
 
-[![latest version](https://anaconda.org/conda-forge/pcmdi_metrics/badges/version.svg)](https://anaconda.org/conda-forge/pcmdi_metrics/)
-![Last updated](https://anaconda.org/conda-forge/pcmdi_metrics/badges/latest_release_date.svg)
+<!-- badges: start -->
+[![latest version](https://img.shields.io/conda/vn/conda-forge/pcmdi_metrics.svg?kill_cache=1)](https://anaconda.org/conda-forge/pcmdi_metrics/)
+[![Last updated](https://anaconda.org/conda-forge/pcmdi_metrics/badges/latest_release_date.svg?kill_cache=1)](https://anaconda.org/conda-forge/pcmdi_metrics/files)
 ![platforms](https://img.shields.io/badge/platforms-linux%20|%20osx-lightgrey.svg)
 [![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.592790.svg)](https://doi.org/10.5281/zenodo.592790)
 [![License](https://anaconda.org/conda-forge/pcmdi_metrics/badges/license.svg)](https://github.com/PCMDI/pcmdi_metrics/blob/main/LICENSE)
 [![Formatted with black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
 [![All Contributors](https://img.shields.io/github/all-contributors/PCMDI/pcmdi_metrics?color=ee8449&style=flat-square)](#contributors)
 
-Conda-forge (NEW, recommended):
-[![Download](https://anaconda.org/conda-forge/pcmdi_metrics/badges/downloads.svg)](https://anaconda.org/conda-forge/pcmdi_metrics/)
+Conda-forge (CURRENT, recommended):
+[![Download](https://anaconda.org/conda-forge/pcmdi_metrics/badges/downloads.svg?kill_cache=1)](https://anaconda.org/conda-forge/pcmdi_metrics/)
 
-PCMDI Conda Channel (halted):
-[![Download](https://anaconda.org/pcmdi/pcmdi_metrics/badges/downloads.svg)](https://anaconda.org/pcmdi/pcmdi_metrics)
+PCMDI Conda Channel (old, deprecated):
+[![Download](https://anaconda.org/pcmdi/pcmdi_metrics/badges/downloads.svg?kill_cache=1)](https://anaconda.org/pcmdi/pcmdi_metrics)
+
+<!-- badges: end -->
 
 The PCMDI Metrics Package (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.  Among other purposes, this enables modeling groups to evaluate changes during the development cycle in the context of the structural error distribution of the multi-model ensemble. Currently, the comparisons emphasize metrics of large- to global-scale annual cycle, tropical and extra-tropical modes of variability, ENSO, MJO, regional monsoons, high frequency characteristics of simulated precipitation, and cloud feedback.
 
@@ -48,9 +51,17 @@ Documentation
 * [View Demo](https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/README.md)
 
 
-**Reference**
+**References**
+
+Latest: 
+
+* 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**. 
+
+Earlier versions:
+
+* Gleckler, P. J., Doutriaux, C., Durack, P. J., Taylor, K. E., Zhang, Y., Williams, D. N., Mason, E., and Servonnat, J.: A more powerful reality test for climate models, Eos T. Am. Geophys. Un., 97, https://doi.org/10.1029/2016eo051663, **2016**. 
 
-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)
+* 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**. 
 
 
 Contact
@@ -109,7 +120,11 @@ Release Notes and History
 
 | <div style="width:300%">[Versions]</div> | Update summary   |
 | ------------- | ------------------------------------- |
-| [v3.5.2]      | Technical update, QC tools, new modes for modes of variability metrics (PSA1, PSA2)
+| [v3.7.1]      | Technical update with documentation improvements
+| [v3.7]        | New capability (**figure generation for mean climate**) and technical update
+| [v3.6.1]      | Technical update, additional QC repair functions
+| [v3.6]        | New capability (**regional application of precip variability**) and technical update
+| [v3.5.2]      | New capability (**QC**, **new modes for modes of variability metrics: PSA1, PSA2**) and technical update
 | [v3.5.1]      | Technical update
 | [v3.5]        | Technical update: MJO and Monsoon Sperber [xCDAT](https://xcdat.readthedocs.io/en/latest/) conversion
 | [v3.4.1]      | Technical update
@@ -126,6 +141,13 @@ Release Notes and History
 | [v3.0.2]      | Minor patch and more documentation added
 | [v3.0.1]      | Minor technical patch                 
 | [v3.0.0]      | New metric added: **Cloud feedback metric** by @mzelinka. [**xCDAT**](https://xcdat.readthedocs.io/en/latest/) implemented for mean climate metrics
+
+<details>
+
+  <summary>Click here for older versions</summary>
+
+| <div style="width:300%">[Versions]</div> | Update summary   |
+| ------------- | ------------------------------------- |
 | [v2.5.1]      | Technical update
 | [v2.5.0]      | New metric added: **Precipitation Benchmarking -- distribution**. Graphics updated
 | [v2.4.0]      | New metric added: **AMO** in variability modes
@@ -144,8 +166,13 @@ Release Notes and History
 | [v1.1]        | First public release, emphasizing **climatological statistics**, with development branches for ENSO and regional monsoon precipitation indices
 | [v1.0]        | Prototype version of the PMP
 
+</details>
 
 [Versions]: https://github.com/PCMDI/pcmdi_metrics/releases
+[v3.7.1]: https://github.com/PCMDI/pcmdi_metrics/releases/tag/v3.7.1
+[v3.7]: https://github.com/PCMDI/pcmdi_metrics/releases/tag/v3.7
+[v3.6.1]: https://github.com/PCMDI/pcmdi_metrics/releases/tag/v3.6.1
+[v3.6]: https://github.com/PCMDI/pcmdi_metrics/releases/tag/v3.6
 [v3.5.2]: https://github.com/PCMDI/pcmdi_metrics/releases/tag/v3.5.2
 [v3.5.1]: https://github.com/PCMDI/pcmdi_metrics/releases/tag/v3.5.1
 [v3.5]: https://github.com/PCMDI/pcmdi_metrics/releases/tag/v3.5
@@ -191,8 +218,8 @@ Current Core Team Members at PCMDI/LLNL
 * Kristin Chang
 
 
-Contributors
-------------
+All Contributors
+----------------
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
 

conda-env/readthedocs.yml → conda-env/ci.yml

@@ -1,4 +1,5 @@
-name: pcmdi_metrics_rtd
+# Conda pcmdi_metrics CI/CD environment (used in GH Actions).
+name: pcmdi_metrics_ci
 channels:
     - conda-forge
     - defaults
@@ -10,43 +11,30 @@ dependencies:
     - python=3.10.10
     - pip=23.1.2
     - numpy=1.23.5
-    - cartopy=0.21.1
+    - cartopy=0.22.0
     - matplotlib=3.7.1
     - cdms2=3.1.5
     - genutil=8.2.1
     - cdutil=8.2.1
     - cdp=1.7.0
-    - eofs=1.4.0
+    - eofs=1.4.1
     - seaborn=0.12.2
     - enso_metrics=1.1.1
-    - xcdat=0.5.0
+    - xcdat>=0.7.0
     - xmltodict=0.13.0
     - setuptools=67.7.2
-    - netcdf4=1.6.3
+    - netcdf4>=1.6.3
     - regionmask=0.9.0
-    - rasterio=1.3.6
+    - rasterio>=1.3.6
     - shapely=2.0.1
+    - numdifftools
+    - nc-time-axis
+    - colorcet
     # ==================
     # Testing
     # ==================
     - pre_commit=3.2.2
     - pytest=7.3.1
     - pytest-cov=4.0.0
-    # ==================
-    # Developer Tools
-    # ==================
-    - jupyterlab=3.6.3
-    - nb_conda=2.2.1
-    - nb_conda_kernels=2.3.1
-    # ==================
-    # Documentation
-    # ==================
-    - sphinx=5.3.0
-    - sphinx-autosummary-accessors=2022.4.0
-    - sphinx-book-theme=1.0.1
-    - sphinx-copybutton=0.5.1
-    - nbsphinx=0.9.1
-    - pandoc=3.1.1
-    - ipython=8.11.0 # Required for nbsphinx syntax highlighting
-
-prefix: /opt/miniconda3/envs/pcmdi_metrics_rtd
+
+prefix: /opt/miniconda3/envs/pmcdi_metrics_ci

conda-env/dev.yml

@@ -1,4 +1,4 @@
-# Conda pcmdi_metrics development environment
+# A conda development environment with all dependencies, including optional and documentation dependencies.
 name: pcmdi_metrics_dev
 channels:
     - conda-forge
@@ -20,7 +20,7 @@ dependencies:
     - eofs=1.4.1
     - seaborn=0.12.2
     - enso_metrics=1.1.1
-    - xcdat>=0.7.0
+    - xcdat>=0.7.2
     - xmltodict=0.13.0
     - setuptools=67.7.2
     - netcdf4>=1.6.3
@@ -29,6 +29,7 @@ dependencies:
     - shapely=2.0.1
     - numdifftools
     - nc-time-axis
+    - colorcet
     # ==================
     # Testing
     # ==================
@@ -45,11 +46,14 @@ dependencies:
     # Documentation
     # ==================
     - sphinx
+    - sphinx-autosummary-accessors
     - sphinx-book-theme
     - sphinx-copybutton
     - sphinx_rtd_theme
+    - furo
     - nbsphinx
     - pandoc
+    - sphinx-design
     - ipython # Required for nbsphinx syntax highlighting
 
 prefix: /opt/miniconda3/envs/pmcdi_metrics_dev