diff --git a/docs/sphinx/source/whatsnew/v0.11.2.rst b/docs/sphinx/source/whatsnew/v0.11.2.rst index e94c0f873..b2fb64fa9 100644 --- a/docs/sphinx/source/whatsnew/v0.11.2.rst +++ b/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 diff --git a/pvlib/clearsky.py b/pvlib/clearsky.py index eb97691ba..be75ecd47 100644 --- a/pvlib/clearsky.py +++ b/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 diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index cd9e72d7f..7fbb1ea98 100644 --- a/pvlib/irradiance.py +++ b/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,12 +2159,17 @@ 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): """ @@ -2164,7 +2177,7 @@ def dirindex(ghi, ghi_clearsky, dni_clear, zenith, times, pressure=101325., 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, diff --git a/pvlib/tests/test_irradiance.py b/pvlib/tests/test_irradiance.py index c39191ba1..9352e978e 100644 --- a/pvlib/tests/test_irradiance.py +++ b/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])