Feature 364 add tci calc (#369)

* Changes URL for coding standards to point to the METplus wrappers contributors guide coding standards.

* Changes wording from build to make to be consistent with experience using newer sphinx.

* Changes to allow autosummary to work and document the diagnostics submodule.

* Adds new menu entry for the diagnostics submodule.

* RST file for autosummary to use, with change from default module.rst file to get the functions to be clickable per sphinx-doc/sphinx#11998.

* RST file for the diagnostic submodule.

* Adds the generated directory from sphinx in the diag_api subdirectory to the gitignore.

* Adds a new land_surface diagnostic file to contain functions for land/surface applications.

* Adds __pycache__ to gitignore.

* Adds sphinx execution times RST file to gitignore.

* Removes cruft from testing, adds exception raising, and updates docstring formatting to match Sphinx https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html.

* Restructure function to handle invalid types. This may not be the right way to do this.

* Removes erroneous menu entries from testing documentation.

* Adds test for calc_tci function and test data.

* Adds Xarray and Pandas dependencies for building documentation, and lifts Python version for building documentation from 3.8 to 3.10.

* Adds TCI test to the unit test config.

* Changes name to remove API.

* Trying to get GHA to run.

* Updating pandas/xarray versions.

* Double equals.

* Changes RST heading level and adds description of the diagnostic reference.

* Moves the diagnostic calculation reference to a sub-menu within the User's Guide.

* Testing failure when readthedocs reports a warning.

* Adds back xarray readthedocs requirement.

* Update docs/Contributors_Guide/index.rst

Co-authored-by: Julie Prestopnik <jpresto@ucar.edu>

* Adds reference for  function.

* Adds bool for turning on/off the pandas and xarray tests.

* Adds new skipna argument to the function, which is passed to pandas and xarray. The default is set to True, but a user can override if they wish.

* Renames diag_api directory to diag_ref.

* Renames testing file for land_surface diagnostics to support additional land_surface diagnostics in the future.

* Turns on the Sphinx napoleon extension to support Google and NumPy docstrings and re-writes the  docstring using Google format.

* Updates Google docstring to acheive desired formatting.

* Adds dunder init file.

* Renames hyperlink and menu entry.

* Changed a directory name and forgot to update the ignore file.

* Removes directory not intended to be in repository.

---------

Co-authored-by: Julie Prestopnik <jpresto@ucar.edu>

.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

@@ -66,7 +66,8 @@ jobs:
         pytest test_future_warnings.py
         pytest test_sl1l2.py
         pytest test_reformatted_for_agg.py
-        coverage run -m pytest test_agg_eclv.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_reformatted_for_agg.py
+        pytest test_diagnostics_land_surface.py
+        coverage run -m pytest test_agg_eclv.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_reformatted_for_agg.py test_diagnostics_land_surface.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
+