Deprecate modelchain.basic_chain (#1401)

* deprecate basic_chain

* whatsnew

* stickler

* also recommend with_sapm

Author: kandersolar

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

@@ -8,6 +8,11 @@ Breaking changes
 
 Deprecations
 ~~~~~~~~~~~~
+* :py:func:`pvlib.modelchain.basic_chain` is deprecated.
+  See :py:meth:`pvlib.modelchain.ModelChain.with_pvwatts` and
+  :py:meth:`pvlib.modelchain.ModelChain.with_sapm` for alternative simplified
+  :py:class:`~pvlib.modelchain.ModelChain` interfaces, although note that the
+  inputs do not directly translate. (:pull:`1401`)
 
 Enhancements
 ~~~~~~~~~~~~

pvlib/modelchain.py

@@ -21,6 +21,8 @@
 from pvlib._deprecation import pvlibDeprecationWarning
 from pvlib.tools import _build_kwargs
 
+from pvlib._deprecation import deprecated
+
 # keys that are used to detect input data and assign data to appropriate
 # ModelChain attribute
 # for ModelChain.weather
@@ -62,6 +64,13 @@
 )
 
 
+@deprecated(
+    since='0.9.1',
+    name='pvlib.modelchain.basic_chain',
+    alternative=('pvlib.modelchain.ModelChain.with_pvwatts'
+                 ' or pvlib.modelchain.ModelChain.with_sapm'),
+    addendum='Note that the with_xyz methods take different model parameters.'
+)
 def basic_chain(times, latitude, longitude,
                 surface_tilt, surface_azimuth,
                 module_parameters, temperature_model_parameters,

pvlib/tests/test_modelchain.py

@@ -1799,10 +1799,11 @@ def test_basic_chain_alt_az(sam_data, cec_inverter_parameters,
     modules = sam_data['sandiamod']
     module_parameters = modules['Canadian_Solar_CS5P_220M___2009_']
     temp_model_params = sapm_temperature_cs5p_220m.copy()
-    dc, ac = modelchain.basic_chain(times, latitude, longitude,
-                                    surface_tilt, surface_azimuth,
-                                    module_parameters, temp_model_params,
-                                    cec_inverter_parameters)
+    with pytest.warns(pvlibDeprecationWarning, match='with_pvwatts'):
+        dc, ac = modelchain.basic_chain(times, latitude, longitude,
+                                        surface_tilt, surface_azimuth,
+                                        module_parameters, temp_model_params,
+                                        cec_inverter_parameters)
 
     expected = pd.Series(np.array([111.621405, -2.00000000e-02]),
                          index=times)
@@ -1821,21 +1822,23 @@ def test_basic_chain_altitude_pressure(sam_data, cec_inverter_parameters,
     modules = sam_data['sandiamod']
     module_parameters = modules['Canadian_Solar_CS5P_220M___2009_']
     temp_model_params = sapm_temperature_cs5p_220m.copy()
-    dc, ac = modelchain.basic_chain(times, latitude, longitude,
-                                    surface_tilt, surface_azimuth,
-                                    module_parameters, temp_model_params,
-                                    cec_inverter_parameters,
-                                    pressure=93194)
+    with pytest.warns(pvlibDeprecationWarning, match='with_pvwatts'):
+        dc, ac = modelchain.basic_chain(times, latitude, longitude,
+                                        surface_tilt, surface_azimuth,
+                                        module_parameters, temp_model_params,
+                                        cec_inverter_parameters,
+                                        pressure=93194)
 
     expected = pd.Series(np.array([113.190045, -2.00000000e-02]),
                          index=times)
     assert_series_equal(ac, expected)
 
-    dc, ac = modelchain.basic_chain(times, latitude, longitude,
-                                    surface_tilt, surface_azimuth,
-                                    module_parameters, temp_model_params,
-                                    cec_inverter_parameters,
-                                    altitude=altitude)
+    with pytest.warns(pvlibDeprecationWarning, match='with_pvwatts'):
+        dc, ac = modelchain.basic_chain(times, latitude, longitude,
+                                        surface_tilt, surface_azimuth,
+                                        module_parameters, temp_model_params,
+                                        cec_inverter_parameters,
+                                        altitude=altitude)
 
     expected = pd.Series(np.array([113.189814, -2.00000000e-02]),
                          index=times)