Fix inconsistencies

pvlib/iotools/bsrn.py

@@ -60,7 +60,7 @@ def _empty_dataframe_from_logical_records(logical_records):
     return pd.DataFrame(columns=columns)
 
 
-def get_bsrn(start, end, station, username, password,
+def get_bsrn(station, start, end, username, password,
              logical_records=('0100',), local_path=None):
     """
     Retrieve ground measured irradiance data from the BSRN FTP server.
@@ -73,12 +73,12 @@ def get_bsrn(start, end, station, username, password,
 
     Parameters
     ----------
+    station: str
+        3-letter BSRN station abbreviation
     start: datetime-like
         First day of the requested period
     end: datetime-like
         Last day of the requested period
-    station: str
-        3-letter BSRN station abbreviation
     username: str
         username for accessing the BSRN FTP server
     password: str

pvlib/iotools/ecmwf_macc.py

@@ -34,12 +34,12 @@ def ECMWFDataServer(*a, **kw):
 }
 
 
-def _ecmwf(server, startdate, stopdate, params, targetname):
+def _ecmwf(server, startdate, enddate, params, targetname):
     # see http://apps.ecmwf.int/datasets/data/macc-reanalysis/levtype=sfc/
     server.retrieve({
         "class": "mc",
         "dataset": "macc",
-        "date": "%s/to/%s" % (startdate, stopdate),
+        "date": "%s/to/%s" % (startdate, enddate),
         "expver": "rean",
         "grid": "0.75/0.75",
         "levtype": "sfc",
@@ -53,7 +53,7 @@ def _ecmwf(server, startdate, stopdate, params, targetname):
     })
 
 
-def get_ecmwf_macc(filename, params, startdate, stopdate, lookup_params=True,
+def get_ecmwf_macc(filename, params, start, end, lookup_params=True,
                    server=None, target=_ecmwf):
     """
     Download data from ECMWF MACC Reanalysis API.
@@ -64,9 +64,9 @@ def get_ecmwf_macc(filename, params, startdate, stopdate, lookup_params=True,
         full path of file where to save data, ``.nc`` appended if not given
     params : str or sequence of str
         keynames of parameter[s] to download
-    startdate : datetime.datetime or datetime.date
+    start : datetime.datetime or datetime.date
         UTC date
-    stopdate : datetime.datetime or datetime.date
+    end : datetime.datetime or datetime.date
         UTC date
     lookup_params : bool, default True
         optional flag, if ``False``, then codes are already formatted
@@ -137,7 +137,7 @@ def get_ecmwf_macc(filename, params, startdate, stopdate, lookup_params=True,
     :func:`pvlib.iotools.get_ecmwf_macc`. ::
 
 
-        target(server, startdate, stopdate, params, filename) -> None
+        target(server, startdate, enddate, params, filename) -> None
 
     Examples
     --------
@@ -161,12 +161,12 @@ def get_ecmwf_macc(filename, params, startdate, stopdate, lookup_params=True,
             params = '/'.join(PARAMS.get(p) for p in params)
         except TypeError:
             params = PARAMS.get(params)
-    startdate = startdate.strftime('%Y-%m-%d')
-    stopdate = stopdate.strftime('%Y-%m-%d')
+    startdate = start.strftime('%Y-%m-%d')
+    enddate = end.strftime('%Y-%m-%d')
     if not server:
         server = ECMWFDataServer()
     t = threading.Thread(target=target, daemon=True,
-                         args=(server, startdate, stopdate, params, filename))
+                         args=(server, startdate, enddate, params, filename))
     t.start()
     return t
 
@@ -191,8 +191,8 @@ def __init__(self, filename):
         # time resolution in hours
         self.time_size = self.data.dimensions['time'].size
         self.start_time = self.data['time'][0]
-        self.stop_time = self.data['time'][-1]
-        self.time_range = self.stop_time - self.start_time
+        self.end_time = self.data['time'][-1]
+        self.time_range = self.end_time - self.start_time
         self.delta_time = self.time_range / (self.time_size - 1)
 
     def get_nearest_indices(self, latitude, longitude):
@@ -281,7 +281,7 @@ def read_ecmwf_macc(filename, latitude, longitude, utc_time_range=None):
     longitude : float
         longitude in degrees
     utc_time_range : sequence of datetime.datetime
-        pair of start and stop naive or UTC date-times
+        pair of start and end naive or UTC date-times
 
     Returns
     -------
@@ -295,9 +295,9 @@ def read_ecmwf_macc(filename, latitude, longitude, utc_time_range=None):
         if utc_time_range:
             start_idx = netCDF4.date2index(
                 utc_time_range[0], nctime, select='before')
-            stop_idx = netCDF4.date2index(
+            end_idx = netCDF4.date2index(
                 utc_time_range[-1], nctime, select='after')
-            time_slice = slice(start_idx, stop_idx + 1)
+            time_slice = slice(start_idx, end_idx + 1)
         else:
             time_slice = slice(0, ecmwf_macc.time_size)
         times = netCDF4.num2date(nctime[time_slice], nctime.units)

pvlib/iotools/psm3.py

@@ -61,11 +61,11 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
 
     Returns
     -------
-    headers : dict
-        metadata from NREL PSM3 about the record, see
-        :func:`pvlib.iotools.parse_psm3` for fields
     data : pandas.DataFrame
         timeseries data from NREL PSM3
+    metadata : dict
+        metadata from NREL PSM3 about the record, see
+        :func:`pvlib.iotools.parse_psm3` for fields
 
     Raises
     ------
@@ -117,6 +117,11 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
        <https://developer.nrel.gov/docs/solar/nsrdb/psm3-tmy-download/>`_
     .. [4] `Physical Solar Model (PSM) v3 - Five Minute Temporal Resolution
        <https://developer.nrel.gov/docs/solar/nsrdb/psm3-5min-download/>`_
+
+    .. versionchanged:: 0.9.0
+       The function now returns a tuple where the first element is a dataframe
+       and the second element is a dictionary containing metadata. Previous
+       versions of this function had the return values switched.
     """
     # The well know text (WKT) representation of geometry notation is strict.
     # A POINT object is a string with longitude first, then the latitude, with
@@ -177,15 +182,18 @@ def parse_psm3(fbuf):
 
     Returns
     -------
-    headers : dict
-        metadata from NREL PSM3 about the record, see notes for fields
     data : pandas.DataFrame
         timeseries data from NREL PSM3
+    metadata : dict
+        metadata from NREL PSM3 about the record, see notes for fields
 
     Notes
     -----
-    The return is a tuple with two items. The first item is a header with
-    metadata from NREL PSM3 about the record containing the following fields:
+    The return is a tuple with two items. The first item is a dataframe with
+    the PSM3 timeseries data.
+
+    The second item is a dictionary with metadata from NREL PSM3 about the
+    record containing the following fields:
 
     * Source
     * Location ID
@@ -234,13 +242,11 @@ def parse_psm3(fbuf):
     * Surface Albedo Units
     * Version
 
-    The second item is a dataframe with the PSM3 timeseries data.
-
     Examples
     --------
     >>> # Read a local PSM3 file:
     >>> with open(filename, 'r') as f:  # doctest: +SKIP
-    ...     metadata, df = iotools.parse_psm3(f)  # doctest: +SKIP
+    ...     df, metadata = iotools.parse_psm3(f)  # doctest: +SKIP
 
     See Also
     --------
@@ -252,19 +258,24 @@ def parse_psm3(fbuf):
        <https://nsrdb.nrel.gov/>`_
     .. [2] `Standard Time Series Data File Format
        <https://rredc.nrel.gov/solar/old_data/nsrdb/2005-2012/wfcsv.pdf>`_
+
+    .. versionchanged:: 0.9.0
+       The function now returns a tuple where the first element is a dataframe
+       and the second element is a dictionary containing metadata. Previous
+       versions of this function had the return values switched.
     """
     # The first 2 lines of the response are headers with metadata
-    header_fields = fbuf.readline().split(',')
-    header_fields[-1] = header_fields[-1].strip()  # strip trailing newline
-    header_values = fbuf.readline().split(',')
-    header_values[-1] = header_values[-1].strip()  # strip trailing newline
-    header = dict(zip(header_fields, header_values))
-    # the response is all strings, so set some header types to numbers
-    header['Local Time Zone'] = int(header['Local Time Zone'])
-    header['Time Zone'] = int(header['Time Zone'])
-    header['Latitude'] = float(header['Latitude'])
-    header['Longitude'] = float(header['Longitude'])
-    header['Elevation'] = int(header['Elevation'])
+    metadata_fields = fbuf.readline().split(',')
+    metadata_fields[-1] = metadata_fields[-1].strip()  # strip trailing newline
+    metadata_values = fbuf.readline().split(',')
+    metadata_values[-1] = metadata_values[-1].strip()  # strip trailing newline
+    metadata = dict(zip(metadata_fields, metadata_values))
+    # the response is all strings, so set some metadata types to numbers
+    metadata['Local Time Zone'] = int(metadata['Local Time Zone'])
+    metadata['Time Zone'] = int(metadata['Time Zone'])
+    metadata['Latitude'] = float(metadata['Latitude'])
+    metadata['Longitude'] = float(metadata['Longitude'])
+    metadata['Elevation'] = int(metadata['Elevation'])
     # get the column names so we can set the dtypes
     columns = fbuf.readline().split(',')
     columns[-1] = columns[-1].strip()  # strip trailing newline
@@ -282,10 +293,10 @@ def parse_psm3(fbuf):
     dtidx = pd.to_datetime(
         data[['Year', 'Month', 'Day', 'Hour', 'Minute']])
     # in USA all timezones are integers
-    tz = 'Etc/GMT%+d' % -header['Time Zone']
+    tz = 'Etc/GMT%+d' % -metadata['Time Zone']
     data.index = pd.DatetimeIndex(dtidx).tz_localize(tz)
 
-    return header, data
+    return data, metadata
 
 
 def read_psm3(filename):
@@ -300,11 +311,11 @@ def read_psm3(filename):
 
     Returns
     -------
-    headers : dict
-        metadata from NREL PSM3 about the record, see
-        :func:`pvlib.iotools.parse_psm3` for fields
     data : pandas.DataFrame
         timeseries data from NREL PSM3
+    metadata : dict
+        metadata from NREL PSM3 about the record, see
+        :func:`pvlib.iotools.parse_psm3` for fields
 
     See Also
     --------
@@ -316,6 +327,11 @@ def read_psm3(filename):
        <https://nsrdb.nrel.gov/>`_
     .. [2] `Standard Time Series Data File Format
        <https://rredc.nrel.gov/solar/old_data/nsrdb/2005-2012/wfcsv.pdf>`_
+
+    .. versionchanged:: 0.9.0
+       The function now returns a tuple where the first element is a dataframe
+       and the second element is a dictionary containing metadata. Previous
+       versions of this function had the return values switched.
     """
     with open(str(filename), 'r') as fbuf:
         content = parse_psm3(fbuf)