clarify threshold_depth

Author: cwhanse

pvlib/snow.py

@@ -13,20 +13,23 @@ def _time_delta_in_hours(times):
     return delta.dt.total_seconds().div(3600)
 
 
-def fully_covered_nrel(snowfall, snow_depth=None, threshold_snowfall=1.):
+def fully_covered_nrel(snowfall, snow_depth=None, threshold_snowfall=1.,
+                       threshold_depth=1.):
     '''
     Calculates the timesteps when modules are fully covered by snow.
 
     Parameters
     ----------
     snowfall: Series
-        Accumulated snowfall in each time period. [cm]
+        Snowfall in each time period. [cm]
     snow_depth: Series, optional
         Snow depth on the ground at the beginning of each time period.
         Must have the same index as ``snowfall``. [cm]
     threshold_snowfall: float, default 1.0
         Hourly snowfall above which the row is fully covered for that hour.
         [cm/hr]
+    threshold_depth: float, default 1.0
+        Snow depth on the ground, above which snow can affect the modules. [cm]
 
     Returns
     ----------
@@ -38,9 +41,9 @@ def fully_covered_nrel(snowfall, snow_depth=None, threshold_snowfall=1.):
     -----
     Implements the model described in [1]_ with minor improvements in [2]_.
 
-    ``snow_depth`` is used to return `False` (not fully covered) when no snow
-    is present on the ground. This check is described in [2]_ as needed for
-    systems with low tilt angle.
+    ``snow_depth`` is used to return `False` (not fully covered) when snow
+    is less than ``threshold_depth. This check is described in [2]_ as needed
+    for systems with low tilt angle.
 
     References
     ----------
@@ -64,13 +67,14 @@ def fully_covered_nrel(snowfall, snow_depth=None, threshold_snowfall=1.):
     covered = (hourly_snow_rate > threshold_snowfall)
     # no coverage when no snow on the ground
     if snow_depth is not None:
-        covered = covered & (snow_depth > 0.)
+        covered = covered & (snow_depth >= threshold_depth)
     return covered
 
 
 def coverage_nrel(snowfall, poa_irradiance, temp_air, surface_tilt,
                   snow_depth=None, initial_coverage=0, threshold_snowfall=1.,
-                  can_slide_coefficient=-80., slide_amount_coefficient=0.197):
+                  threshold_depth=1., can_slide_coefficient=-80.,
+                  slide_amount_coefficient=0.197):
     '''
     Calculates the fraction of the slant height of a row of modules that is
     covered by snow at every time step.
@@ -83,7 +87,7 @@ def coverage_nrel(snowfall, poa_irradiance, temp_air, surface_tilt,
     Parameters
     ----------
     snowfall : Series
-        Accumulated snowfall within each time period. [cm]
+        Snowfall within each time period. [cm]
     poa_irradiance : Series
         Total in-plane irradiance [W/m^2]
     temp_air : Series
@@ -100,6 +104,8 @@ def coverage_nrel(snowfall, poa_irradiance, temp_air, surface_tilt,
     threshold_snowfall : float, default 1.0
         Hourly snowfall above which snow coverage is set to the row's slant
         height. [cm/hr]
+    threshold_depth: float, default 1.0
+        Snow depth on the ground, above which snow can affect the modules. [cm]
     can_slide_coefficient : float, default -80.
         Coefficient to determine if snow can slide given irradiance and air
         temperature. [W/(m^2 C)]
@@ -118,9 +124,9 @@ def coverage_nrel(snowfall, poa_irradiance, temp_air, surface_tilt,
     In [1]_, ``can_slide_coefficient`` is termed `m`, and the value of
     ``slide_amount_coefficient`` is given in tenths of a module's slant height.
 
-    ``snow_depth`` is used to set ``snow_coverage`` to 0 when no snow is
-    present on the ground. This check is described in [2]_ as needed for
-    systems with low tilt angle.
+    ``snow_depth`` is used to set ``snow_coverage`` to 0 (not fully covered)
+    when snow is less than ``threshold_depth. . This check is described in
+    [2]_ as needed for systems with low tilt angle.
 
     References
     ----------
@@ -133,7 +139,8 @@ def coverage_nrel(snowfall, poa_irradiance, temp_air, surface_tilt,
     '''
 
     # find times with new snowfall
-    new_snowfall = fully_covered_nrel(snowfall, snow_depth, threshold_snowfall)
+    new_snowfall = fully_covered_nrel(snowfall, snow_depth, threshold_snowfall,
+                                      threshold_depth)
 
     # set up output Series
     snow_coverage = pd.Series(np.nan, index=poa_irradiance.index)
@@ -162,7 +169,7 @@ def coverage_nrel(snowfall, poa_irradiance, temp_air, surface_tilt,
     if snow_depth is not None:
         # no coverage when there's no snow on the ground
         # described in [2] to avoid non-sliding snow for low-tilt systems.
-        snow_coverage[snow_depth <= 0] = 0.
+        snow_coverage[snow_depth < threshold_depth] = 0.
     # clean up periods where row is completely uncovered
     return snow_coverage.clip(lower=0)
 

pvlib/tests/test_snow.py

@@ -27,7 +27,8 @@ def test_fully_covered_nrel_with_snow_depth():
     expected = pd.Series([False, True, False, True, False, False, False],
                          index=dt)
     fully_covered = snow.fully_covered_nrel(snowfall_data,
-                                            snow_depth=snow_depth)
+                                            snow_depth=snow_depth,
+                                            threshold_depth=0.)
     assert_series_equal(expected, fully_covered)
 
 
@@ -53,6 +54,7 @@ def test_coverage_nrel_hourly():
 def test_coverage_nrel_hourly_with_snow_depth():
     surface_tilt = 45
     slide_amount_coefficient = 0.197
+    threshold_depth = 0.5
     dt = pd.date_range(start="2019-1-1 10:00:00", end="2019-1-1 17:00:00",
                        freq='1h')
     poa_irradiance = pd.Series([400, 200, 100, 1234, 134, 982, 100, 100],
@@ -62,12 +64,13 @@ def test_coverage_nrel_hourly_with_snow_depth():
     snow_depth = pd.Series([1, 1, 1, 1, 0, 1, 0, .1], index=dt)
     snow_coverage = snow.coverage_nrel(
         snowfall_data, poa_irradiance, temp_air, surface_tilt,
-        snow_depth=snow_depth, threshold_snowfall=0.6)
+        snow_depth=snow_depth, threshold_snowfall=0.6,
+        threshold_depth=threshold_depth)
 
     slide_amt = slide_amount_coefficient * sind(surface_tilt)
     covered = 1.0 - slide_amt * np.array([0, 1, 2, 3, 4, 5, 6, 7])
     expected = pd.Series(covered, index=dt)
-    expected[snow_depth <= 0] = 0
+    expected[snow_depth < threshold_depth] = 0
     assert_series_equal(expected, snow_coverage)