Add poa_ prefix to returned names when return_components=True in transposition functions (#2627)

* add `poa_` prefix

* update infinite_sheds

* whatsnew

* lint

* Update docs/sphinx/source/whatsnew/v0.13.2.rst

Co-authored-by: Cliff Hansen <[email protected]>

---------

Co-authored-by: Cliff Hansen <[email protected]>

Author: kandersolar

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

@@ -9,7 +9,10 @@ Breaking Changes
 * Following the removal of the NSRDB PSM3 API, the :func:`!pvlib.iotools.get_psm3`,
   :func:`!pvlib.iotools.read_psm3`, and :func:`!pvlib.iotools.parse_psm3`
   functions are removed. (:issue:`2581`, :pull:`2582`)
-
+* Rename output column names to be prefixed with ``"poa_"`` when ``return_components=True``
+  in :py:func:`~pvlib.irradiance.haydavies`, :py:func:`~pvlib.irradiance.perez`,
+  and :py:func:`~pvlib.irradiance.perez_driesse`. (:issue:`2529`, :pull:`2627`)
+   
 
 Deprecations
 ~~~~~~~~~~~~

pvlib/bifacial/infinite_sheds.py

@@ -301,15 +301,16 @@ def get_irradiance_poa(surface_tilt, surface_azimuth, solar_zenith,
         sky_diffuse_comps_horizontal = haydavies(0, 180, dhi, dni, dni_extra,
                                                  solar_zenith, solar_azimuth,
                                                  return_components=True)
-        circumsolar_horizontal = sky_diffuse_comps_horizontal['circumsolar']
+        circumsolar_horizontal = \
+            sky_diffuse_comps_horizontal['poa_circumsolar']
 
         # Call haydavies a second time where circumsolar_normal is facing
         # directly towards sun, and can be added to DNI
         sky_diffuse_comps_normal = haydavies(solar_zenith, solar_azimuth, dhi,
                                              dni, dni_extra, solar_zenith,
                                              solar_azimuth,
                                              return_components=True)
-        circumsolar_normal = sky_diffuse_comps_normal['circumsolar']
+        circumsolar_normal = sky_diffuse_comps_normal['poa_circumsolar']
 
         dhi = dhi - circumsolar_horizontal
         dni = dni + circumsolar_normal

pvlib/irradiance.py

@@ -793,10 +793,11 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     diffuse_components : OrderedDict (array input) or DataFrame (Series input)
         Keys/columns are:
-            * sky_diffuse: Total sky diffuse
-            * isotropic
-            * circumsolar
-            * horizon (always zero, not accounted for by the Hay-Davies model)
+            * poa_sky_diffuse: Total sky diffuse
+            * poa_isotropic
+            * poa_circumsolar
+            * poa_horizon (always zero, not accounted for by the
+              Hay-Davies model)
 
     Notes
     ------
@@ -855,13 +856,13 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     if return_components:
         diffuse_components = OrderedDict()
-        diffuse_components['sky_diffuse'] = sky_diffuse
+        diffuse_components['poa_sky_diffuse'] = sky_diffuse
 
         # Calculate the individual components
-        diffuse_components['isotropic'] = poa_isotropic
-        diffuse_components['circumsolar'] = poa_circumsolar
-        diffuse_components['horizon'] = np.where(
-            np.isnan(diffuse_components['isotropic']), np.nan, 0.)
+        diffuse_components['poa_isotropic'] = poa_isotropic
+        diffuse_components['poa_circumsolar'] = poa_circumsolar
+        diffuse_components['poa_horizon'] = np.where(
+            np.isnan(diffuse_components['poa_isotropic']), np.nan, 0.)
 
         if isinstance(sky_diffuse, pd.Series):
             diffuse_components = pd.DataFrame(diffuse_components)
@@ -1111,10 +1112,10 @@ def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     diffuse_components : OrderedDict (array input) or DataFrame (Series input)
         Keys/columns are:
-            * sky_diffuse: Total sky diffuse
-            * isotropic
-            * circumsolar
-            * horizon
+            * poa_sky_diffuse: Total sky diffuse
+            * poa_isotropic
+            * poa_circumsolar
+            * poa_horizon
 
 
     References
@@ -1197,12 +1198,12 @@ def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     if return_components:
         diffuse_components = OrderedDict()
-        diffuse_components['sky_diffuse'] = sky_diffuse
+        diffuse_components['poa_sky_diffuse'] = sky_diffuse
 
         # Calculate the different components
-        diffuse_components['isotropic'] = dhi * term1
-        diffuse_components['circumsolar'] = dhi * term2
-        diffuse_components['horizon'] = dhi * term3
+        diffuse_components['poa_isotropic'] = dhi * term1
+        diffuse_components['poa_circumsolar'] = dhi * term2
+        diffuse_components['poa_horizon'] = dhi * term3
 
         # Set values of components to 0 when sky_diffuse is 0
         mask = sky_diffuse == 0
@@ -1353,10 +1354,10 @@ def perez_driesse(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     diffuse_components : OrderedDict (array input) or DataFrame (Series input)
         Keys/columns are:
-            * sky_diffuse: Total sky diffuse
-            * isotropic
-            * circumsolar
-            * horizon
+            * poa_sky_diffuse: Total sky diffuse
+            * poa_isotropic
+            * poa_circumsolar
+            * poa_horizon
 
     Notes
     -----
@@ -1417,12 +1418,12 @@ def perez_driesse(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     if return_components:
         diffuse_components = OrderedDict()
-        diffuse_components['sky_diffuse'] = sky_diffuse
+        diffuse_components['poa_sky_diffuse'] = sky_diffuse
 
         # Calculate the different components
-        diffuse_components['isotropic'] = dhi * term1
-        diffuse_components['circumsolar'] = dhi * term2
-        diffuse_components['horizon'] = dhi * term3
+        diffuse_components['poa_isotropic'] = dhi * term1
+        diffuse_components['poa_circumsolar'] = dhi * term2
+        diffuse_components['poa_horizon'] = dhi * term3
 
         if isinstance(sky_diffuse, pd.Series):
             diffuse_components = pd.DataFrame(diffuse_components)

tests/test_irradiance.py

@@ -210,12 +210,14 @@ def test_haydavies(irrad_data, ephem_data, dni_et):
 
 
 def test_haydavies_components(irrad_data, ephem_data, dni_et):
+    keys = ['poa_sky_diffuse', 'poa_isotropic', 'poa_circumsolar',
+            'poa_horizon']
     expected = pd.DataFrame(np.array(
         [[0, 27.1775, 102.9949, 33.1909],
          [0, 27.1775, 30.1818, 27.9837],
          [0, 0, 72.8130, 5.2071],
          [0, 0, 0, 0]]).T,
-        columns=['sky_diffuse', 'isotropic', 'circumsolar', 'horizon'],
+        columns=keys,
         index=irrad_data.index
     )
     # pandas
@@ -229,23 +231,16 @@ def test_haydavies_components(irrad_data, ephem_data, dni_et):
         40, 180, irrad_data['dhi'].values, irrad_data['dni'].values, dni_et,
         ephem_data['apparent_zenith'].values, ephem_data['azimuth'].values,
         return_components=True)
-    assert_allclose(result['sky_diffuse'], expected['sky_diffuse'], atol=1e-4)
-    assert_allclose(result['isotropic'], expected['isotropic'], atol=1e-4)
-    assert_allclose(result['circumsolar'], expected['circumsolar'], atol=1e-4)
-    assert_allclose(result['horizon'], expected['horizon'], atol=1e-4)
+    for key in keys:
+        assert_allclose(result[key], expected[key], atol=1e-4)
     assert isinstance(result, dict)
     # scalar
     result = irradiance.haydavies(
         40, 180, irrad_data['dhi'].values[-1], irrad_data['dni'].values[-1],
         dni_et[-1], ephem_data['apparent_zenith'].values[-1],
         ephem_data['azimuth'].values[-1], return_components=True)
-    assert_allclose(result['sky_diffuse'], expected['sky_diffuse'].iloc[-1],
-                    atol=1e-4)
-    assert_allclose(result['isotropic'], expected['isotropic'].iloc[-1],
-                    atol=1e-4)
-    assert_allclose(result['circumsolar'], expected['circumsolar'].iloc[-1],
-                    atol=1e-4)
-    assert_allclose(result['horizon'], expected['horizon'].iloc[-1], atol=1e-4)
+    for key in keys:
+        assert_allclose(result[key], expected[key].iloc[-1], atol=1e-4)
     assert isinstance(result, dict)
 
 
@@ -312,13 +307,14 @@ def test_perez_components(irrad_data, ephem_data, dni_et, relative_airmass):
          [0.,  26.84138589,          np.nan,  31.72696071],
          [0.,  0.,         np.nan,  4.47966439],
          [0.,  4.62212181,         np.nan,  9.25316454]]).T,
-        columns=['sky_diffuse', 'isotropic', 'circumsolar', 'horizon'],
+        columns=['poa_sky_diffuse', 'poa_isotropic', 'poa_circumsolar',
+                 'poa_horizon'],
         index=irrad_data.index
     )
-    expected_for_sum = expected['sky_diffuse'].copy()
+    expected_for_sum = expected['poa_sky_diffuse'].copy()
     expected_for_sum.iloc[2] = 0
     sum_components = out.iloc[:, 1:].sum(axis=1)
-    sum_components.name = 'sky_diffuse'
+    sum_components.name = 'poa_sky_diffuse'
 
     assert_frame_equal(out, expected, check_less_precise=2)
     assert_series_equal(sum_components, expected_for_sum, check_less_precise=2)
@@ -338,13 +334,14 @@ def test_perez_driesse_components(irrad_data, ephem_data, dni_et,
          [0., 25.806, np.nan, 33.181],
          [0.,  0.000, np.nan,  4.197],
          [0.,  4.184, np.nan, 10.018]]).T,
-        columns=['sky_diffuse', 'isotropic', 'circumsolar', 'horizon'],
+        columns=['poa_sky_diffuse', 'poa_isotropic', 'poa_circumsolar',
+                 'poa_horizon'],
         index=irrad_data.index
     )
-    expected_for_sum = expected['sky_diffuse'].copy()
+    expected_for_sum = expected['poa_sky_diffuse'].copy()
     expected_for_sum.iloc[2] = 0
     sum_components = out.iloc[:, 1:].sum(axis=1)
-    sum_components.name = 'sky_diffuse'
+    sum_components.name = 'poa_sky_diffuse'
 
     assert_frame_equal(out, expected, check_less_precise=2)
     assert_series_equal(sum_components, expected_for_sum, check_less_precise=2)
@@ -384,13 +381,14 @@ def test_perez_negative_horizon():
          [166.785419, 142.24475, 119.173875, 83.525150, 45.725931],
          [113.548755,  16.09757,   9.956174,  3.142467,  0],
          [1.076010,  -6.13353,  -5.262151, -3.831230, -2.208923]]).T,
-        columns=['sky_diffuse', 'isotropic', 'circumsolar', 'horizon'],
+        columns=['poa_sky_diffuse', 'poa_isotropic', 'poa_circumsolar',
+                 'poa_horizon'],
         index=times
     )
 
-    expected_for_sum = expected['sky_diffuse'].copy()
+    expected_for_sum = expected['poa_sky_diffuse'].copy()
     sum_components = out.iloc[:, 1:].sum(axis=1)
-    sum_components.name = 'sky_diffuse'
+    sum_components.name = 'poa_sky_diffuse'
 
     assert_frame_equal(out, expected, check_less_precise=2)
     assert_series_equal(sum_components, expected_for_sum, check_less_precise=2)