Merge remote-tracking branch 'origin/development' into attempt_refactor_soiling_pr

Author: martin-springer

.github/workflows/nbval.yaml

@@ -29,7 +29,7 @@ jobs:
         pip install --timeout=300 -r requirements.txt -r docs/notebook_requirements.txt .[test]
     - name: Run notebook and check output
       run: |
-        # --sanitize-with:  pre-process text to remove irrelevant differences (e.g. warning filepaths)
+        # --nbval-sanitize-with:  pre-process text to remove irrelevant differences (e.g. warning filepaths)
         pytest --nbval --nbval-sanitize-with docs/nbval_sanitization_rules.cfg docs/${{ matrix.notebook-file }}
     - name: Run notebooks again, save files
       run: |

.gitignore

@@ -7,9 +7,10 @@
 # ignore byte compiled files
 *.py[co]
 
-# ignore coveralls yaml, coverge dir
+# ignore coveralls yaml, coverage dir
 .coveralls.yml
 .coverage
+.coverage.*
 htmlcov/
 
 # ignore test cache

docs/Multi-year_on_year_example.ipynb

@@ -30,7 +30,7 @@ nbconvert==7.17.0
 nbformat==5.10.4
 nest-asyncio==1.6.0
 notebook==7.2.2
-numexpr==2.10.1
+numexpr==2.10.2
 pandocfilters==1.5.1
 parso==0.8.4
 pexpect==4.9.0
@@ -45,6 +45,7 @@ qtconsole==5.5.2
 Send2Trash==1.8.3
 simplegeneric==0.8.1
 soupsieve==2.6
+tabulate==0.9.0
 terminado==0.18.1
 testpath==0.6.0
 tinycss2==1.2.1
@@ -53,3 +54,4 @@ traitlets==5.14.3
 wcwidth==0.2.13
 webencodings==0.5.1
 widgetsnbextension==4.0.11
+

docs/notebook_requirements.txt

@@ -1,6 +1,7 @@
 RdTools Change Log
 ==================
 .. include:: changelog/pending.rst
+.. include:: changelog/v3.2.0.rst
 .. include:: changelog/v3.1.0.rst
 .. include:: changelog/v3.0.1.rst
 .. include:: changelog/v3.0.0.rst

docs/sphinx/source/changelog.rst

@@ -1,5 +1,5 @@
 ****************************
-v3.1.0 (February XX, 2026)
+v3.1.0 (March 05, 2026)
 ****************************
 
 Enhancements

docs/sphinx/source/changelog/v3.1.0.rst

@@ -0,0 +1,75 @@
+*************************
+v3.2.0 (X, X, 2026)
+*************************
+
+Enhancements
+------------
+* :py:func:`~rdtools.degradation.degradation_year_on_year` has new parameter ``label=``
+  to return the calc_info['YoY_values'] as either right labeled (default), left or
+  center labeled. (:issue:`459`)
+* :py:func:`~rdtools.plotting.degradation_timeseries_plot` now defaults to rolling
+  median, centered on the timestamp (pd.rolling(center=True)), and reduces
+  ``min_periods`` from ``rolling_days//2`` to ``rolling_days//4``.
+  (:issue:`455`)
+* :py:func:`~rdtools.degradation.degradation_year_on_year` has new parameter ``multi_yoy``
+  (default False) to trigger multiple YoY degradation calculations similar to Hugo Quest et
+  al 2023. In this mode, instead of a series of 1-year duration slopes, 2-year, 3-year etc
+  slopes are also included.  calc_info['YoY_values'] returns a non-monotonic index
+  in this mode due to multiple overlapping annual slopes.  (:issue:`394`)
+* :py:func:`~rdtools.plotting.degradation_timeseries_plot` now supports ``multi_yoy=True``
+  data by resampling overlapping YoY values to their mean. A warning is issued when this
+  resampling occurs.  (:issue:`394`)
+* :py:func:`~rdtools.plotting.degradation_summary_plots` ``detailed=True`` mode now
+  properly handles points used odd vs even number of times (not just 0, 1, 2).
+  (:issue:`394`)
+* :py:func:`~rdtools.degradation.degradation_year_on_year` now returns
+  ``calc_info['YoY_times']`` DataFrame with ``dt_right``, ``dt_center``, and ``dt_left``
+  columns for each YoY slope.  (:issue:`459`)
+* Added new example notebook ``docs/Multi-year_on_year_example.ipynb`` demonstrating the
+  ``label='center'`` and ``multi_yoy=True`` features of
+  :py:func:`~rdtools.degradation.degradation_year_on_year`.  (:issue:`394`)
+* :py:meth:`~rdtools.analysis_chains.TrendAnalysis.sensor_analysis` and
+  :py:meth:`~rdtools.analysis_chains.TrendAnalysis.clearsky_analysis` now
+  explicitly default ``yoy_kwargs={"label": "right"}``.
+
+Bug Fixes
+---------
+* Fixed ``usage_of_points`` calculation in :py:func:`~rdtools.degradation.degradation_year_on_year`
+  to properly handle ``multi_yoy=True`` mode with overlapping slopes.  (:issue:`394`)
+
+
+Maintenance
+-----------
+* Added ``_avg_timestamp_old_Pandas`` helper function for pandas <2.0 compatibility
+  when calculating center labels.
+* Fixed nbval workflow command syntax (``--sanitize-with`` to ``--nbval-sanitize-with``).
+* Improved pandas 3.0 compatibility with datetime resolution handling.
+* Updated ``docs/notebook_requirements.txt`` to require ``numexpr>=2.10.2`` and
+  ``tabulate>=0.9.0`` to satisfy pandas' optional dependency minimum versions and
+  avoid related warnings/errors.
+* Removed trailing semicolons in example notebooks.
+* Added ``.coverage.*`` pattern to ``.gitignore``.
+
+Testing
+-------
+* Added tests for error handling paths in :py:mod:`~rdtools.analysis_chains`:
+  ``filter_params`` and ``filter_params_aggregated`` setter validation,
+  ``clearsky_rescale_index_mismatch``, ``poa_filter_without_poa``,
+  ``tcell_filter_without_temperature``, ``hour_angle_filter_without_location``,
+  ``clearsky_filter_without_poa``, and ``degradation_timeseries_plot_invalid_case``.
+* Added tests for error handling paths in :py:mod:`~rdtools.degradation`:
+  ``classical_decomposition`` missing/irregular data, ``year_on_year`` circular block
+  validation, no valid pairs error, and ``_mk_test`` edge cases (no trend, ties,
+  decreasing).
+* Added test for ``multi_yoy=True`` parameter in ``degradation_year_on_year``.
+* Added tests for :py:func:`~rdtools.plotting.degradation_timeseries_plot`
+  covering ``label='center'``, ``label='left'``, multi-YoY duplicate index
+  handling, and ``KeyError`` path.
+* Set matplotlib backend to ``Agg`` in test ``conftest.py`` to avoid tkinter issues.
+
+
+Contributors
+------------
+* Chris Deline (:ghuser:`cdeline`)
+* Martin Springer (:ghuser:`martin-springer`)
+

docs/sphinx/source/changelog/v3.2.0.rst

@@ -27,3 +27,4 @@ This page shows example usage of the RdTools analysis functions.
     examples/TrendAnalysis_example
     examples/TrendAnalysis_example_NSRDB
     examples/system_availability_example
+    examples/Multi-year_on_year_example

docs/sphinx/source/examples.rst

@@ -0,0 +1,3 @@
+{
+    "path": "../../../Multi-year_on_year_example.ipynb"
+}

docs/sphinx/source/examples/Multi-year_on_year_example.nblink

@@ -1001,7 +1001,7 @@ def _clearsky_preprocess(self):
         )
 
     def sensor_analysis(
-        self, analyses=["yoy_degradation"], yoy_kwargs={}, srr_kwargs={}
+        self, analyses=["yoy_degradation"], yoy_kwargs={"label": "right"}, srr_kwargs={}
     ):
         """
         Perform entire sensor-based analysis workflow.
@@ -1014,6 +1014,7 @@ def sensor_analysis(
             and 'srr_soiling'
         yoy_kwargs : dict
             kwargs to pass to :py:func:`rdtools.degradation.degradation_year_on_year`
+            default is {"label": "right"}, which will right-label the YoY slope values.
         srr_kwargs : dict
             kwargs to pass to :py:func:`rdtools.soiling.soiling_srr`
 
@@ -1041,7 +1042,7 @@ def sensor_analysis(
         self.results["sensor"] = sensor_results
 
     def clearsky_analysis(
-        self, analyses=["yoy_degradation"], yoy_kwargs={}, srr_kwargs={}
+        self, analyses=["yoy_degradation"], yoy_kwargs={"label": "right"}, srr_kwargs={}
     ):
         """
         Perform entire clear-sky-based analysis workflow. Results are stored
@@ -1053,7 +1054,8 @@ def clearsky_analysis(
             Analyses to perform as a list of strings. Valid entries are 'yoy_degradation'
             and 'srr_soiling'
         yoy_kwargs : dict
-            kwargs to pass to :py:func:`rdtools.degradation.degradation_year_on_year`
+            kwargs to pass to :py:func:`rdtools.degradation.degradation_year_on_year`.
+            default is {"label": "right"}, which will right-label the YoY slope values.
         srr_kwargs : dict
             kwargs to pass to :py:func:`rdtools.soiling.soiling_srr`