ENH: Experimental CustomBusinessDay DateOffset class. Fixes GH2301.

ENH: Added check for required version of Numpy.
ENH: Added holidays and weekmask arguments to cdate_range as suggested by
@jreback. Also improved docstrings.

Author: Tobias Brandt

pandas/core/datetools.py

@@ -8,6 +8,12 @@
 day = DateOffset()
 bday = BDay()
 businessDay = bday
+try:
+    cday = CDay()
+    customBusinessDay = CustomBusinessDay()
+except ImportError:
+    # Don't create CustomBusinessDay instances when not available
+    pass
 monthEnd = MonthEnd()
 yearEnd = YearEnd()
 yearBegin = YearBegin()

pandas/tseries/frequencies.py

@@ -114,14 +114,17 @@ def _get_freq_str(base, mult=1):
 # Offset names ("time rules") and related functions
 
 
-from pandas.tseries.offsets import (Day, BDay, Hour, Minute, Second, Milli,
-                                    Week, Micro, MonthEnd, MonthBegin,
-                                    BMonthBegin, BMonthEnd, YearBegin, YearEnd,
-                                    BYearBegin, BYearEnd, QuarterBegin,
-                                    QuarterEnd, BQuarterBegin, BQuarterEnd)
+from pandas.tseries.offsets import (Micro, Milli, Second, Minute, Hour,
+                                    Day, BDay, CDay, Week, MonthBegin,
+                                    MonthEnd, BMonthBegin, BMonthEnd,
+                                    QuarterBegin, QuarterEnd, BQuarterBegin,
+                                    BQuarterEnd, YearBegin, YearEnd,
+                                    BYearBegin, BYearEnd,
+                                    )
 
 _offset_map = {
     'D': Day(),
+    'C': CDay(),
     'B': BDay(),
     'H': Hour(),
     'T': Minute(),
@@ -278,6 +281,7 @@ def _get_freq_str(base, mult=1):
     'BAS': 'A',
     'MS': 'M',
     'D': 'D',
+    'C': 'C',
     'B': 'B',
     'T': 'T',
     'S': 'S',
@@ -1004,15 +1008,17 @@ def is_subperiod(source, target):
         if _is_quarterly(source):
             return _quarter_months_conform(_get_rule_month(source),
                                            _get_rule_month(target))
-        return source in ['D', 'B', 'M', 'H', 'T', 'S']
+        return source in ['D', 'C', 'B', 'M', 'H', 'T', 'S']
     elif _is_quarterly(target):
-        return source in ['D', 'B', 'M', 'H', 'T', 'S']
+        return source in ['D', 'C', 'B', 'M', 'H', 'T', 'S']
     elif target == 'M':
-        return source in ['D', 'B', 'H', 'T', 'S']
+        return source in ['D', 'C', 'B', 'H', 'T', 'S']
     elif _is_weekly(target):
-        return source in [target, 'D', 'B', 'H', 'T', 'S']
+        return source in [target, 'D', 'C', 'B', 'H', 'T', 'S']
     elif target == 'B':
         return source in ['B', 'H', 'T', 'S']
+    elif target == 'C':
+        return source in ['C', 'H', 'T', 'S']
     elif target == 'D':
         return source in ['D', 'H', 'T', 'S']
     elif target == 'H':
@@ -1055,17 +1061,19 @@ def is_superperiod(source, target):
             smonth = _get_rule_month(source)
             tmonth = _get_rule_month(target)
             return _quarter_months_conform(smonth, tmonth)
-        return target in ['D', 'B', 'M', 'H', 'T', 'S']
+        return target in ['D', 'C', 'B', 'M', 'H', 'T', 'S']
     elif _is_quarterly(source):
-        return target in ['D', 'B', 'M', 'H', 'T', 'S']
+        return target in ['D', 'C', 'B', 'M', 'H', 'T', 'S']
     elif source == 'M':
-        return target in ['D', 'B', 'H', 'T', 'S']
+        return target in ['D', 'C', 'B', 'H', 'T', 'S']
     elif _is_weekly(source):
-        return target in [source, 'D', 'B', 'H', 'T', 'S']
+        return target in [source, 'D', 'C', 'B', 'H', 'T', 'S']
     elif source == 'B':
-        return target in ['D', 'B', 'H', 'T', 'S']
+        return target in ['D', 'C', 'B', 'H', 'T', 'S']
+    elif source == 'C':
+        return target in ['D', 'C', 'B', 'H', 'T', 'S']
     elif source == 'D':
-        return target in ['D', 'B', 'H', 'T', 'S']
+        return target in ['D', 'C', 'B', 'H', 'T', 'S']
     elif source == 'H':
         return target in ['H', 'T', 'S']
     elif source == 'T':

pandas/tseries/index.py

@@ -11,7 +11,7 @@
 from pandas.tseries.frequencies import (
     infer_freq, to_offset, get_period_alias,
     Resolution, get_reso_string)
-from pandas.tseries.offsets import DateOffset, generate_range, Tick
+from pandas.tseries.offsets import DateOffset, generate_range, Tick, CDay
 from pandas.tseries.tools import parse_time_string, normalize_date
 from pandas.util.decorators import cache_readonly
 import pandas.core.common as com
@@ -1740,6 +1740,52 @@ def bdate_range(start=None, end=None, periods=None, freq='B', tz=None,
                          freq=freq, tz=tz, normalize=normalize, name=name)
 
 
+def cdate_range(start=None, end=None, periods=None, freq='C', tz=None,
+                normalize=True, name=None, **kwargs):
+    """
+    Return a fixed frequency datetime index, with CustomBusinessDay as the
+    default frequency
+
+    Parameters
+    ----------
+    start : string or datetime-like, default None
+        Left bound for generating dates
+    end : string or datetime-like, default None
+        Right bound for generating dates
+    periods : integer or None, default None
+        If None, must specify start and end
+    freq : string or DateOffset, default 'C' (CustomBusinessDay)
+        Frequency strings can have multiples, e.g. '5H'
+    tz : string or None
+        Time zone name for returning localized DatetimeIndex, for example
+        Asia/Beijing
+    normalize : bool, default False
+        Normalize start/end dates to midnight before generating date range
+    name : str, default None
+        Name for the resulting index
+    weekmask : str, Default 'Mon Tue Wed Thu Fri'
+        weekmask of valid business days, passed to ``numpy.busdaycalendar``
+    holidays : list
+        list/array of dates to exclude from the set of valid business days,
+        passed to ``numpy.busdaycalendar``
+
+    Notes
+    -----
+    2 of start, end, or periods must be specified
+
+    Returns
+    -------
+    rng : DatetimeIndex
+    """
+
+    if freq=='C':
+        holidays = kwargs.pop('holidays', [])
+        weekmask = kwargs.pop('weekmask', 'Mon Tue Wed Thu Fri')
+        freq = CDay(holidays=holidays, weekmask=weekmask)
+    return DatetimeIndex(start=start, end=end, periods=periods, freq=freq,
+                         tz=tz, normalize=normalize, name=name, **kwargs)
+
+
 def _to_m8(key, tz=None):
     '''
     Timestamp-like => dt64

pandas/tseries/offsets.py

@@ -1,4 +1,5 @@
 from datetime import date, datetime, timedelta
+import numpy as np
 
 from pandas.tseries.tools import to_datetime
 
@@ -7,7 +8,7 @@
 import pandas.lib as lib
 import pandas.tslib as tslib
 
-__all__ = ['Day', 'BusinessDay', 'BDay',
+__all__ = ['Day', 'BusinessDay', 'BDay', 'CustomBusinessDay', 'CDay',
            'MonthBegin', 'BMonthBegin', 'MonthEnd', 'BMonthEnd',
            'YearBegin', 'BYearBegin', 'YearEnd', 'BYearEnd',
            'QuarterBegin', 'BQuarterBegin', 'QuarterEnd', 'BQuarterEnd',
@@ -100,7 +101,8 @@ def _should_cache(self):
 
     def _params(self):
         attrs = [(k, v) for k, v in vars(self).iteritems()
-                 if k not in ['kwds', '_offset', 'name', 'normalize']]
+                 if k not in ['kwds', '_offset', 'name', 'normalize',
+                 'busdaycalendar']]
         attrs.extend(self.kwds.items())
         attrs = sorted(set(attrs))
 
@@ -359,6 +361,115 @@ def onOffset(cls, dt):
         return dt.weekday() < 5
 
 
+class CustomBusinessDay(BusinessDay):
+    """
+    DateOffset subclass representing possibly n business days excluding
+    holidays
+
+    Parameters
+    ----------
+    n : int, default 1
+    offset : timedelta, default timedelta(0)
+    normalize : bool, default False
+        Normalize start/end dates to midnight before generating date range
+    weekmask : str, Default 'Mon Tue Wed Thu Fri'
+        weekmask of valid business days, passed to ``numpy.busdaycalendar``
+    holidays : list
+        list/array of dates to exclude from the set of valid business days,
+        passed to ``numpy.busdaycalendar``
+    """
+
+    _cacheable = False
+
+    def __init__(self, n=1, **kwds):
+        # Check we have the required numpy version
+        from distutils.version import LooseVersion
+        if LooseVersion(np.__version__) < '1.7.0':
+            raise ImportError("CustomBusinessDay requires numpy >= 1.7.0. "
+                              "Current version: "+np.__version__)
+
+        self.n = int(n)
+        self.kwds = kwds
+        self.offset = kwds.get('offset', timedelta(0))
+        self.normalize = kwds.get('normalize', False)
+        self.weekmask = kwds.get('weekmask', 'Mon Tue Wed Thu Fri')
+
+        holidays = kwds.get('holidays', [])
+        holidays = [self._to_dt64(dt, dtype='datetime64[D]') for dt in
+                    holidays]
+        self.holidays = tuple(sorted(holidays))
+        self.kwds['holidays'] = self.holidays
+        self._set_busdaycalendar()
+
+    def _set_busdaycalendar(self):
+        holidays = np.array(self.holidays, dtype='datetime64[D]')
+        self.busdaycalendar = np.busdaycalendar(holidays=holidays,
+                                                weekmask=self.weekmask)
+
+    def __getstate__(self):
+        """"Return a pickleable state"""
+        state = self.__dict__.copy()
+        del state['busdaycalendar']
+        return state
+
+    def __setstate__(self, state):
+        """Reconstruct an instance from a pickled state"""
+        self.__dict__ = state
+        self._set_busdaycalendar()
+
+    @property
+    def rule_code(self):
+        return 'C'
+
+    @staticmethod
+    def _to_dt64(dt, dtype='datetime64'):
+        if isinstance(dt, (datetime, basestring)):
+            dt = np.datetime64(dt, dtype=dtype)
+        if isinstance(dt, np.datetime64):
+            dt = dt.astype(dtype)
+        else:
+            raise TypeError('dt must be datestring, datetime or datetime64')
+        return dt
+
+    def apply(self, other):
+        if isinstance(other, datetime):
+            dtype = type(other)
+        elif isinstance(other, np.datetime64):
+            dtype = other.dtype
+        elif isinstance(other, (timedelta, Tick)):
+            return BDay(self.n, offset=self.offset + other,
+                        normalize=self.normalize)
+        else:
+            raise TypeError('Only know how to combine trading day with '
+                            'datetime, datetime64 or timedelta!')
+        dt64 = self._to_dt64(other)
+
+        day64 = dt64.astype('datetime64[D]')
+        time = dt64 - day64
+
+        if self.n<=0:
+            roll = 'forward'
+        else:
+            roll = 'backward'
+
+        result = np.busday_offset(day64, self.n, roll=roll,
+                                  busdaycal=self.busdaycalendar)
+
+        if not self.normalize:
+            result = result + time
+
+        result = result.astype(dtype)
+
+        if self.offset:
+            result = result + self.offset
+
+        return result
+
+    def onOffset(self, dt):
+        day64 = self._to_dt64(dt).astype('datetime64[D]')
+        return np.is_busday(day64, busdaycal=self.busdaycalendar)
+
+
 class MonthEnd(DateOffset, CacheableOffset):
     """DateOffset of one month end"""
 
@@ -1169,6 +1280,7 @@ class Nano(Tick):
 BDay = BusinessDay
 BMonthEnd = BusinessMonthEnd
 BMonthBegin = BusinessMonthBegin
+CDay = CustomBusinessDay
 
 
 def _get_firstbday(wkday):