ENH: deprecate offset/timerule for freq, add future warnings

Author: adamklein

pandas/core/datetools.py

@@ -1257,7 +1257,7 @@ def _figure_out_timezone(start, end, tzinfo):
 _daterange_cache = {}
 
 def generate_range(start=None, end=None, periods=None,
-                   offset=BDay(), time_rule=None, _deprecated=True):
+                   offset=BDay(), time_rule=None):
     """
     Generates a sequence of dates corresponding to the specified time
     offset. Similar to dateutil.rrule except uses pandas DateOffset

pandas/core/frame.py

@@ -28,7 +28,8 @@
                                 _default_index, _stringify)
 from pandas.core.daterange import DateRange
 from pandas.core.generic import NDFrame
-from pandas.core.index import Index, MultiIndex, NULL_INDEX, _ensure_index
+from pandas.core.index import (Index, DatetimeIndex, MultiIndex, NULL_INDEX,
+                               _ensure_index)
 from pandas.core.indexing import _NDFrameIndexer, _maybe_droplevels
 from pandas.core.internals import BlockManager, make_block, form_blocks
 from pandas.core.series import Series, _radd_compat
@@ -661,7 +662,8 @@ def from_records(cls, data, index=None, exclude=None, columns=None,
             columns = names
             warnings.warn("'names' parameter to DataFrame.from_records is "
                           "being renamed to 'columns', 'names' will be "
-                          "removed in 0.8.0", FutureWarning)
+                          "removed in 0.8.0",
+                          FutureWarning)
 
         if isinstance(data, (np.ndarray, DataFrame, dict)):
             columns, sdict = _rec_to_dict(data)
@@ -2805,7 +2807,30 @@ def unstack(self, level=-1):
     #----------------------------------------------------------------------
     # Time series-related
 
-    def asfreq(self, freq, method=None):
+    def tofreq(self, freq, method=None):
+        """
+        Convert all TimeSeries inside to specified frequency using DateOffset
+        objects. Optionally provide fill method to pad/backfill missing values.
+
+        Parameters
+        ----------
+        freq : DateOffset object, or string
+        method : {'backfill', 'bfill', 'pad', 'ffill', None}
+            Method to use for filling holes in reindexed Series
+            pad / ffill: propagate last valid observation forward to next valid
+            backfill / bfill: use NEXT valid observation to fill methdo
+
+        Returns
+        -------
+        converted : DataFrame
+        """
+        if len(self.index) == 0:
+            return self.copy()
+        dti = DatetimeIndex(self.index[0], self.index[-1], freq=freq)
+        return self.reindex(dti, method=method)
+
+
+    def asfreq(self, offset, method=None):
         """
         Convert all TimeSeries inside to specified frequency using DateOffset
         objects. Optionally provide fill method to pad/backfill missing values.
@@ -2823,14 +2848,19 @@ def asfreq(self, freq, method=None):
         -------
         converted : DataFrame
         """
+
+        import warnings
+        warnings.warn("The 'asfreq' method is deprecated; use 'tofreq' "
+                      " and the new pandas offsets",
+                      FutureWarning)
+        
         if len(self.index) == 0:
             return self.copy()
 
-        if isinstance(freq, datetools.DateOffset):
-            dateRange = DateRange(self.index[0], self.index[-1], offset=freq)
+        if isinstance(offset, datetools.DateOffset):
+            dateRange = DateRange(self.index[0], self.index[-1], offset=offset)
         else:
-            dateRange = DateRange(self.index[0], self.index[-1],
-                                  time_rule=freq)
+            dateRange = DateRange(self.index[0], self.index[-1], time_rule=offset)
 
         return self.reindex(dateRange, method=method)
 
@@ -2852,13 +2882,13 @@ def diff(self, periods=1):
     def shift(self, periods, freq=None, **kwds):
         """
         Shift the index of the DataFrame by desired number of periods with an
-        optional time offset
+        optional time freq
 
         Parameters
         ----------
         periods : int
             Number of periods to move, can be positive or negative
-        offset : DateOffset, timedelta, or time rule string, optional
+        freq : DateOffset, timedelta, or time rule string, optional
             Increment to use from datetools module or time rule (e.g. 'EOM')
 
         Returns
@@ -2881,7 +2911,8 @@ def shift(self, periods, freq=None, **kwds):
         if warn:
             import warnings
             warnings.warn("'timeRule' and 'offset' parameters are deprecated,"
-                          " please use 'freq' instead", FutureWarning)
+                          " please use 'freq' instead",
+                          FutureWarning)
 
         if isinstance(offset, basestring):
             offset = datetools.to_offset(offset)

pandas/core/index.py

@@ -345,7 +345,7 @@ def asof(self, label):
     def sort(self, *args, **kwargs):
         raise Exception('Cannot sort an Index object')
 
-    def shift(self, periods, offset):
+    def shift(self, periods, freq):
         """
         Shift Index containing datetime objects by input number of periods and
         DateOffset
@@ -358,7 +358,7 @@ def shift(self, periods, offset):
             # OK because immutable
             return self
 
-        offset = periods * offset
+        offset = periods * freq
         return Index([idx + offset for idx in self])
 
     def argsort(self, *args, **kwargs):
@@ -1120,15 +1120,27 @@ class DatetimeIndex(Int64Index):
     _sarr_cache = None
 
     def __new__(cls, data=None,
-                offset=None, start=None, end=None, periods=None,
+                freq=None, start=None, end=None, periods=None,
                 dtype=None, copy=False, name=None, tzinfo=None,
-                _deprecated=False, **kwds):
+                **kwds):
+
+        warn = False
+        if 'offset' in kwds and kwds['offset']:
+            freq = kwds['offset']
+            warn = True
+
+        if warn:
+            import warnings
+            warnings.warn("parameter 'offset' is deprecated, "
+                          "please use 'freq' instead",
+                          FutureWarning)
+            if isinstance(freq, basestring):
+                freq = datetools.getOffset(freq)
+        else:
+            if isinstance(freq, basestring):
+                freq = datetools.to_offset(freq)
 
-        if isinstance(offset, basestring):
-            if _deprecated:
-                offset = datetools.getOffset(offset)
-            else:
-                offset = datetools.to_offset(offset)
+        offset = freq
 
         if data is None and offset is None:
             raise ValueError("Must provide offset argument if no data is "
@@ -1153,8 +1165,7 @@ def __new__(cls, data=None,
 
             if useCache:
                 index = cls._cached_range(start, end, periods=periods,
-                                          offset=offset, name=name,
-                                          _deprecated=_deprecated)
+                                          offset=offset, name=name)
             else:
                 if isinstance(offset, datetools.Tick):
                     if periods is None:
@@ -1169,8 +1180,7 @@ def __new__(cls, data=None,
 
                 else:
                     xdr = datetools.generate_range(start=start, end=end,
-                        periods=periods, offset=offset,
-                        _deprecated=_deprecated)
+                        periods=periods, offset=offset)
 
                     data = _dt_unbox_array(list(xdr))
 
@@ -1229,7 +1239,7 @@ def __new__(cls, data=None,
 
     @classmethod
     def _cached_range(cls, start=None, end=None, periods=None, offset=None,
-                      name=None, _deprecated=False):
+                      name=None):
         if start is not None:
             start = Timestamp(start)
         if end is not None:
@@ -1241,8 +1251,7 @@ def _cached_range(cls, start=None, end=None, periods=None, offset=None,
         drc = datetools._daterange_cache
         if offset not in drc:
             xdr = datetools.generate_range(offset=offset,
-                    start=datetools._CACHE_START, end=datetools._CACHE_END,
-                    _deprecated=_deprecated)
+                    start=datetools._CACHE_START, end=datetools._CACHE_END)
 
             arr = np.array(_dt_unbox_array(list(xdr)),
                            dtype='M8[us]', copy=False)
@@ -1341,22 +1350,22 @@ def asobject(self):
         else:
             return Index(_dt_box_array(self.asi8), dtype='object')
 
-    def shift(self, n, offset=None):
+    def shift(self, n, freq=None):
         """
         Specialized shift which produces a DatetimeIndex
 
         Parameters
         ----------
         n : int
             Periods to shift by
-        offset : DateOffset or timedelta-like, optional
+        freq : DateOffset or timedelta-like, optional
 
         Returns
         -------
         shifted : DateRange
         """
-        if offset is not None and offset != self.offset:
-            return Index.shift(self, n, offset)
+        if freq is not None and freq != self.offset:
+            return Index.shift(self, n, freq)
 
         if n == 0:
             # immutable so OK

pandas/core/series.py

@@ -715,8 +715,7 @@ def to_string(self, buf=None, na_rep='NaN', float_format=None,
 
         if nanRep is not None:  # pragma: no cover
             import warnings
-            warnings.warn("nanRep is deprecated, use na_rep",
-                          FutureWarning)
+            warnings.warn("nanRep is deprecated, use na_rep", FutureWarning)
             na_rep = nanRep
 
         the_repr = self._get_repr(float_format=float_format, na_rep=na_rep,
@@ -2268,7 +2267,8 @@ def shift(self, periods, freq=None, **kwds):
         if warn:
             import warnings
             warnings.warn("'timeRule' and 'offset' parameters are deprecated,"
-                          " please use 'freq' instead", FutureWarning)
+                          " please use 'freq' instead",
+                          FutureWarning)
 
         if isinstance(offset, basestring):
             offset = datetools.to_offset(offset)

pandas/tests/test_daterange.py

@@ -127,7 +127,7 @@ def test_shift(self):
         self.assertEquals(shifted.offset, self.rng.offset)
 
         rng = DateRange(START, END, offset=datetools.bmonthEnd)
-        shifted = rng.shift(1, offset=datetools.bday)
+        shifted = rng.shift(1, freq=datetools.bday)
         self.assertEquals(shifted[0], rng[0] + datetools.bday)
 
     def test_pickle_unpickle(self):

pandas/tests/test_datetime64.py

@@ -20,7 +20,7 @@ class TestDatetime64(unittest.TestCase):
 
     def setUp(self):
         dti = DatetimeIndex(start=datetime(2005,1,1),
-                            end=datetime(2005,1,10), offset='Min')
+                            end=datetime(2005,1,10), freq='Min')
 
         self.series = Series(rand(len(dti)), dti)
 
@@ -215,7 +215,7 @@ def test_dayofmonthoffset(self):
                     self.assert_(t.weekday() == day)
 
     def test_datetimeindex_accessors(self):
-        dti = DatetimeIndex(offset='Q@JAN', start=datetime(1997,12,31),
+        dti = DatetimeIndex(freq='Q@JAN', start=datetime(1997,12,31),
                             periods=100)
 
         self.assertEquals(dti.year[0], 1998)
@@ -249,9 +249,9 @@ def test_datetimeindex_accessors(self):
         self.assertEquals(len(dti.quarter), 100)
 
     def test_datetimeindex_diff(self):
-        dti1 = DatetimeIndex(offset='Q@JAN', start=datetime(1997,12,31),
+        dti1 = DatetimeIndex(freq='Q@JAN', start=datetime(1997,12,31),
                              periods=100)
-        dti2 = DatetimeIndex(offset='Q@JAN', start=datetime(1997,12,31),
+        dti2 = DatetimeIndex(freq='Q@JAN', start=datetime(1997,12,31),
                              periods=98)
         self.assert_( len(dti1.diff(dti2)) == 2)
 
@@ -278,7 +278,7 @@ def test_datetimecache(self):
         lib.flush_tcache('W@TUE')
 
     def test_fancy_getitem(self):
-        dti = DatetimeIndex(offset='WOM@1FRI', start=datetime(2005,1,1),
+        dti = DatetimeIndex(freq='WOM@1FRI', start=datetime(2005,1,1),
                             end=datetime(2010,1,1))
 
         s = Series(np.arange(len(dti)), index=dti) 
@@ -294,7 +294,7 @@ def test_fancy_getitem(self):
                             s[datetime(2009,3,6):datetime(2009,6,5)])
 
     def test_fancy_setitem(self):
-        dti = DatetimeIndex(offset='WOM@1FRI', start=datetime(2005,1,1),
+        dti = DatetimeIndex(freq='WOM@1FRI', start=datetime(2005,1,1),
                             end=datetime(2010,1,1))
 
         s = Series(np.arange(len(dti)), index=dti) 
@@ -307,7 +307,7 @@ def test_fancy_setitem(self):
 
     def test_custom_grouper(self):
 
-        dti = DatetimeIndex(offset='Min', start=datetime(2005,1,1),
+        dti = DatetimeIndex(freq='Min', start=datetime(2005,1,1),
                             end=datetime(2005,1,10))
 
         data = np.array([1]*len(dti))
@@ -346,8 +346,8 @@ def test_convert_basic(self):
         assert_series_equal(result, expect)
 
         # from daily
-        dti = DatetimeIndex(start=datetime(2005,1,1), 
-                            end=datetime(2005,1,10), offset='D')
+        dti = DatetimeIndex(start=datetime(2005,1,1), end=datetime(2005,1,10),
+                            freq='D')
 
         s = Series(rand(len(dti)), dti)
 
@@ -400,8 +400,8 @@ def test_convert_basic(self):
 
     def test_convert_upsample(self):
         # from daily
-        dti = DatetimeIndex(start=datetime(2005,1,1), 
-                            end=datetime(2005,1,10), offset='D')
+        dti = DatetimeIndex(start=datetime(2005,1,1), end=datetime(2005,1,10),
+                            freq='D')
 
         s = Series(rand(len(dti)), dti)
 
@@ -434,8 +434,8 @@ def test_convert_olhc(self):
         self.assertEquals(xs['close'], s[5])
 
     def test_convert_reconvert(self):
-        dti = DatetimeIndex(start=datetime(2005,1,1), 
-                            end=datetime(2005,1,10), offset='D')
+        dti = DatetimeIndex(start=datetime(2005,1,1), end=datetime(2005,1,10),
+                            freq='D')
         s = Series(rand(len(dti)), dti)
         s = s.convert('B').convert('8H')
         self.assertEquals(len(s), 22)