Making the irradiation and weather DataFrame of the ModelChain more flexible

pvlib/modelchain.py

@@ -7,10 +7,11 @@
 """
 
 from functools import partial
-
+import logging
+import warnings
 import pandas as pd
 
-from pvlib import solarposition, pvsystem, clearsky, atmosphere
+from pvlib import (solarposition, pvsystem, clearsky, atmosphere, tools)
 from pvlib.tracking import SingleAxisTracker
 import pvlib.irradiance  # avoid name conflict with full import
 
@@ -316,6 +317,10 @@ def __init__(self, system, location,
         self.losses_model = losses_model
         self.orientation_strategy = orientation_strategy
 
+        self.weather = pd.DataFrame()
+        self.times = None
+        self.solar_position = None
+
     def __repr__(self):
         return ('ModelChain for: ' + str(self.system) +
                 ' orientation_startegy: ' + str(self.orientation_strategy) +
@@ -602,32 +607,101 @@ def effective_irradiance_model(self):
             fd*self.total_irrad['poa_diffuse'])
         return self
 
-    def prepare_inputs(self, times, irradiance=None, weather=None):
+    def complete_irradiance(self, times, weather):
+        """
+        Determine the missing irradiation columns. Only two of the following
+        data columns (dni, ghi, dhi) are needed to calculate the missing data.
+
+        This function is not save at the moment. Results can be too high or
+        negative. Please contribute and help to improve this function on
+        https://github.com/pvlib/pvlib-python
+
+        Parameters
+        ----------
+        times : datetime index
+            Date and time index of the irradiation data
+        weather : pandas.DataFrame
+            Table with at least two columns containing one of the following data
+            sets: dni, dhi, ghi
+
+        Returns
+        -------
+        pandas.DataFrame
+            Containing the missing column of the data sets passed with the
+            weather DataFrame.
+
+        """
+        self.weather = weather
+        self.times = times
+        self.solar_position = self.location.get_solarposition(self.times)
+        icolumns = set(self.weather.columns)
+        wrn_txt = "This function is not save at the moment.\n"
+        wrn_txt += "Results can be too high or negative.\n"
+        wrn_txt += "Help to improve this function on github."
+        wrn_txt += "https://github.com/pvlib/pvlib-python"
+        warnings.warn(wrn_txt, UserWarning)
+        if {'ghi', 'dhi'} <= icolumns and 'dni' not in icolumns:
+            logging.debug('Estimate dni from ghi and dhi')
+            self.weather.loc[:, 'dni'] = (
+                (self.weather.loc[:, 'ghi'] - self.weather.loc[:, 'dhi']) /
+                tools.cosd(self.solar_position.loc[:, 'zenith']))
+        elif {'dni', 'dhi'} <= icolumns and 'ghi' not in icolumns:
+            logging.debug('Estimate ghi from dni and dhi')
+            self.weather.loc[:, 'ghi'] = (
+                self.weather.dni * tools.cosd(self.solar_position.zenith) +
+                self.weather.dhi)
+        elif {'dni', 'ghi'} <= icolumns and 'dhi' not in icolumns:
+            logging.debug('Estimate dhi from dni and ghi')
+            self.weather.loc[:, 'dhi'] = (
+                self.weather.ghi - self.weather.dni *
+                tools.cosd(self.solar_position.zenith))
+
+    def prepare_inputs(self, times=None, irradiance=None, weather=None):
         """
         Prepare the solar position, irradiance, and weather inputs to
         the model.
 
         Parameters
         ----------
         times : DatetimeIndex
-            Times at which to evaluate the model.
-        irradiance : None or DataFrame
-            If None, calculates clear sky data.
-            Columns must be 'dni', 'ghi', 'dhi'.
+            Times at which to evaluate the model. Can be None if attribute
+            `times` is already set.
         weather : None or DataFrame
-            If None, assumes air temperature is 20 C and
-            wind speed is 0 m/s.
-            Columns must be 'wind_speed', 'temp_air'.
+            If None, the weather attribute is used. If the weather attribute is
+            also None assumes air temperature is 20 C, wind speed is 0 m/s and
+            irradiation calculated from clear sky data.
+            Column names must be 'wind_speed', 'temp_air', 'dni', 'ghi', 'dhi'.
+            Do not pass incomplete irradiation data.
+            Use method
+            :py:meth:`~pvlib.modelchain.ModelChain.complete_irradiance`
+            instead.
 
         Returns
         -------
         self
 
-        Assigns attributes: times, solar_position, airmass, irradiance,
-        total_irrad, weather, aoi
+        Assigns attributes: times, solar_position, airmass, total_irrad, aoi
         """
-
-        self.times = times
+        # Add columns that does not exist and overwrite existing columns
+        # Maybe there is a more elegant way to do this. Any ideas?
+        if weather is not None:
+            self.weather = self.weather.combine_first(weather)
+            self.weather.update(weather)
+
+        # The following part could be removed together with the irradiance
+        # parameter at version v0.5 or v0.6.
+        # **** Begin ****
+        wrn_txt = "The irradiance parameter will be removed soon.\n"
+        wrn_txt += "Please use the weather parameter to pass a DataFrame with "
+        wrn_txt += "irradiance (ghi, dni, dhi), wind speed and temp_air"
+        if irradiance is not None:
+            warnings.warn(wrn_txt, FutureWarning)
+            for column in irradiance.columns:
+                self.weather[column] = irradiance.pop(column)
+        # **** End ****
+
+        if times is not None:
+            self.times = times
 
         self.solar_position = self.location.get_solarposition(self.times)
 
@@ -637,12 +711,15 @@ def prepare_inputs(self, times, irradiance=None, weather=None):
         self.aoi = self.system.get_aoi(self.solar_position['apparent_zenith'],
                                        self.solar_position['azimuth'])
 
-        if irradiance is None:
-            irradiance = self.location.get_clearsky(
+        if not any([x in ['ghi', 'dni', 'dhi'] for x in self.weather.columns]):
+            self.weather[['ghi', 'dni', 'dhi']] = self.location.get_clearsky(
                 self.solar_position.index, self.clearsky_model,
                 zenith_data=self.solar_position['apparent_zenith'],
                 airmass_data=self.airmass['airmass_absolute'])
-        self.irradiance = irradiance
+
+        if not {'ghi', 'dni', 'dhi'} <= set(self.weather.columns):
+            ValueError(
+                "Uncompleted irradiance data set. Please check you input data")
 
         # PVSystem.get_irradiance and SingleAxisTracker.get_irradiance
         # have different method signatures, so use partial to handle
@@ -670,16 +747,16 @@ def prepare_inputs(self, times, irradiance=None, weather=None):
                 self.solar_position['azimuth'])
 
         self.total_irrad = get_irradiance(
-            self.irradiance['dni'],
-            self.irradiance['ghi'],
-            self.irradiance['dhi'],
+            self.weather['dni'],
+            self.weather['ghi'],
+            self.weather['dhi'],
             airmass=self.airmass['airmass_relative'],
             model=self.transposition_model)
 
-        if weather is None:
-            weather = {'wind_speed': 0, 'temp_air': 20}
-        self.weather = weather
-
+        if self.weather.get('wind_speed') is None:
+            self.weather['wind_speed'] = 0
+        if self.weather.get('temp_air') is None:
+            self.weather['temp_air'] = 20
         return self
 
     def run_model(self, times, irradiance=None, weather=None):
@@ -690,15 +767,14 @@ def run_model(self, times, irradiance=None, weather=None):
         ----------
         times : DatetimeIndex
             Times at which to evaluate the model.
-
-        irradiance : None or DataFrame
-            If None, calculates clear sky data.
-            Columns must be 'dni', 'ghi', 'dhi'.
-
         weather : None or DataFrame
-            If None, assumes air temperature is 20 C and
-            wind speed is 0 m/s.
-            Columns must be 'wind_speed', 'temp_air'.
+            If None, assumes air temperature is 20 C, wind speed is 0 m/s and
+            irradiation calculated from clear sky data.
+            Column names must be 'wind_speed', 'temp_air', 'dni', 'ghi', 'dhi'.
+            Do not pass incomplete irradiation data.
+            Use method
+            :py:meth:`~pvlib.modelchain.ModelChain.complete_irradiance`
+            instead.
 
         Returns
         -------

pvlib/test/test_modelchain.py

@@ -102,7 +102,7 @@ def test_run_model_with_irradiance(system, location):
     times = pd.date_range('20160101 1200-0700', periods=2, freq='6H')
     irradiance = pd.DataFrame({'dni':900, 'ghi':600, 'dhi':150},
                               index=times)
-    ac = mc.run_model(times, irradiance=irradiance).ac
+    ac = mc.run_model(times, weather=irradiance).ac
 
     expected = pd.Series(np.array([  1.90054749e+02,  -2.00000000e-02]),
                          index=times)
@@ -114,7 +114,7 @@ def test_run_model_perez(system, location):
     times = pd.date_range('20160101 1200-0700', periods=2, freq='6H')
     irradiance = pd.DataFrame({'dni':900, 'ghi':600, 'dhi':150},
                               index=times)
-    ac = mc.run_model(times, irradiance=irradiance).ac
+    ac = mc.run_model(times, weather=irradiance).ac
 
     expected = pd.Series(np.array([  190.194545796,  -2.00000000e-02]),
                          index=times)
@@ -127,7 +127,7 @@ def test_run_model_gueymard_perez(system, location):
     times = pd.date_range('20160101 1200-0700', periods=2, freq='6H')
     irradiance = pd.DataFrame({'dni':900, 'ghi':600, 'dhi':150},
                               index=times)
-    ac = mc.run_model(times, irradiance=irradiance).ac
+    ac = mc.run_model(times, weather=irradiance).ac
 
     expected = pd.Series(np.array([  190.194760203,  -2.00000000e-02]),
                          index=times)
@@ -415,3 +415,60 @@ def test_ModelChain___repr__(system, location):
     'orientation_startegy: south_at_latitude_tilt clearsky_model: '+
     'ineichen transposition_model: haydavies solar_position_method: '+
     'nrel_numpy airmass_model: kastenyoung1989')
+
+
+@requires_scipy
+def test_weather_irradiance_input(system, location):
+    """Test will raise a warning and should be removed in future versions."""
+    mc = ModelChain(system, location)
+    times = pd.date_range('2012-06-01 12:00:00', periods=2, freq='H')
+    i = pd.DataFrame({'dni': [2, 3], 'dhi': [4, 6], 'ghi': [9, 5]}, index=times)
+    w = pd.DataFrame({'wind_speed': [11, 5], 'temp_air': [30, 32]}, index=times)
+    mc.run_model(times, irradiance=i, weather=w)
+
+    assert_series_equal(mc.weather['dni'],
+                        pd.Series([2, 3], index=times, name='dni'))
+    assert_series_equal(mc.weather['wind_speed'],
+                        pd.Series([11, 5], index=times, name='wind_speed'))
+
+
+@requires_scipy
+def test_complete_irradiance_clean_run(system, location):
+    """The DataFrame should not change if all columns are passed"""
+    mc = ModelChain(system, location)
+    times = pd.date_range('2010-07-05 9:00:00', periods=2, freq='H')
+    i = pd.DataFrame({'dni': [2, 3], 'dhi': [4, 6], 'ghi': [9, 5]}, index=times)
+
+    mc.complete_irradiance(times, weather=i)
+
+    assert_series_equal(mc.weather['dni'],
+                        pd.Series([2, 3], index=times, name='dni'))
+    assert_series_equal(mc.weather['dhi'],
+                        pd.Series([4, 6], index=times, name='dhi'))
+    assert_series_equal(mc.weather['ghi'],
+                        pd.Series([9, 5], index=times, name='ghi'))
+
+
+@requires_scipy
+def test_complete_irradiance(system, location):
+    """Check calculations"""
+    mc = ModelChain(system, location)
+    times = pd.date_range('2010-07-05 9:00:00', periods=2, freq='H')
+    i = pd.DataFrame({'dni': [30.354455, 77.22822],
+                      'dhi': [372.103976116, 497.087579068],
+                      'ghi': [356.543700, 465.44400]}, index=times)
+
+    mc.complete_irradiance(times, weather=i[['ghi', 'dni']])
+    assert_series_equal(mc.weather['dhi'],
+                        pd.Series([372.103976116, 497.087579068],
+                                  index=times, name='dhi'))
+
+    mc.complete_irradiance(times, weather=i[['dhi', 'dni']])
+    assert_series_equal(mc.weather['ghi'],
+                        pd.Series([356.543700, 465.44400],
+                                  index=times, name='ghi'))
+
+    mc.complete_irradiance(times, weather=i[['dhi', 'ghi']])
+    assert_series_equal(mc.weather['dni'],
+                        pd.Series([30.354455, 77.22822],
+                                  index=times, name='dni'))