add get_[relative_airmass,sky_diffuse,ground_diffuse,extra_radiation,total_irradiance] and pvlibDeprecationWarning (#427)

* initial refactor

* remove new fields from globalinplane wrapper

* update test

* update whatsnew

* add DeprecationWarning

* update api.rst

* add _deprecation.py module

* extraradiation to get_extra_radiation

* grounddiffuse to get_ground_diffuse

* remove deprecated klutcher (misspelling) from get_sky_diffuse

* total_irrad to get_total_poa_irradiance

* update api.rst

* change airmass function names

* forgot to change get_extra_radiation in api.rst

* remove poa from new function names

* no PVLIBDeprecationWarnings in tests

* update deprecation versions

* fix bad merge of whatsnew

* add fail_on_pvlib_version decorator

* pep8

* rename warning, add test_conftest

* remove extra comments

* fix broken test

* update get_total_irradiance arg names

* add test values, fix botched merges

* update to latest mpl code with minor mods

* remove missed kwarg only syntax

* absolute_airmass becomes get_absolute_airmass for consistency and future proofing

* update extraradiation call in forecast.py

* update docs to use new api

* update tutorials

* appveyor config

* sprinkle plt.close to reduce memory on rtd

* fix fail_on_pvlib_version

* allow xpass on python2 and windows

Author: wholmgren

appveyor.yml

@@ -29,7 +29,7 @@ install:
     - cmd: conda info -a
 
     # install depenencies
-    - cmd: conda create -n test_env --yes --quiet python=%PYTHON_VERSION% pip numpy scipy pytables pandas nose pytest pytz ephem numba siphon pytest-mock -c conda-forge
+    - cmd: conda create -n test_env --yes --quiet python=%PYTHON_VERSION% numpy scipy pytables pandas nose pytest pytz ephem numba siphon pytest-mock -c conda-forge
     - cmd: activate test_env
     - cmd: python --version
     - cmd: conda list
@@ -40,4 +40,4 @@ install:
 build: false
 
 test_script:
-    - cmd: py.test -v pvlib
+    - cmd: pytest -v pvlib

docs/sphinx/source/api.rst

@@ -102,8 +102,8 @@ Airmass and atmospheric models
    :toctree: generated/
 
    location.Location.get_airmass
-   atmosphere.absoluteairmass
-   atmosphere.relativeairmass
+   atmosphere.get_absolute_airmass
+   atmosphere.get_relative_airmass
    atmosphere.pres2alt
    atmosphere.alt2pres
    atmosphere.gueymard94_pw
@@ -133,21 +133,22 @@ Decomposing and combining irradiance
 .. autosummary::
    :toctree: generated/
 
-   irradiance.extraradiation
+   irradiance.get_extra_radiation
    irradiance.aoi
    irradiance.aoi_projection
    irradiance.poa_horizontal_ratio
    irradiance.beam_component
-   irradiance.globalinplane
-   irradiance.grounddiffuse
+   irradiance.poa_components
+   irradiance.get_ground_diffuse
 
 Transposition models
 --------------------
 
 .. autosummary::
    :toctree: generated/
 
-   irradiance.total_irrad
+   irradiance.get_total_irradiance
+   irradiance.get_sky_diffuse
    irradiance.isotropic
    irradiance.perez
    irradiance.haydavies

docs/sphinx/source/clearsky.rst

@@ -213,15 +213,15 @@ A clear sky time series using only basic pvlib functions.
 
     In [1]: apparent_zenith = solpos['apparent_zenith']
 
-    In [1]: airmass = pvlib.atmosphere.relativeairmass(apparent_zenith)
+    In [1]: airmass = pvlib.atmosphere.get_relative_airmass(apparent_zenith)
 
     In [1]: pressure = pvlib.atmosphere.alt2pres(altitude)
 
-    In [1]: airmass = pvlib.atmosphere.absoluteairmass(airmass, pressure)
+    In [1]: airmass = pvlib.atmosphere.get_absolute_airmass(airmass, pressure)
 
     In [1]: linke_turbidity = pvlib.clearsky.lookup_linke_turbidity(times, latitude, longitude)
 
-    In [1]: dni_extra = pvlib.irradiance.extraradiation(times)
+    In [1]: dni_extra = pvlib.irradiance.get_extra_radiation(times)
 
     # an input is a pandas Series, so solis is a DataFrame
     In [1]: ineichen = clearsky.ineichen(apparent_zenith, airmass, linke_turbidity, altitude, dni_extra)
@@ -253,17 +253,17 @@ Grid with a clear sky irradiance for a few turbidity values.
 
     In [1]: apparent_zenith = solpos['apparent_zenith']
 
-    In [1]: airmass = pvlib.atmosphere.relativeairmass(apparent_zenith)
+    In [1]: airmass = pvlib.atmosphere.get_relative_airmass(apparent_zenith)
 
     In [1]: pressure = pvlib.atmosphere.alt2pres(altitude)
 
-    In [1]: airmass = pvlib.atmosphere.absoluteairmass(airmass, pressure)
+    In [1]: airmass = pvlib.atmosphere.get_absolute_airmass(airmass, pressure)
 
     In [1]: linke_turbidity = pvlib.clearsky.lookup_linke_turbidity(times, latitude, longitude)
 
     In [1]: print('climatological linke_turbidity = {}'.format(linke_turbidity.mean()))
 
-    In [1]: dni_extra = pvlib.irradiance.extraradiation(times)
+    In [1]: dni_extra = pvlib.irradiance.get_extra_radiation(times)
 
     In [1]: linke_turbidities = [linke_turbidity.mean(), 2, 4]
 
@@ -280,6 +280,9 @@ Grid with a clear sky irradiance for a few turbidity values.
     @savefig ineichen-grid.png width=10in
     In [1]: plt.show();
 
+    @suppress
+    In [1]: plt.close();
+
 
 
 Validation
@@ -350,7 +353,7 @@ A clear sky time series using only basic pvlib functions.
 
     In [1]: pressure = pvlib.atmosphere.alt2pres(altitude)
 
-    In [1]: dni_extra = pvlib.irradiance.extraradiation(times)
+    In [1]: dni_extra = pvlib.irradiance.get_extra_radiation(times)
 
     # an input is a Series, so solis is a DataFrame
     In [1]: solis = clearsky.simplified_solis(apparent_elevation, aod700, precipitable_water,
@@ -367,6 +370,9 @@ A clear sky time series using only basic pvlib functions.
     @savefig solis-vs-time-0.1-1.png width=6in
     In [1]: plt.show();
 
+    @suppress
+    In [1]: plt.close();
+
 The input data types determine the returned output type. Array input
 results in an OrderedDict of array output, and Series input results in a
 DataFrame output. The keys are 'ghi', 'dni', and 'dhi'.
@@ -399,6 +405,9 @@ Irradiance as a function of solar elevation.
     @savefig solis-vs-elevation.png width=6in
     In [1]: ax.legend(loc=2);
 
+    @suppress
+    In [1]: plt.close();
+
 
 Grid with a clear sky irradiance for a few PW and AOD values.
 
@@ -412,7 +421,7 @@ Grid with a clear sky irradiance for a few PW and AOD values.
 
     In [1]: pressure = pvlib.atmosphere.alt2pres(altitude)
 
-    In [1]: dni_extra = pvlib.irradiance.extraradiation(times)
+    In [1]: dni_extra = pvlib.irradiance.get_extra_radiation(times)
 
     In [1]: aod700 = [0.01, 0.1]
 
@@ -429,6 +438,9 @@ Grid with a clear sky irradiance for a few PW and AOD values.
     @savefig solis-grid.png width=10in
     In [1]: plt.show();
 
+    @suppress
+    In [1]: plt.close();
+
 Contour plots of irradiance as a function of both PW and AOD.
 
 .. ipython::
@@ -474,16 +486,25 @@ Contour plots of irradiance as a function of both PW and AOD.
     @savefig solis-ghi.png width=10in
     In [1]: plt.show()
 
+    @suppress
+    In [1]: plt.close();
+
     In [1]: plot_solis('dni')
 
     @savefig solis-dni.png width=10in
     In [1]: plt.show()
 
+    @suppress
+    In [1]: plt.close();
+
     In [1]: plot_solis('dhi')
 
     @savefig solis-dhi.png width=10in
     In [1]: plt.show()
 
+    @suppress
+    In [1]: plt.close();
+
 
 Validation
 ^^^^^^^^^^
@@ -548,6 +569,9 @@ GHI data. We first generate and plot the clear sky and measured data.
     @savefig detect-clear-ghi.png width=10in
     plt.show();
 
+    @suppress
+    plt.close();
+
 Now we run the synthetic data and clear sky estimate through the
 :py:func:`~pvlib.clearsky.detect_clearsky` function.
 
@@ -562,6 +586,9 @@ Now we run the synthetic data and clear sky estimate through the
     @savefig detect-clear-detected.png width=10in
     ax.set_ylabel('Clear (1) or Cloudy (0)');
 
+    @suppress
+    plt.close();
+
 The algorithm detected the cloud event and the overirradiance event.
 
 

docs/sphinx/source/forecasts.rst

@@ -195,6 +195,8 @@ cover forecasts.
               .format(latitude, longitude));
     @savefig gfs_cloud_cover.png width=6in
     plt.legend();
+    @suppress
+    plt.close();
 
 However, many of forecast models do not include radiation components in
 their output fields, or if they do then the radiation fields suffer from
@@ -245,6 +247,8 @@ irradiance conversion using the clear sky scaling algorithm.
               .format(latitude, longitude));
     @savefig gfs_irrad_cs.png width=6in
     plt.legend();
+    @suppress
+    plt.close();
 
 
 The essential parts of the Liu-Jordan cloud cover to irradiance algorithm
@@ -271,6 +275,8 @@ irradiance conversion.
               .format(latitude, longitude));
     @savefig gfs_irrad_lj.png width=6in
     plt.legend();
+    @suppress
+    plt.close();
 
 
 Most weather model output has a fairly coarse time resolution, at least
@@ -290,6 +296,8 @@ recalculate the irradiance.
               .format(latitude, longitude));
     @savefig gfs_irrad_high_res.png width=6in
     plt.legend();
+    @suppress
+    plt.close();
 
 Users may then recombine resampled_irrads and resampled_data using
 slicing :py:func:`pandas.concat` or :py:meth:`pandas.DataFrame.join`.
@@ -345,6 +353,8 @@ The HRRR model covers the continental United States.
               .format(latitude, longitude));
     @savefig hrrr_irrad.png width=6in
     plt.legend();
+    @suppress
+    plt.close();
 
 
 RAP
@@ -369,6 +379,8 @@ The RAP model covers most of North America.
               .format(latitude, longitude));
     @savefig rap_irrad.png width=6in
     plt.legend();
+    @suppress
+    plt.close();
 
 
 NAM
@@ -389,6 +401,8 @@ resolution NAM data with a time horizon of up to 4 days.
               .format(latitude, longitude));
     @savefig nam_irrad.png width=6in
     plt.legend();
+    @suppress
+    plt.close();
 
 
 NDFD
@@ -411,6 +425,8 @@ The NDFD is available for the United States.
               .format(latitude, longitude));
     @savefig ndfd_irrad.png width=6in
     plt.legend();
+    @suppress
+    plt.close();
 
 
 PV Power Forecast
@@ -456,6 +472,8 @@ Here's the forecast plane of array irradiance...
     @savefig poa_irrad.png width=6in
     plt.ylabel('Plane of array irradiance ($W/m^2$)');
     plt.legend(loc='best');
+    @suppress
+    plt.close();
 
 ...the cell and module temperature...
 
@@ -464,6 +482,8 @@ Here's the forecast plane of array irradiance...
     mc.temps.plot();
     @savefig pv_temps.png width=6in
     plt.ylabel('Temperature (C)');
+    @suppress
+    plt.close();
 
 ...and finally AC power...
 
@@ -473,4 +493,6 @@ Here's the forecast plane of array irradiance...
     plt.ylim(0, None);
     @savefig ac_power.png width=6in
     plt.ylabel('AC Power (W)');
+    @suppress
+    plt.close();
 

docs/sphinx/source/package_overview.rst

@@ -81,23 +81,23 @@ to accomplish our system modeling goal:
         times = naive_times.tz_localize(timezone)
         system['surface_tilt'] = latitude
         solpos = pvlib.solarposition.get_solarposition(times, latitude, longitude)
-        dni_extra = pvlib.irradiance.extraradiation(times)
+        dni_extra = pvlib.irradiance.get_extra_radiation(times)
         dni_extra = pd.Series(dni_extra, index=times)
-        airmass = pvlib.atmosphere.relativeairmass(solpos['apparent_zenith'])
+        airmass = pvlib.atmosphere.get_relative_airmass(solpos['apparent_zenith'])
         pressure = pvlib.atmosphere.alt2pres(altitude)
-        am_abs = pvlib.atmosphere.absoluteairmass(airmass, pressure)
+        am_abs = pvlib.atmosphere.get_absolute_airmass(airmass, pressure)
         tl = pvlib.clearsky.lookup_linke_turbidity(times, latitude, longitude)
         cs = pvlib.clearsky.ineichen(solpos['apparent_zenith'], am_abs, tl,
                                      dni_extra=dni_extra, altitude=altitude)
         aoi = pvlib.irradiance.aoi(system['surface_tilt'], system['surface_azimuth'],
                                    solpos['apparent_zenith'], solpos['azimuth'])
-        total_irrad = pvlib.irradiance.total_irrad(system['surface_tilt'],
-                                                   system['surface_azimuth'],
-                                                   solpos['apparent_zenith'],
-                                                   solpos['azimuth'],
-                                                   cs['dni'], cs['ghi'], cs['dhi'],
-                                                   dni_extra=dni_extra,
-                                                   model='haydavies')
+        total_irrad = pvlib.irradiance.get_total_irradiance(system['surface_tilt'],
+                                                            system['surface_azimuth'],
+                                                            solpos['apparent_zenith'],
+                                                            solpos['azimuth'],
+                                                            cs['dni'], cs['ghi'], cs['dhi'],
+                                                            dni_extra=dni_extra,
+                                                            model='haydavies')
         temps = pvlib.pvsystem.sapm_celltemp(total_irrad['poa_global'],
                                              wind_speed, temp_air)
         effective_irradiance = pvlib.pvsystem.sapm_effective_irradiance(
@@ -116,6 +116,8 @@ to accomplish our system modeling goal:
     energies.plot(kind='bar', rot=0)
     @savefig proc-energies.png width=6in
     plt.ylabel('Yearly energy yield (W hr)')
+    @suppress
+    plt.close();
 
 pvlib-python provides a :py:func:`~pvlib.modelchain.basic_chain`
 function that implements much of the code above. Use this function with
@@ -143,6 +145,8 @@ a full understanding of what it is doing internally!
     energies.plot(kind='bar', rot=0)
     @savefig basic-chain-energies.png width=6in
     plt.ylabel('Yearly energy yield (W hr)')
+    @suppress
+    plt.close();
 
 
 .. _object-oriented:
@@ -197,6 +201,8 @@ objects to accomplish our system modeling goal:
     energies.plot(kind='bar', rot=0)
     @savefig modelchain-energies.png width=6in
     plt.ylabel('Yearly energy yield (W hr)')
+    @suppress
+    plt.close();
 
 
 Object oriented (LocalizedPVSystem)
@@ -255,6 +261,8 @@ object to accomplish our modeling goal:
     energies.plot(kind='bar', rot=0)
     @savefig localized-pvsystem-energies.png width=6in
     plt.ylabel('Yearly energy yield (W hr)')
+    @suppress
+    plt.close();
 
 
 User extensions

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

@@ -5,6 +5,34 @@ v0.6.0 (___, 2018)
 
 API Changes
 ~~~~~~~~~~~
+* pvlib python is changing a handful of function names. In general, functions
+  that can calculate a quantity using multiple algorithms now start
+  with the prefix ``get_``. For example, ``relativeairmass`` can calculate
+  airmass using one of many ``model`` arguments. Its name has been changed
+  to ``get_relative_airmass``. The old function names remain in this
+  release, but will emit a ``PVLibDeprecationWarning`` when called. The
+  old functions will be removed in the 0.7 release. Functions composed
+  of multiple words jammed together have been renamed with underscores
+  separating the words (see above).
+  Each change is detailed below. (:issue:`427`)
+* Deprecated relativeairmass. relativeairmass will be removed in 0.7.
+  Use the new get_relative_airmass instead. (:issue:`427`)
+* Deprecated absoluteairmass. absoluteairmass will be removed in 0.7.
+  Use the new get_absolute_airmass instead. (:issue:`427`)
+* Deprecated irradiance.globalinplane. globalinplane will be removed in 0.7.
+  Use the new irradiance.poa_components instead. (:issue:`427`)
+* Added irradiance.poa_components. Function is the same as the now-deprecated
+  irradiance.globalinplane, but adds 'poa_sky_diffuse' and
+  'poa_ground_diffuse' to the output. (:issue:`427`)
+* Deprecated irradiance.extraradiation. Use irradiance.get_extra_radiation
+  instead. irradiance.extraradiation will be removed in 0.7. (:issue:`427`)
+* Deprecated irradiance.grounddiffuse. Use irradiance.get_ground_diffuse
+  instead. irradiance.grounddiffuse will be removed in 0.7. (:issue:`427`)
+* Added irradiance.get_poa_sky_diffuse. (:issue:`427`)
+* Deprecated irradiance.total_irrad. Use irradiance.get_total_poa_irradiance
+  instead. irradiance.total_irrad will be removed in 0.7. (:issue:`427`)
+* Removed 'klutcher' from get_sky_diffuse/total_irrad. This misspelling was
+  deprecated long ago but never removed. (:issue:`97`)
 * pvsystem.calcparams_desoto now requires arguments for each module model
   parameter. (:issue:`462`)
 * Add losses_parameters attribute to PVSystem objects and remove the kwargs