Make several undocumented functions private

docs/sphinx/source/reference/solarposition.rst

@@ -29,7 +29,7 @@ Additional functions for quantities closely related to solar position.
    solarposition.calc_time
    solarposition.pyephem_earthsun_distance
    solarposition.nrel_earthsun_distance
-   spa.calculate_deltat
+   solarposition.calculate_deltat
 
 
 Functions for calculating sunrise, sunset and transit times.
@@ -43,14 +43,6 @@ Functions for calculating sunrise, sunset and transit times.
    solarposition.sun_rise_set_transit_geometric
 
 
-The spa module contains the implementation of the built-in NREL SPA
-algorithm.
-
-.. autosummary::
-   :toctree: generated/
-
-   spa
-
 Correlations and analytical expressions for low precision solar position
 calculations.
 

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

@@ -12,6 +12,14 @@ Breaking Changes
   (:issue:`1724`, :pull:`1739`)
 * For consistency with the rest of pvlib, the ``tilt`` parameter is renamed
   to ``surface_tilt`` in :py:func:`pvlib.soiling.hsu`. (:issue:`1717`, :pull:`1738`)
+* The largely undocumented :py:mod:`pvlib.spa` module is now private.  Users
+  are directed to the wrapper functions in :py:mod:`pvlib.solarposition` instead.
+  Additionally, the :py:func:`~pvlib.solarposition.calculate_deltat` function
+  has been moved to :py:mod:`pvlib.solarposition`. (:issue:`1756`, :pull:`1769`)
+* Several other undocumented functions in :py:mod:`pvlib.iotools.midc`,
+  :py:mod:`pvlib.iotools.srml`, :py:mod:`pvlib.iotools.surfrad`, and
+  :py:mod:`pvlib.scaling` are now private as well. (:issue:`1756`, :pull:`1769`)
+
 
 Deprecations
 ~~~~~~~~~~~~

pvlib/__init__.py

@@ -22,7 +22,6 @@
     snow,
     soiling,
     solarposition,
-    spa,
     temperature,
     tools,
     tracking,

pvlib/spa.py → pvlib/_spa.py

@@ -1245,133 +1245,3 @@ def earthsun_distance(unixtime, delta_t, numthreads):
 
     return R
 
-
-def calculate_deltat(year, month):
-    """Calculate the difference between Terrestrial Dynamical Time (TD)
-    and Universal Time (UT).
-
-    Note: This function is not yet compatible for calculations using
-    Numba.
-
-    Equations taken from http://eclipse.gsfc.nasa.gov/SEcat5/deltatpoly.html
-    """
-
-    plw = 'Deltat is unknown for years before -1999 and after 3000. ' \
-          'Delta values will be calculated, but the calculations ' \
-          'are not intended to be used for these years.'
-
-    try:
-        if np.any((year > 3000) | (year < -1999)):
-            warnings.warn(plw)
-    except ValueError:
-        if (year > 3000) | (year < -1999):
-            warnings.warn(plw)
-    except TypeError:
-        return 0
-
-    y = year + (month - 0.5)/12
-
-    deltat = np.where(year < -500,
-
-                      -20+32*((y-1820)/100)**2, 0)
-
-    deltat = np.where((-500 <= year) & (year < 500),
-
-                      10583.6-1014.41*(y/100)
-                      + 33.78311*(y/100)**2
-                      - 5.952053*(y/100)**3
-                      - 0.1798452*(y/100)**4
-                      + 0.022174192*(y/100)**5
-                      + 0.0090316521*(y/100)**6, deltat)
-
-    deltat = np.where((500 <= year) & (year < 1600),
-
-                      1574.2-556.01*((y-1000)/100)
-                      + 71.23472*((y-1000)/100)**2
-                      + 0.319781*((y-1000)/100)**3
-                      - 0.8503463*((y-1000)/100)**4
-                      - 0.005050998*((y-1000)/100)**5
-                      + 0.0083572073*((y-1000)/100)**6, deltat)
-
-    deltat = np.where((1600 <= year) & (year < 1700),
-
-                      120-0.9808*(y-1600)
-                      - 0.01532*(y-1600)**2
-                      + (y-1600)**3/7129, deltat)
-
-    deltat = np.where((1700 <= year) & (year < 1800),
-
-                      8.83+0.1603*(y-1700)
-                      - 0.0059285*(y-1700)**2
-                      + 0.00013336*(y-1700)**3
-                      - (y-1700)**4/1174000, deltat)
-
-    deltat = np.where((1800 <= year) & (year < 1860),
-
-                      13.72-0.332447*(y-1800)
-                      + 0.0068612*(y-1800)**2
-                      + 0.0041116*(y-1800)**3
-                      - 0.00037436*(y-1800)**4
-                      + 0.0000121272*(y-1800)**5
-                      - 0.0000001699*(y-1800)**6
-                      + 0.000000000875*(y-1800)**7, deltat)
-
-    deltat = np.where((1860 <= year) & (year < 1900),
-
-                      7.62+0.5737*(y-1860)
-                      - 0.251754*(y-1860)**2
-                      + 0.01680668*(y-1860)**3
-                      - 0.0004473624*(y-1860)**4
-                      + (y-1860)**5/233174, deltat)
-
-    deltat = np.where((1900 <= year) & (year < 1920),
-
-                      -2.79+1.494119*(y-1900)
-                      - 0.0598939*(y-1900)**2
-                      + 0.0061966*(y-1900)**3
-                      - 0.000197*(y-1900)**4, deltat)
-
-    deltat = np.where((1920 <= year) & (year < 1941),
-
-                      21.20+0.84493*(y-1920)
-                      - 0.076100*(y-1920)**2
-                      + 0.0020936*(y-1920)**3, deltat)
-
-    deltat = np.where((1941 <= year) & (year < 1961),
-
-                      29.07+0.407*(y-1950)
-                      - (y-1950)**2/233
-                      + (y-1950)**3/2547, deltat)
-
-    deltat = np.where((1961 <= year) & (year < 1986),
-
-                      45.45+1.067*(y-1975)
-                      - (y-1975)**2/260
-                      - (y-1975)**3/718, deltat)
-
-    deltat = np.where((1986 <= year) & (year < 2005),
-
-                      63.86+0.3345*(y-2000)
-                      - 0.060374*(y-2000)**2
-                      + 0.0017275*(y-2000)**3
-                      + 0.000651814*(y-2000)**4
-                      + 0.00002373599*(y-2000)**5, deltat)
-
-    deltat = np.where((2005 <= year) & (year < 2050),
-
-                      62.92+0.32217*(y-2000)
-                      + 0.005589*(y-2000)**2, deltat)
-
-    deltat = np.where((2050 <= year) & (year < 2150),
-
-                      -20+32*((y-1820)/100)**2
-                      - 0.5628*(2150-y), deltat)
-
-    deltat = np.where(year >= 2150,
-
-                      -20+32*((y-1820)/100)**2, deltat)
-
-    deltat = deltat.item() if np.isscalar(year) & np.isscalar(month)\
-        else deltat
-
-    return deltat

pvlib/iotools/midc.py

@@ -102,7 +102,7 @@
 }
 
 
-def format_index(data):
+def _format_index(data):
     """Create DatetimeIndex for the Dataframe localized to the timezone provided
     as the label of the second (time) column.
 
@@ -126,7 +126,7 @@ def format_index(data):
     return data
 
 
-def format_index_raw(data):
+def _format_index_raw(data):
     """Create DatetimeIndex for the Dataframe localized to the timezone provided
     as the label of the third column.
 
@@ -200,9 +200,9 @@ def read_midc(filename, variable_map={}, raw_data=False, **kwargs):
     """
     data = pd.read_csv(filename, **kwargs)
     if raw_data:
-        data = format_index_raw(data)
+        data = _format_index_raw(data)
     else:
-        data = format_index(data)
+        data = _format_index(data)
     data = data.rename(columns=variable_map)
     return data
 

pvlib/iotools/srml.py

@@ -60,11 +60,11 @@ def read_srml(filename):
        `http://solardat.uoregon.edu/ <http://solardat.uoregon.edu/>`_
     """
     tsv_data = pd.read_csv(filename, delimiter='\t')
-    data = format_index(tsv_data)
+    data = _format_index(tsv_data)
     # Drop day of year and time columns
     data = data[data.columns[2:]]
 
-    data = data.rename(columns=map_columns)
+    data = data.rename(columns=_map_columns)
 
     # Quality flag columns are all labeled 0 in the original data. They
     # appear immediately after their associated variable and are suffixed
@@ -90,7 +90,7 @@ def read_srml(filename):
     return data
 
 
-def map_columns(col):
+def _map_columns(col):
     """Map data element numbers to pvlib names.
 
     Parameters
@@ -118,7 +118,7 @@ def map_columns(col):
         return col
 
 
-def format_index(df):
+def _format_index(df):
     """Create a datetime index from day of year, and time columns.
 
     Parameters

pvlib/iotools/surfrad.py

@@ -150,7 +150,7 @@ def read_surfrad(filename, map_variables=True):
                        header=None, names=SURFRAD_COLUMNS)
     file_buffer.close()
 
-    data = format_index(data)
+    data = _format_index(data)
     missing = data == -9999.9
     data = data.where(~missing, np.NaN)
 
@@ -159,7 +159,7 @@ def read_surfrad(filename, map_variables=True):
     return data, metadata
 
 
-def format_index(data):
+def _format_index(data):
     """Create UTC localized DatetimeIndex for the dataframe.
 
     Parameters

pvlib/scaling.py

@@ -146,7 +146,7 @@ def fn(x):
     return vr
 
 
-def latlon_to_xy(coordinates):
+def _latlon_to_xy(coordinates):
     """
     Convert latitude and longitude in degrees to a coordinate system measured
     in meters from zero deg latitude, zero deg longitude.