spectral_factor_firstsolar: rename pw to precipitable_water (#1768)

* rename parameter, and docstring cleanup

* whatsnew

* edits from review

* update tests

Author: kandersolar

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

@@ -10,6 +10,9 @@ Breaking Changes
 * Modified the ``surface_azimuth`` parameter in :py:func:`pvlib.iotools.get_pvgis_hourly` to conform to the
   pvlib azimuth convention (counterclockwise from north). Previously 0 degrees represented south.
   (:issue:`1724`, :pull:`1739`)
+* For consistency with the rest of pvlib, the ``pw`` parameters are renamed to
+  ``precipitable_water`` in :py:func:`pvlib.spectrum.spectral_factor_firstsolar`.
+  (:pull:`1768`)
 * For consistency with the rest of pvlib, the ``tilt`` parameter is renamed
   to ``surface_tilt`` in :py:func:`pvlib.soiling.hsu`. (:issue:`1717`, :pull:`1738`)
 

pvlib/spectrum/mismatch.py

@@ -239,8 +239,10 @@ def integrate(e):
     return smm
 
 
-def spectral_factor_firstsolar(pw, airmass_absolute, module_type=None,
-                               coefficients=None, min_pw=0.1, max_pw=8):
+def spectral_factor_firstsolar(precipitable_water, airmass_absolute,
+                               module_type=None, coefficients=None,
+                               min_precipitable_water=0.1,
+                               max_precipitable_water=8):
     r"""
     Spectral mismatch modifier based on precipitable water and absolute
     (pressure-adjusted) airmass.
@@ -277,21 +279,13 @@ def spectral_factor_firstsolar(pw, airmass_absolute, module_type=None,
 
     Parameters
     ----------
-    pw : array-like
+    precipitable_water : numeric
         atmospheric precipitable water. [cm]
 
-    airmass_absolute : array-like
+    airmass_absolute : numeric
         absolute (pressure-adjusted) airmass. [unitless]
 
-    min_pw : float, default 0.1
-        minimum atmospheric precipitable water. Any pw value lower than min_pw
-        is set to min_pw to avoid model divergence. [cm]
-
-    max_pw : float, default 8
-        maximum atmospheric precipitable water. Any pw value higher than max_pw
-        is set to NaN to avoid model divergence. [cm]
-
-    module_type : None or string, default None
+    module_type : str, optional
         a string specifying a cell type. Values of 'cdte', 'monosi', 'xsi',
         'multisi', and 'polysi' (can be lower or upper case). If provided,
         module_type selects default coefficients for the following modules:
@@ -307,7 +301,7 @@ def spectral_factor_firstsolar(pw, airmass_absolute, module_type=None,
         Manufacturer 2 Model C from [3]_. The spectral response (SR) of CIGS
         and a-Si modules used to derive coefficients can be found in [4]_
 
-    coefficients : None or array-like, default None
+    coefficients : array-like, optional
         Allows for entry of user-defined spectral correction
         coefficients. Coefficients must be of length 6. Derivation of
         coefficients requires use of SMARTS and PV module quantum
@@ -317,10 +311,20 @@ def spectral_factor_firstsolar(pw, airmass_absolute, module_type=None,
         modules with very similar quantum efficiency should be similar,
         in most cases limiting the need for module specific coefficients.
 
+    min_precipitable_water : float, default 0.1
+        minimum atmospheric precipitable water. Any ``precipitable_water``
+        value lower than ``min_precipitable_water``
+        is set to ``min_precipitable_water`` to avoid model divergence. [cm]
+
+    max_precipitable_water : float, default 8
+        maximum atmospheric precipitable water. Any ``precipitable_water``
+        value greater than ``max_precipitable_water``
+        is set to ``np.nan`` to avoid model divergence. [cm]
+
     Returns
     -------
     modifier: array-like
-        spectral mismatch factor (unitless) which is can be multiplied
+        spectral mismatch factor (unitless) which can be multiplied
         with broadband irradiance reaching a module's cells to estimate
         effective irradiance, i.e., the irradiance that is converted to
         electrical current.
@@ -347,16 +351,16 @@ def spectral_factor_firstsolar(pw, airmass_absolute, module_type=None,
     # *** Pw ***
     # Replace Pw Values below 0.1 cm with 0.1 cm to prevent model from
     # diverging"
-    pw = np.atleast_1d(pw)
+    pw = np.atleast_1d(precipitable_water)
     pw = pw.astype('float64')
-    if np.min(pw) < min_pw:
-        pw = np.maximum(pw, min_pw)
-        warn(f'Exceptionally low pw values replaced with {min_pw} cm to '
-             'prevent model divergence')
+    if np.min(pw) < min_precipitable_water:
+        pw = np.maximum(pw, min_precipitable_water)
+        warn('Exceptionally low pw values replaced with '
+             f'{min_precipitable_water} cm to prevent model divergence')
 
     # Warn user about Pw data that is exceptionally high
-    if np.max(pw) > max_pw:
-        pw[pw > max_pw] = np.nan
+    if np.max(pw) > max_precipitable_water:
+        pw[pw > max_precipitable_water] = np.nan
         warn('Exceptionally high pw values replaced by np.nan: '
              'check input data.')
 

pvlib/tests/test_spectrum.py

@@ -243,7 +243,8 @@ def test_spectral_factor_firstsolar_range():
     expected = np.array([0.96080878, 1.03055092, np.nan])
     assert_allclose(out, expected, atol=1e-3)
     with pytest.warns(UserWarning, match='Exceptionally high pw values'):
-        out = spectrum.spectral_factor_firstsolar(6, 1.5, max_pw=5,
+        out = spectrum.spectral_factor_firstsolar(6, 1.5,
+                                                  max_precipitable_water=5,
                                                   module_type='monosi')
     with pytest.warns(UserWarning, match='Exceptionally low pw values'):
         out = spectrum.spectral_factor_firstsolar(np.array([0, 3, 8]),
@@ -252,7 +253,8 @@ def test_spectral_factor_firstsolar_range():
     expected = np.array([0.96080878, 1.03055092, 1.04932727])
     assert_allclose(out, expected, atol=1e-3)
     with pytest.warns(UserWarning, match='Exceptionally low pw values'):
-        out = spectrum.spectral_factor_firstsolar(0.2, 1.5, min_pw=1,
+        out = spectrum.spectral_factor_firstsolar(0.2, 1.5,
+                                                  min_precipitable_water=1,
                                                   module_type='monosi')