Add get_nsrdb_psm4_polar_tmy

Author: AdamRJensen

docs/sphinx/source/reference/iotools.rst

@@ -81,6 +81,7 @@ Satellite-derived irradiance and weather data for the Americas.
    iotools.get_nsrdb_psm4_conus
    iotools.get_nsrdb_psm4_full_disc
    iotools.get_nsrdb_psm4_polar
+   iotools.get_nsrdb_psm4_polar_tmy
    iotools.read_nsrdb_psm4
 
 

pvlib/iotools/__init__.py

@@ -13,6 +13,7 @@
 from pvlib.iotools.psm4 import get_nsrdb_psm4_conus  # noqa: F401
 from pvlib.iotools.psm4 import get_nsrdb_psm4_full_disc  # noqa: F401
 from pvlib.iotools.psm4 import get_nsrdb_psm4_polar  # noqa: F401
+from pvlib.iotools.psm4 import get_nsrdb_psm4_polar_tmy  # noqa: F401
 from pvlib.iotools.psm4 import read_nsrdb_psm4  # noqa: F401
 from pvlib.iotools.pvgis import get_pvgis_tmy, read_pvgis_tmy  # noqa: F401
 from pvlib.iotools.pvgis import read_pvgis_hourly  # noqa: F401

pvlib/iotools/psm4.py

@@ -164,7 +164,8 @@ def get_nsrdb_psm4_aggregated(latitude, longitude, api_key, email,
     See Also
     --------
     pvlib.iotools.get_nsrdb_psm4_tmy, pvlib.iotools.get_nsrdb_psm4_conus,
-    pvlib.iotools.get_nsrdb_psm4_full_disc, pvlib.iotools.read_nsrdb_psm4
+    pvlib.iotools.get_nsrdb_psm4_full_disc, pvlib.iotools.get_nsrdb_psm4_polar,
+    pvlib.iotools.get_nsrdb_psm4_polar_tmy, pvlib.iotools.read_nsrdb_psm4
 
     References
     ----------
@@ -300,8 +301,10 @@ def get_nsrdb_psm4_tmy(latitude, longitude, api_key, email, year='tmy',
 
     See Also
     --------
+    pvlib.iotools.get_nsrdb_psm4_polar_tmy,
     pvlib.iotools.get_nsrdb_psm4_aggregated,
     pvlib.iotools.get_nsrdb_psm4_conus, pvlib.iotools.get_nsrdb_psm4_full_disc,
+    pvlib.iotools.get_nsrdb_psm4_polar,
     pvlib.iotools.read_nsrdb_psm4
 
     References
@@ -436,9 +439,9 @@ def get_nsrdb_psm4_conus(latitude, longitude, api_key, email, year,
 
     See Also
     --------
-    pvlib.iotools.get_nsrdb_psm4_aggregated,
-    pvlib.iotools.get_nsrdb_psm4_tmy, pvlib.iotools.get_nsrdb_psm4_full_disc,
-    pvlib.iotools.read_nsrdb_psm4
+    pvlib.iotools.get_nsrdb_psm4_aggregated, pvlib.iotools.get_nsrdb_psm4_tmy,
+    pvlib.iotools.get_nsrdb_psm4_full_disc, pvlib.iotools.get_nsrdb_psm4_polar,
+    pvlib.iotools.get_nsrdb_psm4_polar_tmy, pvlib.iotools.read_nsrdb_psm4
 
     References
     ----------
@@ -575,9 +578,9 @@ def get_nsrdb_psm4_full_disc(latitude, longitude, api_key, email,
 
     See Also
     --------
-    pvlib.iotools.get_nsrdb_psm4_aggregated,
-    pvlib.iotools.get_nsrdb_psm4_tmy, pvlib.iotools.get_nsrdb_psm4_conus,
-    pvlib.iotools.read_nsrdb_psm4
+    pvlib.iotools.get_nsrdb_psm4_aggregated, pvlib.iotools.get_nsrdb_psm4_tmy,
+    pvlib.iotools.get_nsrdb_psm4_conus, pvlib.iotools.get_nsrdb_psm4_polar,
+    pvlib.iotools.get_nsrdb_psm4_polar_tmy, pvlib.iotools.read_nsrdb_psm4
 
     References
     ----------
@@ -640,7 +643,7 @@ def get_nsrdb_psm4_polar(latitude, longitude, api_key, email,
     Retrieve timeseries weather data from the PSM4 NSRDB Polar API.
 
     The NSRDB is described in [1]_ and the NSRDB PSM4 NSRDB Polar v4 dataset
-    is described in [2]_, [3]_. The Polar dataset extends NSRDB coverage to
+    is described in [2]_, [3]_. The polar dataset extends NSRDB coverage to
     high latitude regions, that are outside the field of view of the
     geostationary satellites.
 
@@ -721,6 +724,7 @@ def get_nsrdb_psm4_polar(latitude, longitude, api_key, email,
     --------
     pvlib.iotools.get_nsrdb_psm4_aggregated, pvlib.iotools.get_nsrdb_psm4_tmy,
     pvlib.iotools.get_nsrdb_psm4_conus, pvlib.iotools.get_nsrdb_psm4_full_disc,
+    pvlib.iotools.get_nsrdb_psm4_polar, pvlib.iotools.get_nsrdb_psm4_polar_tmy,
     pvlib.iotools.read_nsrdb_psm4
 
     References
@@ -776,6 +780,152 @@ def get_nsrdb_psm4_polar(latitude, longitude, api_key, email,
     return read_nsrdb_psm4(fbuf, map_variables)
 
 
+def get_nsrdb_psm4_polar_tmy(latitude, longitude, api_key, email, year='tmy',
+                             time_step=60, parameters=PARAMETERS,
+                             leap_day=False, full_name=PVLIB_PYTHON,
+                             affiliation=PVLIB_PYTHON, utc=False,
+                             map_variables=True, url=None, timeout=30):
+    """
+    Retrieve timeseries weather data from the PSM4 NSRDB Polar TMY v4 API.
+
+    The NSRDB is described in [1]_ and the NSRDB PSM4 Polar TMY v4 dataset is
+    described in [2]_, [3]_. The polar dataset extends NSRDB coverage to high
+    latitude polar regions, that are outside the field of view of the
+    geostationary satellites.
+
+    The dataset provides typical year data over the exclusive economic zone
+    above 60 degrees north. The data have a spatial resolution of 4 km and a
+    temporal resolution of 1 hour.
+
+    Parameters
+    ----------
+    latitude : float or int
+        in decimal degrees, between 60 and 90 degrees north
+    longitude : float or int
+        in decimal degrees, between -180 and 180, east is positive
+    api_key : str
+        NLR Developer Network API key
+    email : str
+        NLR API uses this to automatically communicate messages back
+        to the user only if necessary
+    year : str, default 'tmy'
+        PSM4 API parameter specifing TMY variant to download (e.g. ``'tmy'``
+        or ``'tgy-2023'``). The allowed values update periodically, so
+        consult the NSRDB references below for the current set of options.
+        Called ``names`` in NSRDB API.
+    time_step : int, {60}
+        time step in minutes. Must be 60 for typical year requests. Called
+        ``interval`` in NSRDB API.
+    parameters : list of str, optional
+        meteorological fields to fetch. If not specified, defaults to
+        ``pvlib.iotools.psm4.PARAMETERS``. See reference [2]_ for a list of
+        available fields. Alternatively, pvlib names may also be used (e.g.
+        'ghi' rather than 'GHI'); see :const:`REQUEST_VARIABLE_MAP`. To
+        retrieve all available fields, set ``parameters=[]``.
+    leap_day : bool, default : False
+        Include leap day in the results. Ignored for tmy/tgy/tdy requests.
+    full_name : str, default 'pvlib python'
+        optional
+    affiliation : str, default 'pvlib python'
+        optional
+    utc: bool, default : False
+        retrieve data with timestamps converted to UTC. False returns
+        timestamps in local standard time of the selected location
+    map_variables : bool, default True
+        When true, renames columns of the Dataframe to pvlib variable names
+        where applicable. See variable :const:`VARIABLE_MAP`.
+    url : str, optional
+        Full API endpoint URL. If not specified, the PSM4 Polar TMY v4 URL
+        is used.
+    timeout : int, default 30
+        time in seconds to wait for server response before timeout
+
+    Returns
+    -------
+    data : pandas.DataFrame
+        timeseries data from NLR PSM4
+    metadata : dict
+        metadata from NLR PSM4 about the record, see
+        :func:`pvlib.iotools.read_nsrdb_psm4` for fields
+
+    Raises
+    ------
+    requests.HTTPError
+        if the request response status is not ok, then the ``'errors'`` field
+        from the JSON response or any error message in the content will be
+        raised as an exception, for example if the `api_key` was rejected or if
+        the coordinates were not found in the NSRDB
+
+    Notes
+    -----
+    The required NLR developer key, `api_key`, is available for free by
+    registering at the `NLR Developer Network <https://developer.nlr.gov/>`_.
+
+    .. warning:: The "DEMO_KEY" `api_key` is severely rate limited and may
+        result in rejected requests.
+
+    .. warning:: PSM4 is limited to data found in the NSRDB, please consult
+        the references below for locations with available data.
+
+    See Also
+    --------
+    pvlib.iotools.get_nsrdb_psm4_polar, pvlib.iotools.get_nsrdb_psm4_tmy,
+    pvlib.iotools.get_nsrdb_psm4_aggregated, pvlib.iotools.get_nsrdb_psm4_conus,
+    pvlib.iotools.get_nsrdb_psm4_full_disc, pvlib.iotools.read_nsrdb_psm4
+
+    References
+    ----------
+    .. [1] `NLR National Solar Radiation Database (NSRDB)
+       <https://developer.nlr.gov/docs/solar/nsrdb/>`_
+    .. [2] `NLR NSRDB Polar Data
+       <https://nsrdb.nlr.gov/data-sets/polar-data/>`_
+    .. [3] `NSRDB Polar Tmy V4.0.0
+       <https://developer.nlr.gov/docs/solar/nsrdb/nsrdb-polar-tmy-v4-0-0-download/>`_
+    """
+    # The well know text (WKT) representation of geometry notation is strict.
+    # A POINT object is a string with longitude first, then the latitude, with
+    # four decimals each, and exactly one space between them.
+    longitude = ('%9.4f' % longitude).strip()
+    latitude = ('%8.4f' % latitude).strip()
+    # TODO: make format_WKT(object_type, *args) in tools.py
+
+    # convert pvlib names in parameters to PSM4 convention
+    parameters = [REQUEST_VARIABLE_MAP.get(a, a) for a in parameters]
+
+    # required query-string parameters for request to PSM4 API
+    params = {
+        'api_key': api_key,
+        'full_name': full_name,
+        'email': email,
+        'affiliation': affiliation,
+        'reason': PVLIB_PYTHON,
+        'mailing_list': 'false',
+        'wkt': 'POINT(%s %s)' % (longitude, latitude),
+        'names': year,
+        'attributes':  ','.join(parameters),
+        'leap_day': str(leap_day).lower(),
+        'utc': str(utc).lower(),
+        'interval': time_step
+    }
+    # request CSV download from NLR PSM4
+    if url is None:
+        url = PSM4_POLAR_TMY_URL
+
+    response = requests.get(url, params=params, timeout=timeout)
+    if not response.ok:
+        # if the API key is rejected, then the response status will be 403
+        # Forbidden, and then the error is in the content and there is no JSON
+        try:
+            errors = response.json()['errors']
+        except JSONDecodeError:
+            errors = response.content.decode('utf-8')
+        raise requests.HTTPError(errors, response=response)
+    # the CSV is in the response content as a UTF-8 bytestring
+    # to use pandas we need to create a file buffer from the response
+    fbuf = io.StringIO(response.content.decode('utf-8'))
+    return read_nsrdb_psm4(fbuf, map_variables)
+
+
 def read_nsrdb_psm4(filename, map_variables=True):
     """
     Read an NSRDB PSM4 weather file (formatted as SAM CSV).
@@ -867,6 +1017,8 @@ def read_nsrdb_psm4(filename, map_variables=True):
     pvlib.iotools.get_nsrdb_psm4_tmy
     pvlib.iotools.get_nsrdb_psm4_conus
     pvlib.iotools.get_nsrdb_psm4_full_disc
+    pvlib.iotools.get_nsrdb_psm4_polar
+    pvlib.iotools.get_nsrdb_psm4_polar_tmy
 
     References
     ----------