pvlib 0.9.4a1__py3-none-any.whl → 0.10.0__py3-none-any.whl

pvlib/iotools/psm3.py

@@ -11,17 +11,16 @@ import warnings
 from pvlib._deprecation import pvlibDeprecationWarning
 
 NSRDB_API_BASE = "https://developer.nrel.gov"
-PSM_URL = NSRDB_API_BASE + "/api/nsrdb/v2/solar/psm3-download.csv"
+PSM_URL = NSRDB_API_BASE + "/api/nsrdb/v2/solar/psm3-2-2-download.csv"
 TMY_URL = NSRDB_API_BASE + "/api/nsrdb/v2/solar/psm3-tmy-download.csv"
 PSM5MIN_URL = NSRDB_API_BASE + "/api/nsrdb/v2/solar/psm3-5min-download.csv"
 
-# 'relative_humidity', 'total_precipitable_water' are not available
 ATTRIBUTES = (
     'air_temperature', 'dew_point', 'dhi', 'dni', 'ghi', 'surface_albedo',
     'surface_pressure', 'wind_direction', 'wind_speed')
 PVLIB_PYTHON = 'pvlib python'
 
-# Dictionary mapping PSM3 names to pvlib names
+# Dictionary mapping PSM3 response names to pvlib names
 VARIABLE_MAP = {
     'GHI': 'ghi',
     'DHI': 'dhi',
@@ -31,19 +30,41 @@ VARIABLE_MAP = {
     'Clearsky DNI': 'dni_clear',
     'Solar Zenith Angle': 'solar_zenith',
     'Temperature': 'temp_air',
-    'Relative Humidity': 'relative_humidity',
     'Dew point': 'temp_dew',
+    'Relative Humidity': 'relative_humidity',
     'Pressure': 'pressure',
-    'Wind Direction': 'wind_direction',
     'Wind Speed': 'wind_speed',
+    'Wind Direction': 'wind_direction',
     'Surface Albedo': 'albedo',
     'Precipitable Water': 'precipitable_water',
 }
 
+# Dictionary mapping pvlib names to PSM3 request names
+# Note, PSM3 uses different names for the same variables in the
+# response and the request
+REQUEST_VARIABLE_MAP = {
+    'ghi': 'ghi',
+    'dhi': 'dhi',
+    'dni': 'dni',
+    'ghi_clear': 'clearsky_dhi',
+    'dhi_clear': 'clearsky_dhi',
+    'dni_clear': 'clearsky_dni',
+    'zenith': 'solar_zenith_angle',
+    'temp_air': 'air_temperature',
+    'temp_dew': 'dew_point',
+    'relative_humidity': 'relative_humidity',
+    'pressure': 'surface_pressure',
+    'wind_speed': 'wind_speed',
+    'wind_direction': 'wind_direction',
+    'albedo': 'surface_albedo',
+    'precipitable_water': 'total_precipitable_water',
+}
+
 
 def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
              attributes=ATTRIBUTES, leap_day=None, full_name=PVLIB_PYTHON,
-             affiliation=PVLIB_PYTHON, map_variables=None, timeout=30):
+             affiliation=PVLIB_PYTHON, map_variables=None, url=None,
+             timeout=30):
     """
     Retrieve NSRDB PSM3 timeseries weather data from the PSM3 API. The NSRDB
     is described in [1]_ and the PSM3 API is described in [2]_, [3]_, and [4]_.
@@ -53,6 +74,12 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
        and the second element is a dictionary containing metadata. Previous
        versions of this function had the return values switched.
 
+    .. versionchanged:: 0.10.0
+       The default endpoint for hourly single-year datasets is now v3.2.2.
+       The previous datasets can still be accessed (for now) by setting
+       the ``url`` parameter to the original API endpoint
+       (``"https://developer.nrel.gov/api/nsrdb/v2/solar/psm3-download.csv"``).
+
     Parameters
     ----------
     latitude : float or int
@@ -65,16 +92,19 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
         NREL API uses this to automatically communicate messages back
         to the user only if necessary
     names : str, default 'tmy'
-        PSM3 API parameter specifing year or TMY variant to download, see notes
-        below for options
+        PSM3 API parameter specifing year (e.g. ``2020``) or TMY variant
+        to download (e.g. ``'tmy'`` or ``'tgy-2019'``).  The allowed values
+        update periodically, so consult the NSRDB references below for the
+        current set of options.
     interval : int, {60, 5, 15, 30}
-        interval size in minutes, must be 5, 15, 30 or 60. Only used for
-        single-year requests (i.e., it is ignored for tmy/tgy/tdy requests).
+        interval size in minutes, must be 5, 15, 30 or 60. Must be 60 for
+        typical year requests (i.e., tmy/tgy/tdy).
     attributes : list of str, optional
         meteorological fields to fetch. If not specified, defaults to
         ``pvlib.iotools.psm3.ATTRIBUTES``. See references [2]_, [3]_, and [4]_
         for lists of available fields. Alternatively, pvlib names may also be
-        used (e.g. 'ghi' rather than 'GHI'); see :const:`VARIABLE_MAP`.
+        used (e.g. 'ghi' rather than 'GHI'); see :const:`REQUEST_VARIABLE_MAP`.
+        To retrieve all available fields, set ``attributes=[]``.
     leap_day : boolean, default False
         include leap day in the results. Only used for single-year requests
         (i.e., it is ignored for tmy/tgy/tdy requests).
@@ -82,9 +112,12 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
         optional
     affiliation : str, default 'pvlib python'
         optional
-    map_variables: boolean, optional
+    map_variables : boolean, optional
         When true, renames columns of the Dataframe to pvlib variable names
         where applicable. See variable :const:`VARIABLE_MAP`.
+    url : str, optional
+        API endpoint URL.  If not specified, the endpoint is determined from
+        the ``names`` and ``interval`` parameters.
     timeout : int, default 30
         time in seconds to wait for server response before timeout
 
@@ -112,21 +145,6 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
     .. warning:: The "DEMO_KEY" `api_key` is severely rate limited and may
         result in rejected requests.
 
-    The PSM3 API `names` parameter must be a single value from one of these
-    lists:
-
-    +-----------+-------------------------------------------------------------+
-    | Category  | Allowed values                                              |
-    +===========+=============================================================+
-    | Year      | 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, |
-    |           | 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, |
-    |           | 2018, 2019, 2020                                            |
-    +-----------+-------------------------------------------------------------+
-    | TMY       | tmy, tmy-2016, tmy-2017, tdy-2017, tgy-2017,                |
-    |           | tmy-2018, tdy-2018, tgy-2018, tmy-2019, tdy-2019, tgy-2019  |
-    |           | tmy-2020, tdy-2020, tgy-2020                                |
-    +-----------+-------------------------------------------------------------+
-
     .. warning:: PSM3 is limited to data found in the NSRDB, please consult the
         references below for locations with available data. Additionally,
         querying data with < 30-minute resolution uses a different API endpoint
@@ -141,8 +159,8 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
 
     .. [1] `NREL National Solar Radiation Database (NSRDB)
        <https://nsrdb.nrel.gov/>`_
-    .. [2] `Physical Solar Model (PSM) v3
-       <https://developer.nrel.gov/docs/solar/nsrdb/psm3-download/>`_
+    .. [2] `Physical Solar Model (PSM) v3.2.2
+       <https://developer.nrel.gov/docs/solar/nsrdb/psm3-2-2-download/>`_
     .. [3] `Physical Solar Model (PSM) v3 TMY
        <https://developer.nrel.gov/docs/solar/nsrdb/psm3-tmy-download/>`_
     .. [4] `Physical Solar Model (PSM) v3 - Five Minute Temporal Resolution
@@ -158,12 +176,8 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
     # convert to string to accomodate integer years being passed in
     names = str(names)
 
-    # convert pvlib names in attributes to psm3 convention (reverse mapping)
-    # unlike psm3 columns, attributes are lower case and with underscores
-    amap = {value: key.lower().replace(' ', '_') for (key, value) in
-            VARIABLE_MAP.items()}
-    attributes = [amap.get(a, a) for a in attributes]
-    attributes = list(set(attributes))  # remove duplicate values
+    # convert pvlib names in attributes to psm3 convention
+    attributes = [REQUEST_VARIABLE_MAP.get(a, a) for a in attributes]
 
     if (leap_day is None) and (not names.startswith('t')):
         warnings.warn(
@@ -189,13 +203,16 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
         'interval': interval
     }
     # request CSV download from NREL PSM3
-    if any(prefix in names for prefix in ('tmy', 'tgy', 'tdy')):
-        URL = TMY_URL
-    elif interval in (5, 15):
-        URL = PSM5MIN_URL
-    else:
-        URL = PSM_URL
-    response = requests.get(URL, params=params, timeout=timeout)
+    if url is None:
+        # determine the endpoint that suits the user inputs
+        if any(prefix in names for prefix in ('tmy', 'tgy', 'tdy')):
+            url = TMY_URL
+        elif interval in (5, 15):
+            url = PSM5MIN_URL
+        else:
+            url = PSM_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

pvlib/iotools/pvgis.py

@@ -45,7 +45,7 @@ VARIABLE_MAP = {
 
 def get_pvgis_hourly(latitude, longitude, start=None, end=None,
                      raddatabase=None, components=True,
-                     surface_tilt=0, surface_azimuth=0,
+                     surface_tilt=0, surface_azimuth=180,
                      outputformat='json',
                      usehorizon=True, userhorizon=None,
                      pvcalculation=False,
@@ -76,9 +76,15 @@ def get_pvgis_hourly(latitude, longitude, start=None, end=None,
         Otherwise only global irradiance is returned.
     surface_tilt: float, default: 0
         Tilt angle from horizontal plane. Ignored for two-axis tracking.
-    surface_azimuth: float, default: 0
-        Orientation (azimuth angle) of the (fixed) plane. 0=south, 90=west,
-        -90: east. Ignored for tracking systems.
+    surface_azimuth: float, default: 180
+        Orientation (azimuth angle) of the (fixed) plane. Counter-clockwise
+        from north (north=0, south=180). This is offset 180 degrees from
+        the convention used by PVGIS. Ignored for tracking systems.
+
+        .. versionchanged:: 0.10.0
+           The `surface_azimuth` parameter now follows the pvlib convention, which
+           is counterclockwise from north. However, the convention used by the
+           PVGIS website and pvlib<=0.9.5 is offset by 180 degrees.
     usehorizon: bool, default: True
         Include effects of horizon
     userhorizon: list of float, default: None
@@ -144,6 +150,13 @@ def get_pvgis_hourly(latitude, longitude, start=None, end=None,
     time stamp convention, e.g., SARAH and SARAH2 provide instantaneous values,
     whereas values from ERA5 are averages for the hour.
 
+    Warning
+    -------
+    The azimuth orientation specified in the output metadata does not
+    correspond to the pvlib convention, but is offset 180 degrees. This is
+    despite the fact that the input parameter `surface_tilt` has to be
+    specified according to the pvlib convention.
+
     Notes
     -----
     data includes the following fields:
@@ -191,7 +204,7 @@ def get_pvgis_hourly(latitude, longitude, start=None, end=None,
     """  # noqa: E501
     # use requests to format the query string by passing params dictionary
     params = {'lat': latitude, 'lon': longitude, 'outputformat': outputformat,
-              'angle': surface_tilt, 'aspect': surface_azimuth,
+              'angle': surface_tilt, 'aspect': surface_azimuth-180,
               'pvcalculation': int(pvcalculation),
               'pvtechchoice': pvtechchoice, 'mountingplace': mountingplace,
               'trackingtype': trackingtype, 'components': int(components),
@@ -315,6 +328,11 @@ def read_pvgis_hourly(filename, pvgis_format=None, map_variables=True):
     metadata : dict
         metadata
 
+    Warning
+    -------
+    The azimuth orientation specified in the output metadata does not
+    correspond to the pvlib convention, but is offset 180 degrees.
+
     Raises
     ------
     ValueError
@@ -373,8 +391,8 @@ def read_pvgis_hourly(filename, pvgis_format=None, map_variables=True):
 
 
 def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
-                  userhorizon=None, startyear=None, endyear=None, url=URL,
-                  map_variables=None, timeout=30):
+                  userhorizon=None, startyear=None, endyear=None,
+                  map_variables=True, url=URL, timeout=30):
     """
     Get TMY data from PVGIS.
 
@@ -400,11 +418,11 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
         first year to calculate TMY
     endyear : int, default None
         last year to calculate TMY, must be at least 10 years from first year
+    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, default: :const:`pvlib.iotools.pvgis.URL`
         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 const:`VARIABLE_MAP`.
     timeout : int, default 30
         time in seconds to wait for server response before timeout
 
@@ -490,14 +508,6 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
         # the response is HTTP/1.1 400 BAD REQUEST which is handled earlier
         pass
 
-    if map_variables is None:
-        warnings.warn(
-            'PVGIS variable names will be renamed to pvlib conventions by '
-            'default starting in pvlib 0.10.0. Specify map_variables=True '
-            'to enable that behavior now, or specify map_variables=False '
-            'to hide this warning.', pvlibDeprecationWarning
-        )
-        map_variables = False
     if map_variables:
         data = data.rename(columns=VARIABLE_MAP)
 
@@ -555,7 +565,7 @@ def _parse_pvgis_tmy_basic(src):
     return data, None, None, None
 
 
-def read_pvgis_tmy(filename, pvgis_format=None, map_variables=None):
+def read_pvgis_tmy(filename, pvgis_format=None, map_variables=True):
     """
     Read a file downloaded from PVGIS.
 
@@ -571,7 +581,7 @@ def read_pvgis_tmy(filename, pvgis_format=None, map_variables=None):
         ``outputformat='basic'``, please set ``pvgis_format`` to ``'basic'``.
         If ``filename`` is a buffer, then ``pvgis_format`` is required and must
         be in ``['csv', 'epw', 'json', 'basic']``.
-    map_variables: bool
+    map_variables: bool, default True
         When true, renames columns of the Dataframe to pvlib variable names
         where applicable. See variable :const:`VARIABLE_MAP`.
 
@@ -653,15 +663,61 @@ def read_pvgis_tmy(filename, pvgis_format=None, map_variables=None):
             "'csv', or 'basic'").format(outputformat)
         raise ValueError(err_msg)
 
-    if map_variables is None:
-        warnings.warn(
-            'PVGIS variable names will be renamed to pvlib conventions by '
-            'default starting in pvlib 0.10.0. Specify map_variables=True '
-            'to enable that behavior now, or specify map_variables=False '
-            'to hide this warning.', pvlibDeprecationWarning
-        )
-        map_variables = False
     if map_variables:
         data = data.rename(columns=VARIABLE_MAP)
 
     return data, months_selected, inputs, meta
+
+
+def get_pvgis_horizon(latitude, longitude, url=URL, **kwargs):
+    """Get horizon data from PVGIS.
+
+    Parameters
+    ----------
+    latitude : float
+        Latitude in degrees north
+    longitude : float
+        Longitude in degrees east
+    url: str, default: :const:`pvlib.iotools.pvgis.URL`
+        Base URL for PVGIS
+    kwargs:
+        Passed to requests.get
+
+    Returns
+    -------
+    data : pd.Series
+        Pandas Series of the retrived horizon elevation angles. Index is the
+        corresponding horizon azimuth angles.
+    metadata : dict
+        Metadata returned by PVGIS.
+
+    Notes
+    -----
+    The horizon azimuths are specified clockwise from north, e.g., south=180.
+    This is the standard pvlib convention, although the PVGIS website specifies
+    south=0.
+
+    References
+    ----------
+    .. [1] `PVGIS horizon profile tool
+       <https://ec.europa.eu/jrc/en/PVGIS/tools/horizon>`_
+    """
+    params = {'lat': latitude, 'lon': longitude, 'outputformat': 'json'}
+    res = requests.get(url + 'printhorizon', params=params, **kwargs)
+    if not res.ok:
+        try:
+            err_msg = res.json()
+        except Exception:
+            res.raise_for_status()
+        else:
+            raise requests.HTTPError(err_msg['message'])
+    json_output = res.json()
+    metadata = json_output['meta']
+    data = pd.DataFrame(json_output['outputs']['horizon_profile'])
+    data.columns = ['horizon_azimuth', 'horizon_elevation']
+    # Convert azimuth to pvlib convention (north=0, south=180)
+    data['horizon_azimuth'] += 180
+    data.set_index('horizon_azimuth', inplace=True)
+    data = data['horizon_elevation']  # convert to pd.Series
+    data = data[data.index < 360]  # remove duplicate north point (0 and 360)
+    return data, metadata

pvlib/iotools/sodapro.py

@@ -9,6 +9,8 @@ import io
 import warnings
 
 
+URL = 'api.soda-solardata.com'
+
 CAMS_INTEGRATED_COLUMNS = [
     'TOA', 'Clear sky GHI', 'Clear sky BHI', 'Clear sky DHI', 'Clear sky BNI',
     'GHI', 'BHI', 'DHI', 'BNI',
@@ -44,7 +46,7 @@ SUMMATION_PERIOD_TO_TIME_STEP = {'0 year 0 month 0 day 0 h 1 min 0 s': '1min',
 def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
              altitude=None, time_step='1h', time_ref='UT', verbose=False,
              integrated=False, label=None, map_variables=True,
-             server='www.soda-is.com', timeout=30):
+             server=URL, timeout=30):
     """
     Retrieve time-series of radiation and/or clear-sky global, beam, and
     diffuse radiation from CAMS (see [1]_). Data is retrieved from SoDa [2]_.
@@ -91,8 +93,8 @@ def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
     map_variables: bool, default: True
         When true, renames columns of the DataFrame to pvlib variable names
         where applicable. See variable :const:`VARIABLE_MAP`.
-    server: str, default: 'www.soda-is.com'
-        Main server (www.soda-is.com) or backup mirror server (pro.soda-is.com)
+    server: str, default: :const:`pvlib.iotools.sodapro.URL`
+        Base url of the SoDa Pro CAMS Radiation API.
     timeout : int, default: 30
         Time in seconds to wait for server response before timeout
 
@@ -344,13 +346,13 @@ def read_cams(filename, integrated=False, label=None, map_variables=True):
         all time steps except for '1M' which has a default of 'right'.
     map_variables: bool, default: True
         When true, renames columns of the Dataframe to pvlib variable names
-        where applicable. See variable VARIABLE_MAP.
+        where applicable. See variable :const:`VARIABLE_MAP`.
 
     Returns
     -------
     data: pandas.DataFrame
-        Timeseries data from CAMS Radiation or McClear
-        :func:`pvlib.iotools.get_cams` for fields
+        Timeseries data from CAMS Radiation or McClear.
+        See :func:`pvlib.iotools.get_cams` for fields.
     metadata: dict
         Metadata available in the file.
 

pvlib/iotools/srml.py

@@ -3,7 +3,10 @@ Radiation Monitoring Laboratory (SRML) data.
 """
 import numpy as np
 import pandas as pd
+import urllib
+import warnings
 
+from pvlib._deprecation import deprecated
 
 # VARIABLE_MAP is a dictionary mapping SRML data element numbers to their
 # pvlib names. For most variables, only the first three digits are used,
@@ -15,7 +18,7 @@ VARIABLE_MAP = {
     '100': 'ghi',
     '201': 'dni',
     '300': 'dhi',
-    '920': 'wind_dir',
+    '920': 'wind_direction',
     '921': 'wind_speed',
     '930': 'temp_air',
     '931': 'temp_dew',
@@ -24,22 +27,24 @@ VARIABLE_MAP = {
 }
 
 
-def read_srml(filename):
+def read_srml(filename, map_variables=True):
     """
-    Read University of Oregon SRML 1min .tsv file into pandas dataframe.  The
-    SRML is described in [1]_.
+    Read University of Oregon SRML 1min .tsv file into pandas dataframe.
+
+    The SRML is described in [1]_.
 
     Parameters
     ----------
     filename: str
         filepath or url to read for the tsv file.
+    map_variables: bool, default: True
+        When true, renames columns of the DataFrame to pvlib variable names
+        where applicable. See variable :const:`VARIABLE_MAP`.
 
     Returns
     -------
     data: Dataframe
-        A dataframe with datetime index and all of the variables listed
-        in the `VARIABLE_MAP` dict inside of the map_columns function,
-        along with their associated quality control flags.
+        A dataframe with datetime index
 
     Notes
     -----
@@ -50,21 +55,22 @@ def read_srml(filename):
     the time of the row until the time of the next row. This is consistent
     with pandas' default labeling behavior.
 
-    See SRML's `Archival Files`_ page for more information.
-
-    .. _Archival Files: http://solardat.uoregon.edu/ArchivalFiles.html
+    See [2]_ for more information concerning the file format.
 
     References
     ----------
     .. [1] University of Oregon Solar Radiation Monitoring Laboratory
        `http://solardat.uoregon.edu/ <http://solardat.uoregon.edu/>`_
+    .. [2] `Archival (short interval) data files
+       <http://solardat.uoregon.edu/ArchivalFiles.html>`_
     """
     tsv_data = pd.read_csv(filename, delimiter='\t')
-    data = format_index(tsv_data)
+    data = _format_index(tsv_data)
     # Drop day of year and time columns
     data = data[data.columns[2:]]
 
-    data = data.rename(columns=map_columns)
+    if map_variables:
+        data = data.rename(columns=_map_columns)
 
     # Quality flag columns are all labeled 0 in the original data. They
     # appear immediately after their associated variable and are suffixed
@@ -90,7 +96,7 @@ def read_srml(filename):
     return data
 
 
-def map_columns(col):
+def _map_columns(col):
     """Map data element numbers to pvlib names.
 
     Parameters
@@ -118,7 +124,7 @@ def map_columns(col):
         return col
 
 
-def format_index(df):
+def _format_index(df):
     """Create a datetime index from day of year, and time columns.
 
     Parameters
@@ -166,9 +172,12 @@ def format_index(df):
     return df
 
 
-def read_srml_month_from_solardat(station, year, month, filetype='PO'):
-    """Request a month of SRML data from solardat and read it into
-    a Dataframe.  The SRML is described in [1]_.
+@deprecated('0.10.0', alternative='pvlib.iotools.get_srml', removal='0.11.0')
+def read_srml_month_from_solardat(station, year, month, filetype='PO',
+                                  map_variables=True):
+    """Request a month of SRML data and read it into a Dataframe.
+
+    The SRML is described in [1]_.
 
     Parameters
     ----------
@@ -180,6 +189,9 @@ def read_srml_month_from_solardat(station, year, month, filetype='PO'):
         Month to request data for.
     filetype: string
         SRML file type to gather. See notes for explanation.
+    map_variables: bool, default: True
+        When true, renames columns of the DataFrame to pvlib variable names
+        where applicable. See variable :const:`VARIABLE_MAP`.
 
     Returns
     -------
@@ -214,5 +226,96 @@ def read_srml_month_from_solardat(station, year, month, filetype='PO'):
         year=year % 100,
         month=month)
     url = "http://solardat.uoregon.edu/download/Archive/"
-    data = read_srml(url + file_name)
+    data = read_srml(url + file_name, map_variables=map_variables)
     return data
+
+
+def get_srml(station, start, end, filetype='PO', map_variables=True,
+             url="http://solardat.uoregon.edu/download/Archive/"):
+    """Request data from UoO SRML and read it into a Dataframe.
+
+    The University of Oregon Solar Radiation Monitoring Laboratory (SRML) is
+    described in [1]_. A list of stations can be found in [2]_.
+
+    Data is returned for the entire months between and including start and end.
+
+    Parameters
+    ----------
+    station : str
+        Two letter station abbreviation.
+    start : datetime like
+        First day of the requested period
+    end : datetime like
+        Last day of the requested period
+    filetype : string, default: 'PO'
+        SRML file type to gather. See notes for explanation.
+    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, default: 'http://solardat.uoregon.edu/download/Archive/'
+        API endpoint URL
+
+    Returns
+    -------
+    data : pd.DataFrame
+        Dataframe with data from SRML.
+    meta : dict
+        Metadata.
+
+    Notes
+    -----
+    File types designate the time interval of a file and if it contains
+    raw or processed data. For instance, `RO` designates raw, one minute
+    data and `PO` designates processed one minute data. The availability
+    of file types varies between sites. Below is a table of file types
+    and their time intervals. See [1] for site information.
+
+    ============= ============ ==================
+    time interval raw filetype processed filetype
+    ============= ============ ==================
+    1 minute      RO           PO
+    5 minute      RF           PF
+    15 minute     RQ           PQ
+    hourly        RH           PH
+    ============= ============ ==================
+
+    Warning
+    -------
+    SRML data has nighttime data prefilled with 0s through the end of the
+    current month (i.e., values are provided for data in the future).
+
+    References
+    ----------
+    .. [1] University of Oregon Solar Radiation Measurement Laboratory
+       `http://solardat.uoregon.edu/ <http://solardat.uoregon.edu/>`_
+    .. [2] Station ID codes - Solar Radiation Measurement Laboratory
+       `http://solardat.uoregon.edu/StationIDCodes.html
+       <http://solardat.uoregon.edu/StationIDCodes.html>`_
+    """
+    # Use pd.to_datetime so that strings (e.g. '2021-01-01') are accepted
+    start = pd.to_datetime(start)
+    end = pd.to_datetime(end)
+
+    # Generate list of months
+    months = pd.date_range(
+        start, end.replace(day=1) + pd.DateOffset(months=1), freq='1M')
+    months_str = months.strftime('%y%m')
+
+    # Generate list of filenames
+    filenames = [f"{station}{filetype}{m}.txt" for m in months_str]
+
+    dfs = []  # Initialize list of monthly dataframes
+    for f in filenames:
+        try:
+            dfi = read_srml(url + f, map_variables=map_variables)
+            dfs.append(dfi)
+        except urllib.error.HTTPError:
+            warnings.warn(f"The following file was not found: {f}")
+
+    data = pd.concat(dfs, axis='rows')
+
+    meta = {'filetype': filetype,
+            'station': station,
+            'filenames': filenames}
+
+    return data, meta

pvlib/iotools/surfrad.py

@@ -150,7 +150,7 @@ def read_surfrad(filename, map_variables=True):
                        header=None, names=SURFRAD_COLUMNS)
     file_buffer.close()
 
-    data = format_index(data)
+    data = _format_index(data)
     missing = data == -9999.9
     data = data.where(~missing, np.NaN)
 
@@ -159,7 +159,7 @@ def read_surfrad(filename, map_variables=True):
     return data, metadata
 
 
-def format_index(data):
+def _format_index(data):
     """Create UTC localized DatetimeIndex for the dataframe.
 
     Parameters