Adopt ghi_clear variable name for clearsky GHI (#2306)

* non-breaking: clearsky_ghi -> ghi_clear

* breaking: clearsky_ghi & ghi_clearsky -> ghi_clear

* *_test_not_working_*

* Apply suggestions from code review

Co-authored-by: Echedey Luis <80125792+echedey-ls@users.noreply.github.com>

* change all variables

* Update pvlib/tests/test_irradiance.py

Co-authored-by: Echedey Luis <80125792+echedey-ls@users.noreply.github.com>

* dirindex deprecation test

* Update pvlib/tests/test_irradiance.py

Co-authored-by: Echedey Luis <80125792+echedey-ls@users.noreply.github.com>

* add @fail_on_pvlib_version("0.12") decorator

* Update test_irradiance.py

* correct version number

* Update irradiance.py

* 0.12->0.13 in test_irradiance.py

* Update v0.11.2.rst

* Update pvlib/tests/test_irradiance.py

Co-authored-by: Echedey Luis <80125792+echedey-ls@users.noreply.github.com>

* indents

* add missing .. versionchanged::

* refine test

* Update pvlib/irradiance.py

Co-authored-by: Kevin Anderson <kevin.anderso@gmail.com>

* Update irradiance.py

---------

Co-authored-by: Echedey Luis <80125792+echedey-ls@users.noreply.github.com>
Co-authored-by: Kevin Anderson <kevin.anderso@gmail.com>

Author: 3 people

docs/sphinx/source/whatsnew/v0.11.2.rst

@@ -9,6 +9,9 @@ Deprecations
 * Deprecated terms ``dni_clearsky`` and ``clearsky_dni``, replaced with ``dni_clear``.
   Affected functions are :py:func:`~pvlib.irradiance.dirindex` and :py:func:`~pvlib.irradiance.dni`.
   (:issue:`2272`, :pull:`2274`)
+* Deprecated term ``ghi_clearsky``, replaced with ``ghi_clear``.
+  Affected functions are :py:func:`~pvlib.irradiance.dirindex` and :py:func:`~pvlib.irradiance.clearsky_index`.
+  (:issue:`2272`, :pull:`2306`)
 
 
 Enhancements

pvlib/clearsky.py

@@ -327,13 +327,13 @@ def haurwitz(apparent_zenith):
     '''
 
     cos_zenith = tools.cosd(apparent_zenith.values)
-    clearsky_ghi = np.zeros_like(apparent_zenith.values)
+    ghi_clear = np.zeros_like(apparent_zenith.values)
     cos_zen_gte_0 = cos_zenith > 0
-    clearsky_ghi[cos_zen_gte_0] = (1098.0 * cos_zenith[cos_zen_gte_0] *
-                                   np.exp(-0.059/cos_zenith[cos_zen_gte_0]))
+    ghi_clear[cos_zen_gte_0] = (1098.0 * cos_zenith[cos_zen_gte_0] *
+                                np.exp(-0.059/cos_zenith[cos_zen_gte_0]))
 
     df_out = pd.DataFrame(index=apparent_zenith.index,
-                          data=clearsky_ghi,
+                          data=ghi_clear,
                           columns=['ghi'])
 
     return df_out

pvlib/irradiance.py

@@ -1614,7 +1614,12 @@ def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
         return ghi
 
 
-def clearsky_index(ghi, clearsky_ghi, max_clearsky_index=2.0):
+@renamed_kwarg_warning(
+    since='0.11.2',
+    old_param_name='clearsky_ghi',
+    new_param_name='ghi_clear',
+    removal="0.13.0")
+def clearsky_index(ghi, ghi_clear, max_clearsky_index=2.0):
     """
     Calculate the clearsky index.
 
@@ -1626,9 +1631,12 @@ def clearsky_index(ghi, clearsky_ghi, max_clearsky_index=2.0):
     ghi : numeric
         Global horizontal irradiance. [Wm⁻²]
 
-    clearsky_ghi : numeric
+    ghi_clear : numeric
         Modeled clearsky GHI
 
+        .. versionchanged:: 0.11.2
+            Renamed from ``ghi_clearsky`` to ``ghi_clear``.
+
     max_clearsky_index : numeric, default 2.0
         Maximum value of the clearsky index. The default, 2.0, allows
         for over-irradiance events typically seen in sub-hourly data.
@@ -1638,12 +1646,12 @@ def clearsky_index(ghi, clearsky_ghi, max_clearsky_index=2.0):
     clearsky_index : numeric
         Clearsky index
     """
-    clearsky_index = ghi / clearsky_ghi
+    clearsky_index = ghi / ghi_clear
     # set +inf, -inf, and nans to zero
     clearsky_index = np.where(~np.isfinite(clearsky_index), 0,
                               clearsky_index)
     # but preserve nans in the input arrays
-    input_is_nan = ~np.isfinite(ghi) | ~np.isfinite(clearsky_ghi)
+    input_is_nan = ~np.isfinite(ghi) | ~np.isfinite(ghi_clear)
     clearsky_index = np.where(input_is_nan, np.nan, clearsky_index)
 
     clearsky_index = np.maximum(clearsky_index, 0)
@@ -2151,20 +2159,25 @@ def _dirint_bins(times, kt_prime, zenith, w, delta_kt_prime):
     return kt_prime_bin, zenith_bin, w_bin, delta_kt_prime_bin
 
 
+@renamed_kwarg_warning(
+    since='0.11.2',
+    old_param_name='ghi_clearsky',
+    new_param_name='ghi_clear',
+    removal="0.13.0")
 @renamed_kwarg_warning(
     since='0.11.2',
     old_param_name='dni_clearsky',
     new_param_name='dni_clear',
     removal="0.13.0")
-def dirindex(ghi, ghi_clearsky, dni_clear, zenith, times, pressure=101325.,
+def dirindex(ghi, ghi_clear, dni_clear, zenith, times, pressure=101325.,
              use_delta_kt_prime=True, temp_dew=None, min_cos_zenith=0.065,
              max_zenith=87):
     """
     Determine DNI from GHI using the DIRINDEX model.
 
     The DIRINDEX model [1]_ modifies the DIRINT model implemented in
     :py:func:`pvlib.irradiance.dirint` by taking into account information
-    from a clear sky model. It is recommended that ``ghi_clearsky`` be
+    from a clear sky model. It is recommended that ``ghi_clear`` be
     calculated using the Ineichen clear sky model
     :py:func:`pvlib.clearsky.ineichen` with ``perez_enhancement=True``.
 
@@ -2175,9 +2188,12 @@ def dirindex(ghi, ghi_clearsky, dni_clear, zenith, times, pressure=101325.,
     ghi : array-like
         Global horizontal irradiance. [Wm⁻²]
 
-    ghi_clearsky : array-like
+    ghi_clear : array-like
         Global horizontal irradiance from clear sky model. [Wm⁻²]
 
+        .. versionchanged:: 0.11.2
+            Renamed from ``ghi_clearsky`` to ``ghi_clear``.
+
     dni_clear : array-like
         Direct normal irradiance from clear sky model. [Wm⁻²]
 
@@ -2240,7 +2256,7 @@ def dirindex(ghi, ghi_clearsky, dni_clear, zenith, times, pressure=101325.,
                         temp_dew=temp_dew, min_cos_zenith=min_cos_zenith,
                         max_zenith=max_zenith)
 
-    dni_dirint_clearsky = dirint(ghi_clearsky, zenith, times,
+    dni_dirint_clearsky = dirint(ghi_clear, zenith, times,
                                  pressure=pressure,
                                  use_delta_kt_prime=use_delta_kt_prime,
                                  temp_dew=temp_dew,

pvlib/tests/test_irradiance.py

@@ -1095,6 +1095,20 @@ def test_dirindex(times):
         equal_nan=True)
 
 
+@fail_on_pvlib_version("0.13")
+def test_dirindex_ghi_clearsky_deprecation():
+    times = pd.DatetimeIndex(['2014-06-24T18-1200'])
+    ghi = pd.Series([1038.62], index=times)
+    ghi_clearsky = pd.Series([1042.48031487], index=times)
+    dni_clearsky = pd.Series([939.95469881], index=times)
+    zenith = pd.Series([10.56413562], index=times)
+    pressure, tdew = 93193, 10
+    with pytest.warns(pvlibDeprecationWarning, match='ghi_clear'):
+        irradiance.dirindex(
+            ghi=ghi, ghi_clearsky=ghi_clearsky, dni_clear=dni_clearsky,
+            zenith=zenith, times=times, pressure=pressure, temp_dew=tdew)
+
+
 def test_dirindex_min_cos_zenith_max_zenith():
     # map out behavior under difficult conditions with various
     # limiting kwargs settings
@@ -1260,6 +1274,13 @@ def test_clearsky_index():
     assert_series_equal(out, expected)
 
 
+@fail_on_pvlib_version("0.13")
+def test_clearsky_index_clearsky_ghi_deprecation():
+    with pytest.warns(pvlibDeprecationWarning, match='ghi_clear'):
+        ghi, clearsky_ghi = 200, 300
+        irradiance.clearsky_index(ghi, clearsky_ghi=clearsky_ghi)
+
+
 def test_clearness_index():
     ghi = np.array([-1, 0, 1, 1000])
     solar_zenith = np.array([180, 90, 89.999, 0])