coerce and rotate pvgis TMY data to desired tz and year

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

@@ -16,6 +16,10 @@ Enhancements
 * Add new parameters for min/max absolute air mass to
   :py:func:`pvlib.spectrum.spectral_factor_firstsolar`.
   (:issue:`2086`, :pull:`2100`)
+* Add ``utc_offset`` and ``coerce_year`` arguments to
+  :py:func:`pvlib.iotools.get_pvgis_tmy` to allow user to specify time zone,
+  rotate indices of TMY to begin at midnight, and force indices to desired
+  year. (:issue:`2139`, :pull:`2138`)
 
 
 Bug fixes
@@ -45,4 +49,4 @@ Contributors
 * Leonardo Micheli (:ghuser:`lmicheli`)
 * Echedey Luis (:ghuser:`echedey-ls`)
 * Rajiv Daxini (:ghuser:`RDaxini`)
-
+* Mark A. Mikofski (:ghuser:`mikofski`)

pvlib/iotools/pvgis.py

@@ -14,6 +14,7 @@
 * `monthly radiation
   <https://ec.europa.eu/jrc/en/PVGIS/tools/monthly-radiation>`_
 """
+import calendar
 import io
 import json
 from pathlib import Path
@@ -390,9 +391,32 @@ def read_pvgis_hourly(filename, pvgis_format=None, map_variables=True):
     raise ValueError(err_msg)
 
 
+def _coerce_and_rotate_pvgis(pvgis_data, tz, year):
+    """
+    After converting TZ, rotate indices so timeseries starts at midnight
+    and force all indices to a common year. Only works for integer TZ.
+    """
+    # assert tz//1 == tz
+    tzname = f'Etc/GMT{-tz:+d}'
+    # check if February is leap year
+    feb1 = pvgis_data[pvgis_data.index.month == 2].index.year[0]
+    if calendar.isleap(feb1):
+        # replace Feb year with a non-leap year
+        pvgis_data.index = [
+            ts.replace(year=1990) if ts.month == 2 else ts
+            for ts in pvgis_data.index]
+    pvgis_data = pd.concat(
+        [pvgis_data.iloc[-tz:], pvgis_data.iloc[:-tz]],
+        axis=0).tz_convert(tzname)
+    pvgis_data.index = [
+        timestamp.replace(year=year) for timestamp in pvgis_data.index]
+    return pvgis_data
+
+
 def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
                   userhorizon=None, startyear=None, endyear=None,
-                  map_variables=True, url=URL, timeout=30):
+                  map_variables=True, url=URL, timeout=30,
+                  utc_offset=0, coerce_year=1990):
     """
     Get TMY data from PVGIS.
 
@@ -424,6 +448,12 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
         base url of PVGIS API, append ``tmy`` to get TMY endpoint
     timeout : int, default 30
         time in seconds to wait for server response before timeout
+    utc_offset: int, default 0
+        Use to specify a timezone other than the default UTC zero. Will force
+        year to ``coerce_year`` if not zero.
+    coerce_year: int, default 1990
+        Use to force indices to desired year. Ignored if ``utc_offset`` is
+        zero.
 
     Returns
     -------
@@ -510,6 +540,9 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
     if map_variables:
         data = data.rename(columns=VARIABLE_MAP)
 
+    if utc_offset != 0:
+        data = _coerce_and_rotate_pvgis(data, utc_offset, coerce_year)
+
     return data, months_selected, inputs, meta
 
 

pvlib/tests/iotools/test_pvgis.py

@@ -435,6 +435,22 @@ def _compare_pvgis_tmy_basic(expected, meta_expected, pvgis_data):
         assert np.allclose(data[outvar], expected[outvar])
 
 
+@pytest.mark.remote_data
+@pytest.mark.flaky(reruns=RERUNS, reruns_delay=RERUNS_DELAY)
+def test_get_pvgis_tmy_coerce_year():
+    """test utc_offset and coerce_year work as expected"""
+    pvgis_data = get_pvgis_tmy(45, 8, utc_offset=2)  # Turin
+    jan1_midnight1990 = pd.Timestamp('1990-01-01 00:00:00', tz='Etc/GMT-2')
+    dec31_midnight1990 = pd.Timestamp('1990-12-31 23:00:00', tz='Etc/GMT-2')
+    assert pvgis_data[0].index[0] == jan1_midnight1990
+    assert pvgis_data[0].index[-1] == dec31_midnight1990
+    pvgis_data = get_pvgis_tmy(45, 8, utc_offset=2, coerce_year=2021)  # Turin
+    jan1_midnight2021 = pd.Timestamp('2021-01-01 00:00:00', tz='Etc/GMT-2')
+    dec31_midnight2021 = pd.Timestamp('2021-12-31 23:00:00', tz='Etc/GMT-2')
+    assert pvgis_data[0].index[0] == jan1_midnight2021
+    assert pvgis_data[0].index[-1] == dec31_midnight2021
+
+
 @pytest.mark.remote_data
 @pytest.mark.flaky(reruns=RERUNS, reruns_delay=RERUNS_DELAY)
 def test_get_pvgis_tmy_csv(expected, month_year_expected, inputs_expected,