Merge branch 'main' into zhan391

.all-contributorsrc

@@ -235,12 +235,22 @@
         "code",
         "research"
       ]
+    },
+    {
+      "login": "bosup",
+      "name": "Bo Dong",
+      "avatar_url": "https://avatars.githubusercontent.com/u/130708142?v=4",
+      "profile": "https://github.com/bosup",
+      "contributions": [
+        "code"
+      ]
     }
   ],
   "contributorsPerLine": 7,
   "skipCi": true,
   "repoType": "github",
   "repoHost": "https://github.com",
   "projectName": "pcmdi_metrics",
-  "projectOwner": "PCMDI"
+  "projectOwner": "PCMDI",
+  "commitType": "docs"
 }

README.md

@@ -50,7 +50,7 @@ Documentation
 
 **Reference**
 
-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 (_accepted, publication in progress_) [[preprint](https://egusphere.copernicus.org/preprints/2023/egusphere-2023-2720/)]
+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)
 
 
 Contact
@@ -109,6 +109,7 @@ Release Notes and History
 
 | <div style="width:300%">[Versions]</div> | Update summary   |
 | ------------- | ------------------------------------- |
+| [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
 | [v3.4]        | Technical update: Modes of variability [xCDAT](https://xcdat.readthedocs.io/en/latest/) conversion
@@ -144,6 +145,7 @@ Release Notes and History
 
 
 [Versions]: https://github.com/PCMDI/pcmdi_metrics/releases
+[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
 [v3.4.1]: https://github.com/PCMDI/pcmdi_metrics/releases/tag/v3.4.1
 [v3.4]: https://github.com/PCMDI/pcmdi_metrics/releases/tag/v3.4
@@ -217,6 +219,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     </tr>
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://sites.google.com/uw.edu/kimresearchgroup"><img src="https://scholar.googleusercontent.com/citations?view_op=view_photo&user=3xLjsIsAAAAJ&citpid=3?s=100" width="100px;" alt="Daehyun Kim"/><br /><sub><b>Daehyun Kim</b></sub></a><br /><a href="https://github.com/PCMDI/pcmdi_metrics/commits?author=" title="Code">💻</a> <a href="#research" title="Research">🔬</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/bosup"><img src="https://avatars.githubusercontent.com/u/130708142?v=4?s=100" width="100px;" alt="Bo"/><br /><sub><b>Bo Dong</b></sub></a><br /><a href="https://github.com/PCMDI/pcmdi_metrics/commits?author=bosup" title="Code">💻</a></td>
     </tr>
   </tbody>
 </table>

conda-env/dev.yml

@@ -38,19 +38,18 @@ dependencies:
     # ==================
     # Developer Tools
     # ==================
-    - jupyterlab=3.6.3
-    - nb_conda=2.2.1
-    - nb_conda_kernels=2.3.1
+    - jupyterlab
+    - nb_conda
+    - nb_conda_kernels
     # ==================
     # Documentation
     # ==================
-    - sphinx=5.3.0
-    - sphinx-autosummary-accessors=2022.4.0
-    - sphinx-book-theme=1.0.1
-    - sphinx-copybutton=0.5.1
+    - sphinx
+    - sphinx-book-theme
+    - sphinx-copybutton
     - sphinx_rtd_theme
-    - nbsphinx=0.9.1
-    - pandoc=3.1.1
-    - ipython=8.11.0 # Required for nbsphinx syntax highlighting
+    - nbsphinx
+    - pandoc
+    - ipython # Required for nbsphinx syntax highlighting
 
 prefix: /opt/miniconda3/envs/pmcdi_metrics_dev

docs/conf.py

@@ -9,33 +9,67 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import sys
+import os
+sys.path.insert(0, os.path.abspath('../pcmdi_metrics/utils'))
 
-#import sphinx_autosummary_accessors
+# import sphinx_autosummary_accessors
 
 # -- Project information -----------------------------------------------------
 
 project = 'PCMDI Metrics Package'
-copyright = '2023 PCMDI'
+copyright = '2024 PCMDI'
 author = 'PCMDI'
 
-# The full version, including alpha/beta/rc tags
-# release = '1.2.1'
-
+# The version info for the project you're documenting, acts as replacement
+# for |version| and |release|, also used in various other places throughout
+# the built documents.
+#
+# The short X.Y version.
+# import pcmdi_metrics
+# version = pcmdi_metrics.__version__
+# The full version, including alpha/beta/rc tags.
+# release = pcmdi_metrics.__version__
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx_rtd_theme']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx_rtd_theme', 'sphinx.ext.napoleon']
+
+# autosummary and autodoc configurations
+# autosummary_generate = True
+"""
+autodoc_member_order = "bysource"
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "private-members": True,
+}
+autodoc_typehints = "none"
+"""
+
+# Napoleon configurations
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_param = False
+napoleon_use_rtype = False
+napoleon_preprocess_types = True
 
 # Add any paths that contain templates here, relative to this directory.
+# templates_path = ['_templates', sphinx_autosummary_accessors.templates_path]
 templates_path = ['_templates']
 
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = ".rst"
+
+# The master toctree document.
+master_doc = "index"
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #

docs/resources.rst

@@ -7,7 +7,5 @@ Resources
 .. toctree::
    :maxdepth: 1
 
-   pmp-using-cdp-guide
-   pmpparser
-
-
+   utils
+   resources_legacy

docs/resources_legacy.rst

@@ -0,0 +1,11 @@
+.. _resources:
+
+**************
+Legacy archive
+**************
+
+.. toctree::
+   :maxdepth: 1
+
+   pmp-using-cdp-guide
+   pmpparser

docs/utils.rst

@@ -0,0 +1,9 @@
+*****
+Utils
+*****
+
+
+.. automodule:: pcmdi_metrics.utils
+   :members: check_daily_time_axis, check_monthly_time_axis, create_land_sea_mask, apply_landmask, apply_oceanmask, regrid
+   :undoc-members:
+   :show-inheritance:

pcmdi_metrics/mean_climate/lib/compute_metrics.py

@@ -197,7 +197,7 @@ def compute_metrics(Var, dm, do, debug=False, time_dim_sync=False):
         metrics_dictionary["bias_xy"][sea] = format(bias_sea, sig_digits)
         metrics_dictionary["rms_xy"][sea] = format(rms_sea, sig_digits)
         metrics_dictionary["rmsc_xy"][sea] = format(rmsc_sea, sig_digits)
-        metrics_dictionary["cor_xy"][sea] = format(cor_sea, ".2f")
+        metrics_dictionary["cor_xy"][sea] = format(cor_sea, sig_digits)
         metrics_dictionary["mae_xy"][sea] = format(mae_sea, sig_digits)
         metrics_dictionary["std-obs_xy"][sea] = format(stdObs_xy_sea, sig_digits)
         metrics_dictionary["std_xy"][sea] = format(std_xy_sea, sig_digits)
@@ -250,7 +250,7 @@ def compute_metrics(Var, dm, do, debug=False, time_dim_sync=False):
 
         rms_mo_l.append(format(rms_mo, sig_digits))
         rmsc_mo_l.append(format(rmsc_mo, sig_digits))
-        cor_mo_l.append(format(cor_mo, ".2f"))
+        cor_mo_l.append(format(cor_mo, sig_digits))
         mae_mo_l.append(format(mae_mo, sig_digits))
         bias_mo_l.append(format(bias_mo, sig_digits))
         stdObs_xy_mo_l.append(format(stdObs_xy_mo, sig_digits))

pcmdi_metrics/utils/__init__.py

@@ -12,6 +12,12 @@
     regrid,
 )
 from .land_sea_mask import apply_landmask, apply_oceanmask, create_land_sea_mask
+from .qc import (
+    check_daily_time_axis,
+    check_monthly_time_axis,
+    last_day_of_month,
+    repeating_months,
+)
 from .sort_human import sort_human
 from .string_constructor import StringConstructor, fill_template
 from .tree_dict import tree

pcmdi_metrics/utils/grid.py

@@ -173,19 +173,30 @@ def regrid(
     regrid_method: str = "bilinear",
     fill_zero: bool = False,
 ) -> xr.Dataset:
-    """regrid the dataset to a given grid
+    """
+    Regrid the dataset to a given grid.
 
-    Args:
-        ds (xr.Dataset): dataset to regrid
-        data_var (str): variable in the dataset
-        target_grid (xr.Dataset): grid for interpolate to
-        regrid_tool (str, optional): Regrid option: "regrid2" or "xesmf". Defaults to "regrid2".
-        regrid_method (str, optional): Regrid method option that is required for xesmf regridder. Defaults to "bilinear".
-        fill_zero (bool, optional): Fill NaN value with zero if exists. Defaluts to False
+    Parameters
+    ----------
+    ds : xr.Dataset
+        Dataset to regrid.
+    data_var : str
+        Variable in the dataset.
+    target_grid : xr.Dataset
+        Grid to interpolate to.
+    regrid_tool : str, optional
+        Regrid option: "regrid2" or "xesmf". Default is "regrid2".
+    regrid_method : str, optional
+        Regrid method option that is required for xesmf regridder. Default is "bilinear".
+    fill_zero : bool, optional
+        Fill NaN value with zero if exists. Default is False.
 
-    Returns:
-        xr.Dataset: Regridded dataset
+    Returns
+    -------
+    xr.Dataset
+        Regridded dataset.
     """
+
     target_grid = get_grid(target_grid)  # To remove time dimension if exist
     # regrid
     if regrid_tool == "regrid2":