Add direct irradiance to VARIABLE_MAP in get_era5 iotools function (#2819)

* Add dni to VARIABLE_MAP in get_era5 iotools function

* Add dni to example variable in doc

* Convert dni from J to W

* Change dni to bhi

* Update v0.16.0.rst

* Update test_era5.py

* Fix linter

Author: AdamRJensen

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

@@ -25,7 +25,9 @@ Bug fixes
 
 Enhancements
 ~~~~~~~~~~~~
-
+* Map beam horizontal irradiance to ``bhi`` when
+  :py:func:`~pvlib.iotools.get_era5` is called with ``map_variables=True``.
+  (:pull:`2819`)
 
 Documentation
 ~~~~~~~~~~~~~

pvlib/iotools/era5.py

@@ -11,6 +11,7 @@
     't2m': 'temp_air',
     'sp': 'pressure',
     'ssrd': 'ghi',
+    'fdir': 'bhi',
     'tp': 'precipitation',
     'strd': 'longwave_down',
 
@@ -19,6 +20,7 @@
     '2m_temperature': 'temp_air',
     'surface_pressure': 'pressure',
     'surface_solar_radiation_downwards': 'ghi',
+    'total_sky_direct_solar_radiation_at_surface': 'bhi',
     'total_precipitation': 'precipitation',
     'surface_thermal_radiation_downwards': 'longwave_down',
 }
@@ -52,6 +54,7 @@ def _m_to_cm(m):
     'skt': _k_to_c,
     'sp': _same,
     'ssrd': _j_to_w,
+    'fdir': _j_to_w,
     'strd': _j_to_w,
     'tp': _m_to_cm,
 }
@@ -80,7 +83,7 @@ def get_era5(latitude, longitude, start, end, variables, api_key,
         Last day of the requested period.  Assumed to be UTC if not localized.
     variables : list of str
         List of variable names to retrieve, for example
-        ``['ghi', 'temp_air']``. Both pvlib and ERA5 names can be used.
+        ``['ghi', 'bhi', 'temp_air']``. Both pvlib and ERA5 names can be used.
         See [1]_ for additional options.
     api_key : str
         ECMWF CDS API key.

tests/iotools/test_era5.py

@@ -17,7 +17,9 @@ def params():
     return {
         'latitude': 40.01, 'longitude': -80.01,
         'start': '2020-06-01', 'end': '2020-06-01',
-        'variables': ['ghi', 'temp_air'],
+        # Test a mix of pvlib and ERA5 variable names
+        'variables': [
+            'ghi', 'temp_air', 'total_sky_direct_solar_radiation_at_surface'],
         'api_key': api_key,
     }
 
@@ -33,7 +35,11 @@ def expected():
     ghi = [153., 18.4, 0., 0., 0., 0., 0., 0., 0., 0., 0., 60., 229.5,
            427.8, 620.1, 785.5, 910.1, 984.2, 1005.9, 962.4, 844.1, 685.2,
            526.9, 331.4]
-    df = pd.DataFrame({'temp_air': temp_air, 'ghi': ghi}, index=index)
+    bhi = [102.6, 8.3, 0., 0., 0., 0., 0., 0., 0., 0., 0., 34.9, 167.8, 345.6,
+           524.3, 679.5, 796.1, 866.1, 893.4, 841.7, 724., 539.6, 415.1,
+           239.6]
+    df = pd.DataFrame({'temp_air': temp_air, 'ghi': ghi, 'bhi': bhi},
+                      index=index)
     return df
 
 
@@ -66,9 +72,11 @@ def test_get_era5_timezone(params, expected):
 @pytest.mark.flaky(reruns=RERUNS, reruns_delay=RERUNS_DELAY)
 def test_get_era5_map_variables(params, expected):
     df, meta = pvlib.iotools.get_era5(**params, map_variables=False)
-    expected = expected.rename(columns={'temp_air': 't2m', 'ghi': 'ssrd'})
+    expected = expected.rename(columns={
+        'temp_air': 't2m', 'ghi': 'ssrd', "bhi": "fdir"})
     df['t2m'] -= 273.15  # apply unit conversions manually
     df['ssrd'] /= 3600
+    df['fdir'] /= 3600
     pd.testing.assert_frame_equal(df, expected, check_freq=False, atol=0.1)
     assert meta['longitude'] == -80.0
     assert meta['latitude'] == 40.0