Update PVGIS docs and test to comply with PVGIS version 5.2

pvlib/data/pvgis_hourly_Timeseries_45.000_8.000_SA2_10kWp_CIS_5_2a_2013_2014.json

@@ -0,0 +1 @@
+{"inputs": {"location": {"latitude": 45.0, "longitude": 8.0, "elevation": 250.0}, "meteo_data": {"radiation_db": "PVGIS-SARAH2", "meteo_db": "ERA-Interim", "year_min": 2013, "year_max": 2014, "use_horizon": true, "horizon_db": null, "horizon_data": "DEM-calculated"}, "mounting_system": {"two_axis": {"slope": {"value": "-", "optimal": "-"}, "azimuth": {"value": "-", "optimal": "-"}}}, "pv_module": {"technology": "CIS", "peak_power": 10.0, "system_loss": 5.0}}, "outputs": {"hourly": [{"time": "20130101:0010", "P": 0.0, "G(i)": 0.0, "H_sun": 0.0, "T2m": -0.97, "WS10m": 1.52, "Int": 0.0}, {"time": "20130101:0110", "P": 0.0, "G(i)": 0.0, "H_sun": 0.0, "T2m": -1.06, "WS10m": 1.45, "Int": 0.0}, {"time": "20130101:0210", "P": 0.0, "G(i)": 0.0, "H_sun": 0.0, "T2m": -1.03, "WS10m": 1.45, "Int": 0.0}, {"time": "20130101:0310", "P": 0.0, "G(i)": 0.0, "H_sun": 0.0, "T2m": -0.48, "WS10m": 1.31, "Int": 0.0}, {"time": "20130101:0410", "P": 0.0, "G(i)": 0.0, "H_sun": 0.0, "T2m": -0.09, "WS10m": 1.24, "Int": 0.0}, {"time": "20130101:0510", "P": 0.0, "G(i)": 0.0, "H_sun": 0.0, "T2m": -0.38, "WS10m": 1.17, "Int": 0.0}, {"time": "20130101:0610", "P": 0.0, "G(i)": 0.0, "H_sun": 0.0, "T2m": 0.29, "WS10m": 1.03, "Int": 0.0}, {"time": "20130101:0710", "P": 0.0, "G(i)": 0.0, "H_sun": 0.0, "T2m": 1.0, "WS10m": 0.62, "Int": 0.0}, {"time": "20130101:0810", "P": 1187.2, "G(i)": 129.59, "H_sun": 8.06, "T2m": 0.97, "WS10m": 0.97, "Int": 0.0}, {"time": "20130101:0910", "P": 3950.1, "G(i)": 423.28, "H_sun": 14.8, "T2m": 1.89, "WS10m": 0.69, "Int": 0.0}]}, "meta": {"inputs": {"location": {"description": "Selected location", "variables": {"latitude": {"description": "Latitude", "units": "decimal degree"}, "longitude": {"description": "Longitude", "units": "decimal degree"}, "elevation": {"description": "Elevation", "units": "m"}}}, "meteo_data": {"description": "Sources of meteorological data", "variables": {"radiation_db": {"description": "Solar radiation database"}, "meteo_db": {"description": "Database used for meteorological variables other than solar radiation"}, "year_min": {"description": "First year of the calculations"}, "year_max": {"description": "Last year of the calculations"}, "use_horizon": {"description": "Include horizon shadows"}, "horizon_db": {"description": "Source of horizon data"}}}, "mounting_system": {"description": "Mounting system", "choices": "fixed, vertical_axis, inclined_axis, two_axis", "fields": {"slope": {"description": "Inclination angle from the horizontal plane", "units": "degree"}, "azimuth": {"description": "Orientation (azimuth) angle of the (fixed) PV system (0 = S, 90 = W, -90 = E)", "units": "degree"}}}, "pv_module": {"description": "PV module parameters", "variables": {"technology": {"description": "PV technology"}, "peak_power": {"description": "Nominal (peak) power of the PV module", "units": "kW"}, "system_loss": {"description": "Sum of system losses", "units": "%"}}}}, "outputs": {"hourly": {"type": "time series", "timestamp": "hourly averages", "variables": {"P": {"description": "PV system power", "units": "W"}, "G(i)": {"description": "Global irradiance on the inclined plane (plane of the array)", "units": "W/m2"}, "H_sun": {"description": "Sun height", "units": "degree"}, "T2m": {"description": "2-m air temperature", "units": "degree Celsius"}, "WS10m": {"description": "10-m total wind speed", "units": "m/s"}, "Int": {"description": "1 means solar radiation values are reconstructed"}}}}}}

pvlib/iotools/pvgis.py

@@ -26,7 +26,7 @@
 URL = 'https://re.jrc.ec.europa.eu/api/'
 
 # Dictionary mapping PVGIS names to pvlib names
-PVGIS_VARIABLE_MAP = {
+VARIABLE_MAP = {
     'G(h)': 'ghi',
     'Gb(n)': 'dni',
     'Gd(h)': 'dhi',
@@ -112,10 +112,11 @@ def get_pvgis_hourly(latitude, longitude, start=None, end=None,
         documentation [2]_ for more info.
     url: str, default: :const:`pvlib.iotools.pvgis.URL`
         Base url of PVGIS API. ``seriescalc`` is appended to get hourly data
-        endpoint.
+        endpoint. Note, a specific PVGIS version can be specified, e.g.,
+        https://re.jrc.ec.europa.eu/api/v5_2/
     map_variables: bool, default: True
         When true, renames columns of the Dataframe to pvlib variable names
-        where applicable. See variable PVGIS_VARIABLE_MAP.
+        where applicable. See variable :const:`VARIABLE_MAP`.
     timeout: int, default: 30
         Time in seconds to wait for server response before timeout
 
@@ -138,10 +139,10 @@ def get_pvgis_hourly(latitude, longitude, start=None, end=None,
     Hint
     ----
     PVGIS provides access to a number of different solar radiation datasets,
-    including satellite-based (SARAH, CMSAF, and NSRDB PSM3) and re-analysis
-    products (ERA5 and COSMO). Each data source has a different geographical
-    coverage and time stamp convention, e.g., SARAH and CMSAF provide
-    instantaneous values, whereas values from ERA5 are averages for the hour.
+    including satellite-based (SARAH, SARAH2, and NSRDB PSM3) and re-analysis
+    products (ERA5). Each data source has a different geographical coverage and
+    time stamp convention, e.g., SARAH and SARAH2 provide instantaneous values,
+    whereas values from ERA5 are averages for the hour.
 
     Notes
     -----
@@ -172,6 +173,12 @@ def get_pvgis_hourly(latitude, longitude, start=None, end=None,
     --------
     pvlib.iotools.read_pvgis_hourly, pvlib.iotools.get_pvgis_tmy
 
+    Examples
+    --------
+    >>> # Retrieve two years of irradiance data from PVGIS:
+    >>> data, meta, inputs = pvlib.iotools.get_pvgis_hourly(  # doctest: +SKIP
+    >>>    latitude=45, longitude=8, start=2015, end=2016)  # doctest: +SKIP
+
     References
     ----------
     .. [1] `PVGIS <https://ec.europa.eu/jrc/en/pvgis>`_
@@ -228,7 +235,7 @@ def _parse_pvgis_hourly_json(src, map_variables):
     data = data.drop('time', axis=1)
     data = data.astype(dtype={'Int': 'int'})  # The 'Int' column to be integer
     if map_variables:
-        data = data.rename(columns=PVGIS_VARIABLE_MAP)
+        data = data.rename(columns=VARIABLE_MAP)
     return data, inputs, metadata
 
 
@@ -270,7 +277,7 @@ def _parse_pvgis_hourly_csv(src, map_variables):
     data.index = pd.to_datetime(data['time'], format='%Y%m%d:%H%M', utc=True)
     data = data.drop('time', axis=1)
     if map_variables:
-        data = data.rename(columns=PVGIS_VARIABLE_MAP)
+        data = data.rename(columns=VARIABLE_MAP)
     # All columns should have the dtype=float, except 'Int' which should be
     # integer. It is necessary to convert to float, before converting to int
     data = data.astype(float).astype(dtype={'Int': 'int'})
@@ -297,7 +304,7 @@ def read_pvgis_hourly(filename, pvgis_format=None, map_variables=True):
         ``pvgis_format`` is required and must be in ``['csv', 'json']``.
     map_variables: bool, default True
         When true, renames columns of the DataFrame to pvlib variable names
-        where applicable. See variable PVGIS_VARIABLE_MAP.
+        where applicable. See variable :const:`VARIABLE_MAP`.
 
     Returns
     -------
@@ -369,8 +376,9 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
                   userhorizon=None, startyear=None, endyear=None, url=URL,
                   map_variables=None, timeout=30):
     """
-    Get TMY data from PVGIS. For more information see the PVGIS [1]_ TMY tool
-    documentation [2]_.
+    Get TMY data from PVGIS.
+
+    For more information see the PVGIS [1]_ TMY tool documentation [2]_.
 
     Parameters
     ----------
@@ -396,7 +404,7 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
         base url of PVGIS API, append ``tmy`` to get TMY endpoint
     map_variables: bool
         When true, renames columns of the Dataframe to pvlib variable names
-        where applicable. See variable PVGIS_VARIABLE_MAP.
+        where applicable. See variable const:`VARIABLE_MAP`.
     timeout : int, default 30
         time in seconds to wait for server response before timeout
 
@@ -428,13 +436,12 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
         the error message in the response will be raised as an exception,
         otherwise raise whatever ``HTTP/1.1`` error occurred
 
-    See also
+    See Also
     --------
     read_pvgis_tmy
 
     References
     ----------
-
     .. [1] `PVGIS <https://ec.europa.eu/jrc/en/pvgis>`_
     .. [2] `PVGIS TMY tool <https://ec.europa.eu/jrc/en/PVGIS/tools/tmy>`_
     .. [3] `PVGIS horizon profile tool
@@ -492,7 +499,7 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
         )
         map_variables = False
     if map_variables:
-        data = data.rename(columns=PVGIS_VARIABLE_MAP)
+        data = data.rename(columns=VARIABLE_MAP)
 
     return data, months_selected, inputs, meta
 
@@ -566,7 +573,7 @@ def read_pvgis_tmy(filename, pvgis_format=None, map_variables=None):
         be in ``['csv', 'epw', 'json', 'basic']``.
     map_variables: bool
         When true, renames columns of the Dataframe to pvlib variable names
-        where applicable. See variable PVGIS_VARIABLE_MAP.
+        where applicable. See variable :const:`VARIABLE_MAP`.
 
 
     Returns
@@ -584,12 +591,12 @@ def read_pvgis_tmy(filename, pvgis_format=None, map_variables=None):
     ------
     ValueError
         if ``pvgis_format`` is ``None`` and the file extension is neither
-        ``.csv``, ``.json``, nor ``.epw``, or if ``pvgis_format`` is provided as
-        input but isn't in ``['csv', 'epw', 'json', 'basic']``
+        ``.csv``, ``.json``, nor ``.epw``, or if ``pvgis_format`` is provided
+        as input but isn't in ``['csv', 'epw', 'json', 'basic']``
     TypeError
         if ``pvgis_format`` is ``None`` and ``filename`` is a buffer
 
-    See also
+    See Also
     --------
     get_pvgis_tmy
     """
@@ -655,7 +662,6 @@ def read_pvgis_tmy(filename, pvgis_format=None, map_variables=None):
         )
         map_variables = False
     if map_variables:
-        data = data.rename(columns=PVGIS_VARIABLE_MAP)
+        data = data.rename(columns=VARIABLE_MAP)
 
     return data, months_selected, inputs, meta
-