Change name to solarposition.sun_rise_set_transit_spa (#603)

* Change name to solarposition.rise_set_transit_spa

* Style fixes

* Adjust column order

* Update whatsnew and api.rst

* Change function names to sun_rise_set_transit pattern

* Fix mistake in sun_rise_set_transit_spa

* Adjust test for timezone

* Undo try-except

* Update v0.6.1.rst

Fix line wrapping

* Edits to api.rst, whatsnew and error messages

* Edit api.rst, fix deprecation version, add deprecation test

* Fix deprecation test lat/long

* Fix deprecation for get_sun_rise_set_transit

* More fixes to deprecate test

* And more fixes to deprecate test

* And more fixes to deprecate test

Author: cwhanse

docs/sphinx/source/api.rst

@@ -55,9 +55,19 @@ Additional functions for quantities closely related to solar position.
    solarposition.calc_time
    solarposition.pyephem_earthsun_distance
    solarposition.nrel_earthsun_distance
-   solarposition.rise_set_transit_ephem
    spa.calculate_deltat
 
+
+Functions for calculating sunrise, sunset and transit times.
+
+.. autosummary::
+   :toctree: generated/
+
+   solarposition.sun_rise_set_transit_ephem
+   solarposition.sun_rise_set_transit_spa
+   solarposition.sun_rise_set_transit_geometric
+
+
 The spa module contains the implementation of the built-in NREL SPA
 algorithm.
 

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

@@ -21,14 +21,17 @@ API Changes
 * Added keyword argument ``horizon`` to :func:`~pvlib.solarposition.pyephem`
   and :func:`~pvlib.solarposition.calc_time` with default value ``'+0:00'``
 * Changed key names for `components` returned from :py:func:`pvlib.clearsky.detect_clearsky`
+* Changed function name from :py:func:`pvlib.solarposition.get_rise_set_transit` (deprecated)
+  to :py:func:`pvlib.solarposition.sun_rise_set_transit_spa. `sun_rise_set_transit_spa`
+  requires time input to be localized to the specified latitude/longitude. (:issue:`316')
 
 
 Enhancements
 ~~~~~~~~~~~~
-* :func:`~pvlib.solarposition.rise_set_transit_ephem` returns sunrise, sunset
+* :func:`~pvlib.solarposition.sun_rise_set_transit_ephem` returns sunrise, sunset
   and transit times using pyephem (:issue:`114`)
 * Add geometric functions for sunrise, sunset, and sun transit times,
-  :func:`~pvlib.solarposition.sunrise_sunset_transit_geometric` (:issue:`114`)
+  :func:`~pvlib.solarposition.sun_rise_set_transit_geometric` (:issue:`114`)
 * Created :py:func:`pvlib.iotools.read_srml` and
   :py:func:`pvlib.iotools.read_srml_month_from_solardat` to read University of
   Oregon Solar Radiation Monitoring Laboratory data. (:issue:`589`)

pvlib/solarposition.py

@@ -24,6 +24,8 @@
 
 from pvlib import atmosphere
 from pvlib.tools import datetime_to_djd, djd_to_datetime
+from pvlib._deprecation import deprecated
+
 
 NS_PER_HR = 1.e9 * 3600.  # nanoseconds per hour
 
@@ -40,7 +42,6 @@ def get_solarposition(time, latitude, longitude,
     time : pandas.DatetimeIndex
 
     latitude : float
-
     longitude : float
 
     altitude : None or float, default None
@@ -359,9 +360,8 @@ def spa_python(time, latitude, longitude,
     return result
 
 
-def get_sun_rise_set_transit(time, latitude, longitude, how='numpy',
-                             delta_t=67.0,
-                             numthreads=4):
+def sun_rise_set_transit_spa(times, latitude, longitude, how='numpy',
+                             delta_t=67.0, numthreads=4):
     """
     Calculate the sunrise, sunset, and sun transit times using the
     NREL SPA algorithm described in [1].
@@ -373,13 +373,15 @@ def get_sun_rise_set_transit(time, latitude, longitude, how='numpy',
 
     Parameters
     ----------
-    time : pandas.DatetimeIndex
-        Only the date part is used
+    times : pandas.DatetimeIndex
+        Must be localized to the timezone for ``latitude`` and ``longitude``.
     latitude : float
+        Latitude in degrees, positive north of equator, negative to south
     longitude : float
+        Longitude in degrees, positive east of prime meridian, negative to west
     delta_t : float, optional
         If delta_t is None, uses spa.calculate_deltat
-        using time.year and time.month from pandas.DatetimeIndex.
+        using times.year and times.month from pandas.DatetimeIndex.
         For most simulations specifing delta_t is sufficient.
         Difference between terrestrial time and UT1.
         *Note: delta_t = None will break code using nrel_numba,
@@ -394,9 +396,9 @@ def get_sun_rise_set_transit(time, latitude, longitude, how='numpy',
 
     Returns
     -------
-    DataFrame
-        The DataFrame will have the following columns:
-        sunrise, sunset, transit
+    pandas.DataFrame
+        index is the same as input `times` argument
+        columns are 'sunrise', 'sunset', and 'transit'
 
     References
     ----------
@@ -409,36 +411,40 @@ def get_sun_rise_set_transit(time, latitude, longitude, how='numpy',
     lat = latitude
     lon = longitude
 
-    if not isinstance(time, pd.DatetimeIndex):
-        try:
-            time = pd.DatetimeIndex(time)
-        except (TypeError, ValueError):
-            time = pd.DatetimeIndex([time, ])
+    # times must be localized
+    if times.tz:
+        tzinfo = times.tz
+    else:
+        raise ValueError('times must be localized')
 
     # must convert to midnight UTC on day of interest
-    utcday = pd.DatetimeIndex(time.date).tz_localize('UTC')
+    utcday = pd.DatetimeIndex(times.date).tz_localize('UTC')
     unixtime = np.array(utcday.astype(np.int64)/10**9)
 
     spa = _spa_python_import(how)
 
-    delta_t = delta_t or spa.calculate_deltat(time.year, time.month)
+    delta_t = delta_t or spa.calculate_deltat(times.year, times.month)
 
     transit, sunrise, sunset = spa.transit_sunrise_sunset(
         unixtime, lat, lon, delta_t, numthreads)
 
     # arrays are in seconds since epoch format, need to conver to timestamps
     transit = pd.to_datetime(transit*1e9, unit='ns', utc=True).tz_convert(
-        time.tz).tolist()
+        tzinfo).tolist()
     sunrise = pd.to_datetime(sunrise*1e9, unit='ns', utc=True).tz_convert(
-        time.tz).tolist()
+        tzinfo).tolist()
     sunset = pd.to_datetime(sunset*1e9, unit='ns', utc=True).tz_convert(
-        time.tz).tolist()
+        tzinfo).tolist()
 
-    result = pd.DataFrame({'transit': transit,
-                           'sunrise': sunrise,
-                           'sunset': sunset}, index=time)
+    return pd.DataFrame(index=times, data={'sunrise': sunrise,
+                                           'sunset': sunset,
+                                           'transit': transit})
 
-    return result
+
+get_sun_rise_set_transit = deprecated('0.6.1',
+                                      alternative='sun_rise_set_transit_spa',
+                                      name='get_sun_rise_set_transit',
+                                      removal='0.7')(sun_rise_set_transit_spa)
 
 
 def _ephem_convert_to_seconds_and_microseconds(date):
@@ -476,10 +482,11 @@ def _ephem_setup(latitude, longitude, altitude, pressure, temperature,
     return obs, sun
 
 
-def rise_set_transit_ephem(time, latitude, longitude,
-                           next_or_previous='next',
-                           altitude=0,
-                           pressure=101325, temperature=12, horizon='0:00'):
+def sun_rise_set_transit_ephem(times, latitude, longitude,
+                               next_or_previous='next',
+                               altitude=0,
+                               pressure=101325,
+                               temperature=12, horizon='0:00'):
     """
     Calculate the next sunrise and sunset times using the PyEphem package.
 
@@ -488,9 +495,9 @@ def rise_set_transit_ephem(time, latitude, longitude,
     time : pandas.DatetimeIndex
         Must be localized
     latitude : float
-        positive is north of 0
+        Latitude in degrees, positive north of equator, negative to south
     longitude : float
-        positive is east of 0
+        Longitude in degrees, positive east of prime meridian, negative to west
     next_or_previous : str
         'next' or 'previous' sunrise and sunset relative to time
     altitude : float, default 0
@@ -523,8 +530,10 @@ def rise_set_transit_ephem(time, latitude, longitude,
         raise ImportError('PyEphem must be installed')
 
     # times must be localized
-    if not time.tz:
-        raise ValueError('rise_set_ephem: times must be localized')
+    if times.tz:
+        tzinfo = times.tz
+    else:
+        raise ValueError('times must be localized')
 
     obs, sun = _ephem_setup(latitude, longitude, altitude,
                             pressure, temperature, horizon)
@@ -544,18 +553,18 @@ def rise_set_transit_ephem(time, latitude, longitude,
     sunrise = []
     sunset = []
     trans = []
-    for thetime in time:
+    for thetime in times:
         thetime = thetime.to_pydatetime()
         # pyephem drops timezone when converting to its internal datetime
         # format, so handle timezone explicitly here
         obs.date = ephem.Date(thetime - thetime.utcoffset())
-        sunrise.append(_ephem_to_timezone(rising(sun), time.tz))
-        sunset.append(_ephem_to_timezone(setting(sun), time.tz))
-        trans.append(_ephem_to_timezone(transit(sun), time.tz))
+        sunrise.append(_ephem_to_timezone(rising(sun), tzinfo))
+        sunset.append(_ephem_to_timezone(setting(sun), tzinfo))
+        trans.append(_ephem_to_timezone(transit(sun), tzinfo))
 
-    return pd.DataFrame(index=time, data={'sunrise': sunrise,
-                                          'sunset': sunset,
-                                          'transit': trans})
+    return pd.DataFrame(index=times, data={'sunrise': sunrise,
+                                           'sunset': sunset,
+                                           'transit': trans})
 
 
 def pyephem(time, latitude, longitude, altitude=0, pressure=101325,
@@ -1371,8 +1380,8 @@ def _times_to_hours_after_local_midnight(times):
     return np.array(hrs)
 
 
-def sunrise_sunset_transit_geometric(times, latitude, longitude, declination,
-                                     equation_of_time):
+def sun_rise_set_transit_geometric(times, latitude, longitude, declination,
+                                   equation_of_time):
     """
     Geometric calculation of solar sunrise, sunset, and transit.