Merge branch 'develop' into feature_361_aggstats_for_linetypes

.github/workflows/documentation.yml

@@ -20,11 +20,11 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          python-version: '3.8'
+          python-version: '3.10'
       - name: Install dependencies
         run: |
           python -m pip install --upgrade python-dateutil requests sphinx \
-          sphinx-gallery Pillow sphinx_rtd_theme
+          sphinx-gallery Pillow sphinx_rtd_theme pandas xarray 
           python -m pip install -r docs/requirements.txt
       - name: Build docs
         run: ./.github/jobs/build_documentation.sh 

.github/workflows/unit_tests.yml

@@ -68,11 +68,13 @@ jobs:
         pytest test_future_warnings.py
         pytest test_sl1l2.py
         pytest test_reformatted_for_agg.py
+        pytest test_diagnostics_land_surface.py
         coverage run -m pytest test_agg_eclv.py test_agg_ratio.py test_agg_stat.py test_agg_stats_and_boot.py \
                   test_agg_stats_with_groups.py test_calc_difficulty_index.py test_convert_lon_indices.py \
                   test_event_equalize.py  test_event_equalize_against_values.py test_lon_360_to_180.py \
                   test_statistics.py test_tost_paired.py test_utils.py test_future_warnings.py \
                   test_sl1l2.py test_reformatted_for_agg.py
+        
         coverage html
         
     - name: Archive code coverage results

.gitignore

@@ -4,9 +4,12 @@
 # temp files surrounded by #
 *#*#
 
+__pycache__/
+
 # sphinx output
 docs/_build
-
+docs/diag_ref/generated
+docs/sg_execution_times.rst
 docs/auto_examples
 
 

.readthedocs.yaml

@@ -25,3 +25,4 @@ python:
 sphinx:
   builder: html
   configuration: docs/conf.py
+  fail_on_warning: true

docs/Contributors_Guide/index.rst

@@ -39,7 +39,7 @@ Python Requirements
 Coding Standards
 ================
 
-METplus has adopted some coding standards for its Python code.  Detailed information can be found here: https://metplus.readthedocs.io/en/main_v4.0/Users_Guide/
+METplus has adopted some coding standards for its Python code.  Detailed information can be found here: https://metplus.readthedocs.io/en/latest/Contributors_Guide/coding_standards.html
 
 Comment the Python code using Python docstrings: https://peps.python.org/pep-0257/
 
@@ -203,9 +203,9 @@ Create User Documentation
 
 * from the command line, run the following commands::
 
-   build clean
+   make clean
 
-   build_html
+   make html
 
 * Verify that there aren’t any warnings or error messages in the output
 

docs/Users_Guide/index.rst

@@ -68,6 +68,7 @@ National Center for Atmospheric Research (NCAR) is sponsored by NSF.
    aggregation
    write_mpr
    release-notes
+   ../diag_ref/index
 
 **Indices and tables**
 

docs/_templates/autosummary/module.rst

@@ -0,0 +1,61 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/conf.py

@@ -12,7 +12,7 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('..'))
 print(sys.path)
 
 
@@ -39,10 +39,15 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.autosummary',
               'sphinx.ext.intersphinx',
               'sphinx_gallery.gen_gallery',
               'sphinx_design',
-              'sphinx_rtd_theme',]
+              'sphinx_rtd_theme',
+              'sphinx.ext.napoleon',]
+
+# Turn on sphinx.ext.autosummary
+autosummary_generate = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/diag_ref/index.rst

@@ -0,0 +1,18 @@
+.. _api-index:
+
+********************************
+Diagnostic Calculation Reference
+********************************
+
+This reference contains technical documentation for various diagnostic calculations in METcalcpy.
+
+.. currentmodule:: metcalcpy.diagnostics
+
+.. autosummary::
+   :toctree: generated/
+   :recursive:
+
+   land_surface
+
+* :ref:`modindex`
+* :ref:`genindex`

docs/index.rst

@@ -121,9 +121,6 @@ To cite this documentation in publications, please refer to the METcalcpy User's
    Users_Guide/index
    Contributors_Guide/index
 
-
-
-
 Indices
 =======
 

docs/requirements.txt

@@ -4,3 +4,5 @@ sphinxcontrib-bibtex==2.6.1
 sphinx==5.3.0
 sphinx-design==0.3.0
 sphinx_rtd_theme==1.3.0
+pandas==2.2.1
+xarray==2024.3.0

metcalcpy/diagnostics/land_surface.py

@@ -0,0 +1,52 @@
+"""Diagnostics relevant to Land/Surface applications"""
+
+from xarray.core.dataarray import DataArray
+from pandas.core.series import Series
+
+def calc_tci(soil_data,sfc_flux_data,skipna=True):
+  """ Function for computing the Terrestrial Coupling Index
+
+  Args:
+      soil_data (Xarray DataArray or Pandas Series): The moisture variable to use for computing TCI.
+      sfc_flux_data (Xarray DataArray or Pandas Series): The latent heat flux variable to use for computing TCI.
+      skipna (bool): Skip NA values. Passed to Pandas or Xarray.
+ 
+  Returns:
+      Xarray DataArray or float32: If Xarray DataArray's are passed, then an Xarray DataArray 
+      containing the gridded TCI is returned. If a Pandas Series is passed, then a single TCI 
+      value is returned.
+
+  Raises:
+      TypeError: If an unrecognized object type is passed, or the object types do not match.
+
+  Reference:
+      Dirmeyer, P. A., 2011: The terrestrial segment of soil moisture-climate coupling. *Geophys. Res. Lett.*, **38**, L16702, doi: 10.1029/2011GL048268.
+  
+  """
+
+  # For Xarray objects, compute the mean 
+  if isinstance(soil_data,DataArray) and isinstance(sfc_flux_data,DataArray):
+    soil_mean = soil_data.mean(dim='time',skipna=skipna)
+    soil_count = soil_data.count(dim='time')
+    sfc_flux_mean = sfc_flux_data.mean(dim='time',skipna=skipna)
+    soil_std = soil_data.std(dim='time',skipna=skipna)
+    numer = ((soil_data-soil_mean) * (sfc_flux_data-sfc_flux_mean)).sum(dim='time',skipna=skipna)
+
+  # For Pandas objects, compute the mean
+  elif isinstance(soil_data,Series) and isinstance(sfc_flux_data,Series):
+    soil_mean = soil_data.mean(skipna=skipna)
+    soil_count = soil_data.count()
+    sfc_flux_mean = sfc_flux_data.mean(skipna=skipna)
+    soil_std = soil_data.std(skipna=skipna)
+    numer = ((soil_data-soil_mean) * (sfc_flux_data-sfc_flux_mean)).sum(skipna=skipna)
+
+  # No other object types are supported
+  else:
+    raise TypeError("Only Xarray DataArray or Pandas DataFrame Objects are supported. Input objects must be of the same type. Got "+str(type(soil_data))+" for soil_data and "+str(type(sfc_flux_data))+" for sfc_flux_data")
+
+  # Compute the covariance term
+  covarTerm = numer / soil_count 
+
+  # Return the Terrestrial Coupling Index (TCI)
+  return covarTerm/soil_std
+