ENH: Add BusinessHour offset

Author: sinhrks

doc/source/timeseries.rst

@@ -4,7 +4,7 @@
 .. ipython:: python
    :suppress:
 
-   from datetime import datetime, timedelta
+   from datetime import datetime, timedelta, time
    import numpy as np
    np.random.seed(123456)
    from pandas import *
@@ -482,11 +482,13 @@ frequency increment. Specific offset logic like "month", "business day", or
     BYearEnd, "business year end"
     BYearBegin, "business year begin"
     FY5253, "retail (aka 52-53 week) year"
+    BusinessHour, "business hour"
     Hour, "one hour"
     Minute, "one minute"
     Second, "one second"
     Milli, "one millisecond"
     Micro, "one microsecond"
+    Nano, "one nanosecond"
 
 
 The basic ``DateOffset`` takes the same arguments as
@@ -667,6 +669,102 @@ in the usual way.
     have to change to fix the timezone issues, the behaviour of the
     ``CustomBusinessDay`` class may have to change in future versions.
 
+.. _timeseries.businesshour:
+
+Business Hour
+~~~~~~~~~~~~~
+
+The ``BusinessHour`` class provides a business hour representation on ``BusinessDay``,
+allowing to use specific start and end times.
+
+By default, ``BusinessHour`` uses 9:00 - 17:00 as business hours.
+Adding ``BusinessHour`` will increment ``Timestamp`` by hourly.
+If target ``Timestamp`` is out of business hours, move to the next business hour then increment it.
+If the result exceeds the business hours end, remaining is added to the next business day.
+
+.. ipython:: python
+
+    bh = BusinessHour()
+    bh
+
+    # 2014-08-01 is Friday
+    Timestamp('2014-08-01 10:00').weekday()
+    Timestamp('2014-08-01 10:00') + bh
+
+    # Below example is the same as Timestamp('2014-08-01 09:00') + bh
+    Timestamp('2014-08-01 08:00') + bh
+
+    # If the results is on the end time, move to the next business day
+    Timestamp('2014-08-01 16:00') + bh
+
+    # Remainings are added to the next day
+    Timestamp('2014-08-01 16:30') + bh
+
+    # Adding 2 business hours
+    Timestamp('2014-08-01 10:00') + BusinessHour(2)
+
+    # Subtracting 3 business hours
+    Timestamp('2014-08-01 10:00') + BusinessHour(-3)
+
+Also, you can specify ``start`` and ``end`` time by keywords.
+Argument must be ``str`` which has ``hour:minute`` representation or ``datetime.time`` instance.
+Specifying seconds, microseconds and nanoseconds as business hour results in ``ValueError``.
+
+.. ipython:: python
+
+    bh = BusinessHour(start='11:00', end=time(20, 0))
+    bh
+
+    Timestamp('2014-08-01 13:00') + bh
+    Timestamp('2014-08-01 09:00') + bh
+    Timestamp('2014-08-01 18:00') + bh
+
+Passing ``start`` time later than ``end`` represents midnight business hour.
+In this case, business hour exceeds midnight and overlap to the next day.
+Valid business hours are distinguished by whether it started from valid ``BusinessDay``.
+
+.. ipython:: python
+
+    bh = BusinessHour(start='17:00', end='09:00')
+    bh
+
+    Timestamp('2014-08-01 17:00') + bh
+    Timestamp('2014-08-01 23:00') + bh
+
+    # Although 2014-08-02 is Satuaday,
+    # it is valid because it starts from 08-01 (Friday).
+    Timestamp('2014-08-02 04:00') + bh
+
+    # Although 2014-08-04 is Monday,
+    # it is out of business hours because it starts from 08-03 (Sunday).
+    Timestamp('2014-08-04 04:00') + bh
+
+Applying ``BusinessHour.rollforward`` and ``rollback`` to out of business hours results in
+the next business hour start or previous day's end. Different from other offsets, ``BusinessHour.rollforward``
+may output different results from ``apply`` by definition.
+
+This is because one day's business hour end is equal to next day's business hour start. For example,
+under the default business hours (9:00 - 17:00), there is no gap (0 minutes) between ``2014-08-01 17:00`` and
+``2014-08-04 09:00``.
+
+.. ipython:: python
+
+    # This adjusts a Timestamp to business hour edge
+    BusinessHour().rollback(Timestamp('2014-08-02 15:00'))
+    BusinessHour().rollforward(Timestamp('2014-08-02 15:00'))
+
+    # It is the same as BusinessHour().apply(Timestamp('2014-08-01 17:00')).
+    # And it is the same as BusinessHour().apply(Timestamp('2014-08-04 09:00'))
+    BusinessHour().apply(Timestamp('2014-08-02 15:00'))
+
+    # BusinessDay results (for reference)
+    BusinessHour().rollforward(Timestamp('2014-08-02'))
+
+    # It is the same as BusinessDay().apply(Timestamp('2014-08-01'))
+    # The result is the same as rollworward because BusinessDay never overlap.
+    BusinessHour().apply(Timestamp('2014-08-02'))
+
+
 Offset Aliases
 ~~~~~~~~~~~~~~
 
@@ -696,6 +794,7 @@ frequencies. We will refer to these aliases as *offset aliases*
     "BA", "business year end frequency"
     "AS", "year start frequency"
     "BAS", "business year start frequency"
+    "BH", "business hour frequency"
     "H", "hourly frequency"
     "T", "minutely frequency"
     "S", "secondly frequency"

doc/source/v0.15.0.txt

@@ -19,6 +19,8 @@ users upgrade to this version.
   - Internal refactoring of the ``Index`` class to no longer sub-class ``ndarray``, see :ref:`Internal Refactoring <whatsnew_0150.refactoring>`
   - New datetimelike properties accessor ``.dt`` for Series, see :ref:`Datetimelike Properties <whatsnew_0150.dt>`
   - dropping support for ``PyTables`` less than version 3.0.0, and ``numexpr`` less than version 2.1 (:issue:`7990`)
+  - New datetimelike properties accessor ``.dt`` for Series, see :ref:`Dateimelike Properties <whatsnew_0150.dt>`
+  - ``BusinessHour`` offset is supported, see :ref:`here <timeseries.businesshour>`
 
 - :ref:`Other Enhancements <whatsnew_0150.enhancements>`
 
@@ -174,6 +176,7 @@ API changes
   for localizing a specific level of a MultiIndex (:issue:`7846`)
 
 - ``Timestamp.__repr__`` displays ``dateutil.tz.tzoffset`` info (:issue:`7907`)
+
 - ``merge``, ``DataFrame.merge``, and ``ordered_merge`` now return the same type
   as the ``left`` argument.  (:issue:`7737`)
 
@@ -232,6 +235,14 @@ API changes
      idx.duplicated()
      idx.drop_duplicates()
 
+- ``BusinessHour`` offset is now supported, which represents business hours starting from 09:00 - 17:00 on ``BusinessDay`` by default. See :ref:`Here <timeseries.businesshour>` for details. (:issue:`7905`)
+
+  .. ipython:: python
+
+     Timestamp('2014-08-01 09:00') + BusinessHour()
+     Timestamp('2014-08-01 07:00') + BusinessHour()
+     Timestamp('2014-08-01 16:30') + BusinessHour()
+
 .. _whatsnew_0150.dt:
 
 .dt accessor

pandas/tseries/frequencies.py

@@ -718,13 +718,12 @@ def get_freq(self):
         delta = self.deltas[0]
         if _is_multiple(delta, _ONE_DAY):
             return self._infer_daily_rule()
+        elif _is_multiple(delta, _ONE_HOUR):
+            return self._infer_hourly_rule()
         else:
             # Possibly intraday frequency
             if not self.is_unique:
                 return None
-            if _is_multiple(delta, _ONE_HOUR):
-                # Hours
-                return _maybe_add_count('H', delta / _ONE_HOUR)
             elif _is_multiple(delta, _ONE_MINUTE):
                 # Minutes
                 return _maybe_add_count('T', delta / _ONE_MINUTE)
@@ -745,6 +744,10 @@ def get_freq(self):
     def day_deltas(self):
         return [x / _ONE_DAY for x in self.deltas]
 
+    @cache_readonly
+    def hour_deltas(self):
+        return [x / _ONE_HOUR for x in self.deltas]
+
     @cache_readonly
     def fields(self):
         return tslib.build_field_sarray(self.values)
@@ -840,6 +843,14 @@ def _infer_daily_rule(self):
         if wom_rule:
             return wom_rule
 
+    def _infer_hourly_rule(self):
+        # Business hourly, maybe. 17: one day / 65: one weekend
+        if self.hour_deltas in ([1, 17], [1, 65], [1, 17, 65]):
+            return 'BH'
+        elif not self.is_unique:
+            return None
+        return _maybe_add_count('H', self.deltas[0] / _ONE_HOUR)
+
     def _get_annual_rule(self):
         if len(self.ydiffs) > 1:
             return None