pvlib 0.11.0a1__py3-none-any.whl → 0.11.2__py3-none-any.whl

pvlib/iam.py

@@ -269,8 +269,8 @@ def martin_ruiz(aoi, a_r=0.16):
 
     which is presented as :math:`AL(\alpha) = 1 - IAM` in equation 4 of [1]_,
     with :math:`\alpha` representing the angle of incidence AOI. Thus IAM = 1
-    at AOI = 0, and IAM = 0 at AOI = 90.  This equation is only valid for
-    -90 <= aoi <= 90, therefore `iam` is constrained to 0.0 outside this
+    at AOI = 0°, and IAM = 0 at AOI = 90°.  This equation is only valid for
+    0° <= aoi <= 90°, therefore `iam` is constrained to 0.0 outside this
     interval.
 
     References
@@ -891,8 +891,8 @@ def schlick_diffuse(surface_tilt):
     implements only the integrated Schlick approximation.
 
     Note also that the output of this function (which is an exact integration)
-    can be compared with the output of :py:func:`marion_diffuse` which numerically
-    integrates the Schlick approximation:
+    can be compared with the output of :py:func:`marion_diffuse` which
+    numerically integrates the Schlick approximation:
 
     .. code::
 

pvlib/iotools/midc.py

@@ -193,7 +193,7 @@ def read_midc(filename, variable_map={}, raw_data=False, **kwargs):
 
     See the MIDC_VARIABLE_MAP for collection of mappings by site.
     For a full list of pvlib variable names see the
-    :ref:`variables_style_rules`.
+    :ref:`nomenclature`.
 
     Be sure to check the units for the variables you will use on the
     `MIDC site <https://midcdmz.nrel.gov/>`_.

pvlib/iotools/pvgis.py

@@ -18,10 +18,10 @@ import io
 import json
 from pathlib import Path
 import requests
+import numpy as np
 import pandas as pd
+import pytz
 from pvlib.iotools import read_epw, parse_epw
-import warnings
-from pvlib._deprecation import pvlibDeprecationWarning
 
 URL = 'https://re.jrc.ec.europa.eu/api/'
 
@@ -390,9 +390,33 @@ def read_pvgis_hourly(filename, pvgis_format=None, map_variables=True):
     raise ValueError(err_msg)
 
 
+def _coerce_and_roll_tmy(tmy_data, tz, year):
+    """
+    Assumes ``tmy_data`` input is UTC, converts from UTC to ``tz``, rolls
+    dataframe so timeseries starts at midnight, and forces all indices to
+    ``year``. Only works for integer ``tz``, but ``None`` and ``False`` are
+    re-interpreted as zero / UTC.
+    """
+    if tz:
+        tzname = pytz.timezone(f'Etc/GMT{-tz:+d}')
+    else:
+        tz = 0
+        tzname = pytz.timezone('UTC')
+    new_index = pd.DatetimeIndex([
+        timestamp.replace(year=year, tzinfo=tzname)
+        for timestamp in tmy_data.index],
+        name=f'time({tzname})')
+    new_tmy_data = pd.DataFrame(
+        np.roll(tmy_data, tz, axis=0),
+        columns=tmy_data.columns,
+        index=new_index)
+    return new_tmy_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,
+                  roll_utc_offset=None, coerce_year=None):
     """
     Get TMY data from PVGIS.
 
@@ -424,6 +448,13 @@ 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
+    roll_utc_offset: int, optional
+        Use to specify a time zone other than the default UTC zero and roll
+        dataframe by ``roll_utc_offset`` so it starts at midnight on January
+        1st. Ignored if ``None``, otherwise will force year to ``coerce_year``.
+    coerce_year: int, optional
+        Use to force indices to desired year. Will default to 1990 if
+        ``coerce_year`` is not specified, but ``roll_utc_offset`` is specified.
 
     Returns
     -------
@@ -436,16 +467,6 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
     metadata : list or dict
         file metadata, ``None`` for basic
 
-    Note
-    ----
-    The PVGIS website uses 10 years of data to generate the TMY, whereas the
-    API accessed by this function defaults to using all available years. This
-    means that the TMY returned by this function may not be identical to the
-    one generated by the website. To replicate the website requests, specify
-    the corresponding 10 year period using ``startyear`` and ``endyear``.
-    Specifying ``endyear`` also avoids the TMY changing when new data becomes
-    available.
-
     Raises
     ------
     requests.HTTPError
@@ -510,6 +531,11 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
     if map_variables:
         data = data.rename(columns=VARIABLE_MAP)
 
+    if not (roll_utc_offset is None and coerce_year is None):
+        # roll_utc_offset is specified, but coerce_year isn't
+        coerce_year = coerce_year or 1990
+        data = _coerce_and_roll_tmy(data, roll_utc_offset, coerce_year)
+
     return data, months_selected, inputs, meta