Document and test np.nan handling in spectrum.average_photon_energy (#2426)

* docs: tentative wording

* test: single+all nan (series+df)

* insert blank line

* fix test assert statement

* fix tests

* combine assert out1 lines

* equal->is

* Update v0.12.1.rst

Author: RDaxini

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

@@ -19,6 +19,8 @@ Enhancements
 Documentation
 ~~~~~~~~~~~~~
 * Add a supporting reference to :py:func:`pvlib.atmosphere.get_relative_airmass` (:issue:`2390`, :pull:`2424`)
+* Documented how `np.nan` values are handled by :py:func:`~pvlib.spectrum.average_photon_energy`
+  (:issue:`2423`, :pull:`2426`)
 
 Testing
 ~~~~~~~
@@ -31,3 +33,4 @@ Maintenance
 Contributors
 ~~~~~~~~~~~~
 * Cliff Hansen (:ghuser:`cwhanse`)
+* Rajiv Daxini (:ghuser:`RDaxini`)

pvlib/spectrum/irradiance.py

@@ -138,7 +138,8 @@ def average_photon_energy(spectra):
     ape : numeric or pandas.Series
         Average Photon Energy [eV].
         Note: returns ``np.nan`` in the case of all-zero spectral irradiance
-        input.
+        input, or where one or more spectral irradiance values is
+        ``np.nan``.
 
     Notes
     -----

tests/spectrum/test_irradiance.py

@@ -130,3 +130,24 @@ def test_average_photon_energy_zero_irr():
     expected_2 = np.nan
     assert_allclose(out_1, expected_1, atol=1e-3)
     assert_allclose(out_2, expected_2, atol=1e-3)
+
+
+def test_average_photon_energy_nan_irr():
+    # test for handling NaN input
+
+    spectra_df_nan = spectrum.get_reference_spectra().T
+    spectra_df_nan.loc["global", 315.0] = np.nan
+    spectra_df_nan.loc['extraterrestrial', :] = np.nan
+
+    spectra_series_nan = spectrum.get_reference_spectra()['global']
+    spectra_series_singlenan = spectra_series_nan.copy()
+    spectra_series_singlenan.loc[315.0] = np.nan
+    spectra_series_allnan = spectra_series_nan*np.nan
+
+    out1 = spectrum.average_photon_energy(spectra_df_nan)
+    out2 = spectrum.average_photon_energy(spectra_series_singlenan)
+    out3 = spectrum.average_photon_energy(spectra_series_allnan)
+
+    assert np.all(np.isnan(out1[['global', 'extraterrestrial']]))
+    assert np.all(np.isnan(out2))
+    assert np.all(np.isnan(out3))