Add map_variables parameter to read_tmy3 function

docs/sphinx/source/whatsnew/v0.9.5.rst

@@ -16,7 +16,9 @@ Deprecations
 
 Enhancements
 ~~~~~~~~~~~~
-
+* Added variable mapping of columns when reading TMY3 dataframe using the 
+  ``read_tmy3`` function.
+  (:issue:`1517`, :pull:`1623`)
 
 Bug fixes
 ~~~~~~~~~

pvlib/data/variables_style_rules.csv

@@ -7,6 +7,7 @@ dni_extra;direct normal irradiance at top of atmosphere (extraterrestrial)
 dhi;diffuse horizontal irradiance
 bhi;beam/direct horizontal irradiance
 ghi;global horizontal irradiance
+ghi_extra;Extraterrestrial horizontal radiation recv’d during 60 minutes prior to timestamp
 gri;ground-reflected irradiance
 aoi;angle of incidence between :math:`90\deg` and :math:`90\deg`
 aoi_projection;cos(aoi)
@@ -49,3 +50,5 @@ pac, ac; ac powe.
 eta_inv; inverter efficiency
 eta_inv_ref; reference inverter efficiency
 eta_inv_nom; nominal inverter efficiency
+albedo;The ratio of reflected solar irradiance to global horizontal irradiance, unitless
+precipitable_water;Total precipitable water contained in a column of unit cross section from earth to top of atmosphere

pvlib/iotools/tmy.py

@@ -3,9 +3,28 @@
 import datetime
 import re
 import pandas as pd
-
-
-def read_tmy3(filename, coerce_year=None, recolumn=True):
+import warnings
+from pvlib._deprecation import pvlibDeprecationWarning
+
+# Dictionary mapping TMY3 names to pvlib names
+VARIABLE_MAP = {
+    'GHI (W/m^2)': 'ghi',
+    'ETR (W/m^2)': 'ghi_extra',
+    'DNI (W/m^2)': 'dni',
+    'ETRN (W/m^2)': 'dni_extra',
+    'DHI (W/m^2)': 'dhi',
+    'Pressure (mbar)': 'pressure',
+    'Wdir (degrees)': 'wind_direction',
+    'Wspd (m/s)': 'wind_speed',
+    'Dry-bulb (C)': 'temp_air',
+    'Dew-point (C)': 'temp_dew',
+    'RHum (%)': 'relative_humidity',
+    'Alb (unitless)': 'albedo',
+    'Pwat (cm)': 'precipitable_water'
+}
+
+
+def read_tmy3(filename, coerce_year=None, map_variables=None, recolumn=True):
     """Read a TMY3 file into a pandas dataframe.
 
     Note that values contained in the metadata dictionary are unchanged
@@ -24,6 +43,9 @@ def read_tmy3(filename, coerce_year=None, recolumn=True):
         If supplied, the year of the index will be set to `coerce_year`, except
         for the last index value which will be set to the *next* year so that
         the index increases monotonically.
+    map_variables : bool, default None
+        When True, renames columns of the DataFrame to pvlib variable names
+        where applicable. See variable :const:`VARIABLE_MAP`.
     recolumn : bool, default True
         If ``True``, apply standard names to TMY3 columns. Typically this
         results in stripping the units from the column name.
@@ -152,8 +174,10 @@ def read_tmy3(filename, coerce_year=None, recolumn=True):
     ----------
     .. [1] Wilcox, S and Marion, W. "Users Manual for TMY3 Data Sets".
        NREL/TP-581-43156, Revised May 2008.
+       :doi:`10.2172/928611`
     .. [2] Wilcox, S. (2007). National Solar Radiation Database 1991 2005
        Update: Users Manual. 472 pp.; NREL Report No. TP-581-41364.
+       :doi:`10.2172/901864`
     .. [3] `SolarAnywhere file formats
        <https://www.solaranywhere.com/support/historical-data/file-formats/>`_
     """  # noqa: E501
@@ -198,9 +222,17 @@ def read_tmy3(filename, coerce_year=None, recolumn=True):
     # NOTE: as of pvlib-0.6.3, min req is pandas-0.18.1, so pd.to_timedelta
     # unit must be in (D,h,m,s,ms,us,ns), but pandas>=0.24 allows unit='hour'
     data.index = data_ymd + pd.to_timedelta(shifted_hour, unit='h')
-
-    if recolumn:
-        data = _recolumn(data)  # rename to standard column names
+    if map_variables is None:
+        if recolumn:
+            data = _recolumn(data)  # rename to standard column names
+        warnings.warn(
+            'TMY3 variable names will be renamed to pvlib conventions by '
+            'default starting in pvlib 0.11.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)
 
     data = data.tz_localize(int(meta['TZ'] * 3600))
 

pvlib/tests/iotools/test_tmy.py

@@ -1,6 +1,7 @@
 import numpy as np
 import pandas as pd
 from pvlib.iotools import tmy
+from pvlib._deprecation import pvlibDeprecationWarning
 from ..conftest import DATA_DIR
 import pytest
 
@@ -16,7 +17,7 @@
 
 
 def test_read_tmy3():
-    tmy.read_tmy3(TMY3_TESTFILE)
+    tmy.read_tmy3(TMY3_TESTFILE, map_variables=False)
 
 
 def test_read_tmy3_recolumn():
@@ -25,20 +26,42 @@ def test_read_tmy3_recolumn():
 
 
 def test_read_tmy3_norecolumn():
-    data, _ = tmy.read_tmy3(TMY3_TESTFILE, recolumn=False)
+    data, _ = tmy.read_tmy3(TMY3_TESTFILE, recolumn=False, map_variables=False)
     assert 'GHI source' in data.columns
 
 
+def test_read_tmy3_map_variables():
+    data, meta = tmy.read_tmy3(TMY3_TESTFILE, map_variables=True)
+    assert 'ghi' in data.columns
+    assert 'dni' in data.columns
+    assert 'dhi' in data.columns
+    assert 'pressure' in data.columns
+    assert 'wind_direction' in data.columns
+    assert 'wind_speed' in data.columns
+    assert 'temp_air' in data.columns
+    assert 'temp_dew' in data.columns
+    assert 'relative_humidity' in data.columns
+    assert 'albedo' in data.columns
+    assert 'ghi_extra' in data.columns
+    assert 'dni_extra' in data.columns
+    assert 'precipitable_water' in data.columns
+
+
+def test_read_tmy3_map_variables_deprecating_warning():
+    with pytest.warns(pvlibDeprecationWarning, match='names will be renamed'):
+        data, meta = tmy.read_tmy3(TMY3_TESTFILE)
+
+
 def test_read_tmy3_coerce_year():
     coerce_year = 1987
-    data, _ = tmy.read_tmy3(TMY3_TESTFILE, coerce_year=coerce_year)
+    data, _ = tmy.read_tmy3(TMY3_TESTFILE, coerce_year=coerce_year, map_variables=False)
     assert (data.index[:-1].year == 1987).all()
     assert data.index[-1].year == 1988
 
 
 def test_read_tmy3_no_coerce_year():
     coerce_year = None
-    data, _ = tmy.read_tmy3(TMY3_TESTFILE, coerce_year=coerce_year)
+    data, _ = tmy.read_tmy3(TMY3_TESTFILE, coerce_year=coerce_year, map_variables=False)
     assert 1997 and 1999 in data.index.year
     assert data.index[-2] == pd.Timestamp('1998-12-31 23:00:00-09:00')
     assert data.index[-1] == pd.Timestamp('1999-01-01 00:00:00-09:00')
@@ -50,7 +73,7 @@ def test_read_tmy2():
 
 def test_gh865_read_tmy3_feb_leapyear_hr24():
     """correctly parse the 24th hour if the tmy3 file has a leap year in feb"""
-    data, meta = read_tmy3(TMY3_FEB_LEAPYEAR)
+    data, meta = read_tmy3(TMY3_FEB_LEAPYEAR, map_variables=False)
     # just to be safe, make sure this _IS_ the Greensboro file
     greensboro = {
         'USAF': 723170,
@@ -87,7 +110,7 @@ def test_solaranywhere_tmy3(solaranywhere_index):
     # The SolarAnywhere TMY3 format specifies midnight as 00:00 whereas the
     # NREL TMY3 format utilizes 24:00. The SolarAnywhere file is therefore
     # included to test files with  00:00 timestamps are parsed correctly
-    data, meta = tmy.read_tmy3(TMY3_SOLARANYWHERE)
+    data, meta = tmy.read_tmy3(TMY3_SOLARANYWHERE,map_variables=False)
     pd.testing.assert_index_equal(data.index, solaranywhere_index)
     assert meta['USAF'] == 0
     assert meta['Name'] == 'Burlington  United States'