Merge branch 'main' into update/nasa-power-variable-map

Author: AdamRJensen

docs/examples/irradiance-transposition/plot_rtranpose_limitations.py

@@ -28,7 +28,7 @@
 #
 # In this example we look at a single point in time and consider a full range
 # of possible GHI and POA global values as shown in figures 3 and 4 of [1]_.
-# Then we use :py:meth:`pvlib.irradiance.ghi_from_poa_driesse_2023` to estimate
+# Then we use :py:meth:`pvlib.irradiance.ghi_from_poa_driesse_2024` to estimate
 # the original GHI from POA global.
 #
 # References
@@ -45,7 +45,7 @@
 
 from pvlib.irradiance import (erbs_driesse,
                               get_total_irradiance,
-                              ghi_from_poa_driesse_2023,
+                              ghi_from_poa_driesse_2024,
                               )
 
 matplotlib.rcParams['axes.grid'] = True
@@ -92,7 +92,7 @@
 
 poa_test = 200
 
-ghi_hat = ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
+ghi_hat = ghi_from_poa_driesse_2024(surface_tilt, surface_azimuth,
                                     solar_zenith, solar_azimuth,
                                     poa_test,
                                     dni_extra,
@@ -156,7 +156,7 @@
 # out, other times not.
 #
 
-result = ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
+result = ghi_from_poa_driesse_2024(surface_tilt, surface_azimuth,
                                    solar_zenith, solar_azimuth,
                                    poa_global,
                                    dni_extra,

docs/examples/irradiance-transposition/plot_rtranpose_year.py

@@ -21,7 +21,7 @@
 # Recovering GHI from POA irradiance is termed "reverse transposition."
 #
 # In this example we start with a TMY file and calculate POA global irradiance.
-# Then we use :py:meth:`pvlib.irradiance.ghi_from_poa_driesse_2023` to estimate
+# Then we use :py:meth:`pvlib.irradiance.ghi_from_poa_driesse_2024` to estimate
 # the original GHI from POA global.  Details of the method found in [1]_.
 #
 # Another method for reverse tranposition called GTI-DIRINT is also
@@ -49,7 +49,7 @@
 from pvlib import iotools, location
 from pvlib.irradiance import (get_extra_radiation,
                               get_total_irradiance,
-                              ghi_from_poa_driesse_2023,
+                              ghi_from_poa_driesse_2024,
                               aoi,
                               )
 
@@ -114,7 +114,7 @@
 
 start = time.process_time()
 
-df['ghi_rev'] = ghi_from_poa_driesse_2023(TILT, ORIENT,
+df['ghi_rev'] = ghi_from_poa_driesse_2024(TILT, ORIENT,
                                           solpos.apparent_zenith,
                                           solpos.azimuth,
                                           df.poa_global,

docs/sphinx/source/reference/irradiance/reverse-transposition.rst

@@ -6,5 +6,5 @@ Reverse transposition models
 .. autosummary::
    :toctree: ../generated/
 
-   irradiance.ghi_from_poa_driesse_2023
+   irradiance.ghi_from_poa_driesse_2024
    irradiance.gti_dirint

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

@@ -10,10 +10,17 @@ Breaking Changes
 
 Deprecations
 ~~~~~~~~~~~~
+* Rename :py:func:`!pvlib.irradiance.ghi_from_poa_driesse_2023` to
+  :py:func:`~pvlib.irradiance.ghi_from_poa_driesse_2024`. The year now reflects
+  the publication date. The old name will be removed in v0.17.0.
+  (:issue:`2774`, :pull:`2777`)
 
 
 Bug fixes
 ~~~~~~~~~
+* Added test coverage for :py:func:`pvlib.irradiance.dirint` with
+  ``np.array`` and ``pd.Series`` inputs. 
+  (:issue:`2751`, :pull:`2752`)
 * Corrects a bug in :py:func:`pvlib.temperature.fuentes`. If inputs were
   data type integer, users can expect modeled cell temperature values to
   increase slightly.
@@ -22,6 +29,14 @@ Bug fixes
   introduced in v0.15.1 (:pull:`2702`) that caused a broadcasting
   ``ValueError`` when ``tracker_theta`` was a 2-D (or higher rank) array.
   (:issue:`2747`, :pull:`2749`)
+* Document that timestamps returned by :py:func:`~pvlib.iotools.get_era5`
+  represent the end of the averaging interval, consistent with ERA5
+  conventions. (:issue:`2772`, :pull:`2773`)
+
+* :py:func:`pvlib.iotools.read_nsrdb_psm4` now parses the file header with the
+  :py:mod:`csv` module instead of a naive ``str.split(',')``, so quoted column
+  names containing commas (e.g. the material names in spectral-on-demand files)
+  are no longer split into spurious columns. (:issue:`2736`, :pull:`2771`)
 
 Enhancements
 ~~~~~~~~~~~~
@@ -61,7 +76,10 @@ Maintenance
 Contributors
 ~~~~~~~~~~~~
 * :ghuser:`Omesh37`
+* :ghuser:`gaoflow`
 * Cliff Hansen (:ghuser:`cwhanse`)
+* :ghuser:`shethkajal7`
 * Arthur Onno (:ghuser:`ArthurOnnoTerabase`)
 * Adam R. Jensen (:ghuser:`AdamRJensen`)
 * Karl Hill (:ghuser:`karlhillx`)
+* Rajiv Daxini (:ghuser:`RDaxini`)

pvlib/iotools/era5.py

@@ -102,7 +102,7 @@ def get_era5(latitude, longitude, start, end, variables, api_key,
     Returns
     -------
     data : pd.DataFrame
-        Time series data. The index corresponds to the start of the interval.
+        Time series data. The index corresponds to the end of the interval.
     meta : dict
         Metadata.
 

pvlib/iotools/psm4.py

@@ -6,6 +6,7 @@
 https://developer.nlr.gov/docs/solar/nsrdb/nsrdb-GOES-full-disc-v4-0-0-download/
 """
 
+import csv
 import io
 from urllib.parse import urljoin
 import requests
@@ -723,11 +724,16 @@ def read_nsrdb_psm4(filename, map_variables=True):
        <https://web.archive.org/web/20170207203107/https://sam.nrel.gov/sites/default/files/content/documents/pdf/wfcsv.pdf>`_
     """
     with tools._file_context_manager(filename) as fbuf:
+        # The first 3 header lines are parsed with the csv module rather than a
+        # naive str.split(',') so that quoted fields containing commas are kept
+        # intact.  Spectral-on-demand files, for instance, have column names
+        # like '"GaAs (Bauhuis et al., 2009)"' whose embedded commas would
+        # otherwise be split into spurious columns (see GH #2736).
         # The first 2 lines of the response are headers with metadata
-        metadata_fields = fbuf.readline().split(',')
-        metadata_values = fbuf.readline().split(',')
+        metadata_fields = next(csv.reader([fbuf.readline()]))
+        metadata_values = next(csv.reader([fbuf.readline()]))
         # get the column names so we can set the dtypes
-        columns = fbuf.readline().split(',')
+        columns = next(csv.reader([fbuf.readline()]))
         columns[-1] = columns[-1].strip()  # strip trailing newline
         # Since the header has so many columns, excel saves blank cols in the
         # data below the header lines.

pvlib/irradiance.py

@@ -16,7 +16,7 @@
 from pvlib import atmosphere, solarposition, tools
 import pvlib  # used to avoid dni name collision in complete_irradiance
 
-from pvlib._deprecation import pvlibDeprecationWarning
+from pvlib._deprecation import pvlibDeprecationWarning, deprecated
 import warnings
 
 
@@ -132,7 +132,9 @@ def _handle_extra_radiation_types(datetime_or_doy, epoch_year):
     # a better way to do it.
     if isinstance(datetime_or_doy, pd.DatetimeIndex):
         to_doy = tools._pandas_to_doy  # won't be evaluated unless necessary
-        def to_datetimeindex(x): return x                       # noqa: E306
+
+        def to_datetimeindex(x):
+            return x                       # noqa: E306
         to_output = partial(pd.Series, index=datetime_or_doy)
     elif isinstance(datetime_or_doy, pd.Timestamp):
         to_doy = tools._pandas_to_doy
@@ -146,12 +148,14 @@ def to_datetimeindex(x): return x                       # noqa: E306
             tools._datetimelike_scalar_to_datetimeindex
         to_output = tools._scalar_out
     elif np.isscalar(datetime_or_doy):  # ints and floats of various types
-        def to_doy(x): return x                                 # noqa: E306
+        def to_doy(x):
+            return x                                 # noqa: E306
         to_datetimeindex = partial(tools._doy_to_datetimeindex,
                                    epoch_year=epoch_year)
         to_output = tools._scalar_out
     else:  # assume that we have an array-like object of doy
-        def to_doy(x): return x                                 # noqa: E306
+        def to_doy(x):
+            return x                                 # noqa: E306
         to_datetimeindex = partial(tools._doy_to_datetimeindex,
                                    epoch_year=epoch_year)
         to_output = tools._array_out
@@ -1075,7 +1079,7 @@ def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
     airmass : numeric
         Relative (not pressure-corrected) airmass values. If AM is a
         DataFrame it must be of the same size as all other DataFrame
-        inputs. AM must be >=0 (careful using the 1/sec(z) model of AM
+        inputs. AM must be >=0 (careful using the 1/cos(z) model of AM
         generation). [unitless]
 
     model : string, default 'allsitescomposite1990'
@@ -1335,7 +1339,7 @@ def perez_driesse(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
     airmass : numeric, optional
         Relative (not pressure-corrected) airmass values. If ``airmass`` is a
         DataFrame it must be of the same size as all other DataFrame
-        inputs. AM must be >=0 (careful using the 1/sec(z) model of AM
+        inputs. AM must be >=0 (careful using the 1/cos(z) model of AM
         generation). [unitless]
 
     return_components: bool (optional, default=False)
@@ -1442,7 +1446,7 @@ def _poa_from_ghi(surface_tilt, surface_azimuth,
     Transposition function that includes decomposition of GHI using the
     continuous Erbs-Driesse model.
 
-    Helper function for ghi_from_poa_driesse_2023.
+    Helper function for ghi_from_poa_driesse_2024.
     '''
     # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Nov., 2023
 
@@ -1468,7 +1472,7 @@ def _ghi_from_poa(surface_tilt, surface_azimuth,
     '''
     Reverse transposition function that uses the scalar bisection from scipy.
 
-    Helper function for ghi_from_poa_driesse_2023.
+    Helper function for ghi_from_poa_driesse_2024.
     '''
     # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Nov., 2023
 
@@ -1512,7 +1516,7 @@ def poa_error(ghi):
     return ghi, conv, niter
 
 
-def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
+def ghi_from_poa_driesse_2024(surface_tilt, surface_azimuth,
                               solar_zenith, solar_azimuth,
                               poa_global,
                               dni_extra, airmass=None, albedo=0.25,
@@ -1614,6 +1618,14 @@ def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
         return ghi
 
 
+ghi_from_poa_driesse_2023 = deprecated(
+    since="0.15.2",
+    name="pvlib.irradiance.ghi_from_poa_driesse_2023",
+    alternative="pvlib.irradiance.ghi_from_poa_driesse_2024",
+    removal="0.17.0",
+)(ghi_from_poa_driesse_2024)
+
+
 def clearsky_index(ghi, ghi_clear, max_clearsky_index=2.0):
     """
     Calculate the clearsky index.
@@ -1964,14 +1976,14 @@ def dirint(ghi, solar_zenith, times, pressure=101325., use_delta_kt_prime=True,
 
     Returns
     -------
-    dni : array-like
-        The modeled direct normal irradiance, as provided by the
-        DIRINT model. [Wm⁻²]
+    dni : pd.Series
+        Estimated direct normal irradiance. [Wm⁻²]
 
     Notes
     -----
-    DIRINT model requires time series data (ie. one of the inputs must
-    be a vector of length > 2).
+    The DIRINT model was developed for time series data with length > 2.
+    The implementation in pvlib assumes the data are periodic which may
+    affect the first and last DNI values.
 
     References
     ----------
@@ -2109,6 +2121,7 @@ def _dirint_bins(times, kt_prime, zenith, w, delta_kt_prime):
     -------
     tuple of kt_prime_bin, zenith_bin, w_bin, delta_kt_prime_bin
     """
+
     # @wholmgren: the following bin assignments use MATLAB's 1-indexing.
     # Later, we'll subtract 1 to conform to Python's 0-indexing.
 

pvlib/snow.py

@@ -248,7 +248,8 @@ def _townsend_effective_snow(snow_total, snow_events):
 
 def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
                   temp_air, poa_global, slant_height, lower_edge_height,
-                  string_factor=1.0, angle_of_repose=40):
+                  string_factor=1.0, angle_of_repose=40,
+                  front_side_fraction=1.0):
     '''
     Calculates monthly snow loss based on the Townsend monthly snow loss
     model.
@@ -293,6 +294,12 @@ def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
         Piled snow angle, assumed to stabilize at 40°, the midpoint of
         25°-55° avalanching slope angles. [deg]
 
+    front_side_fraction : numeric or array-like, default 1.0
+        Fraction of monthly energy from front-side insolation. [unitless]
+        Multiplies the calculated loss fraction. For example,
+        use 0.9 when 90% of monthly energy is from the front side
+        of a bifacial system and 10% is from the rear side.
+
     Returns
     -------
     loss : array-like
@@ -310,6 +317,10 @@ def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
     publication of [1]_, as described in [2]_.
     The definition for snow events documented above is based on [3]_.
 
+    For bifacial systems, [2]_ recommends including both front-side and
+    rear-side insolation in ``poa_global``. The resulting loss is
+    scaled by the front-side energy fraction ``front_side_fraction``.
+
     References
     ----------
     .. [1] Townsend, Tim & Powers, Loren. (2011). Photovoltaics and snow: An
@@ -384,4 +395,6 @@ def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
         * string_factor
     )
 
+    loss_fraction = loss_fraction * front_side_fraction
+
     return np.clip(loss_fraction, 0, 1)

tests/iotools/test_psm4.py

@@ -185,6 +185,31 @@ def test_read_nsrdb_psm4_map_variables():
     assert_index_equal(data.columns, pd.Index(columns_mapped))
 
 
+def test_read_nsrdb_psm4_quoted_columns_with_commas():
+    """spectral-on-demand files have quoted column names containing commas;
+    these must not be split into spurious columns (GH #2736)"""
+    # Minimal NSRDB file whose column header (3rd line) has quoted material
+    # names with embedded commas, which is valid CSV. A naive str.split(',')
+    # would break these into extra columns and raise on read.
+    content = (
+        "Source,Location ID,City,State,Country,Latitude,Longitude,Time Zone,"
+        "Elevation,Local Time Zone,Version\n"
+        "NSRDB,1,-,-,-,40.0,-105.0,-7,1600,-7,4.0.1\n"
+        'Year,Month,Day,Hour,Minute,GHI,"GaAs (Bauhuis et al., 2009)",'
+        '"InGaP (Gray, 2008)"\n'
+        "2023,1,1,0,0,0,0.1,0.2\n"
+        "2023,1,1,1,0,5,0.3,0.4\n"
+    )
+    data, metadata = psm4.read_nsrdb_psm4(StringIO(content),
+                                          map_variables=False)
+    assert list(data.columns) == [
+        'Year', 'Month', 'Day', 'Hour', 'Minute', 'GHI',
+        'GaAs (Bauhuis et al., 2009)', 'InGaP (Gray, 2008)']
+    assert data.shape == (2, 8)
+    # the embedded-comma data columns round-trip as floats
+    assert data['GaAs (Bauhuis et al., 2009)'].tolist() == [0.1, 0.3]
+
+
 @pytest.mark.remote_data
 @pytest.mark.flaky(reruns=RERUNS, reruns_delay=RERUNS_DELAY)
 def test_get_nsrdb_psm4_aggregated_parameter_mapping(nlr_api_key):