ENH: Added parameter origin to to_datetime

closes pandas-dev#11276
closes pandas-dev#11745
closes pandas-dev#11470

Author: sumitbinnani

doc/source/whatsnew/v0.18.1.txt

@@ -221,6 +221,8 @@ Other Enhancements
 - Added ``.weekday_name`` property as a component to ``DatetimeIndex`` and the ``.dt`` accessor. (:issue:`11128`)
 
 - ``Index.take`` now handles ``allow_fill`` and ``fill_value`` consistently (:issue:`12631`)
+- Added ``weekday_name`` as a component to ``DatetimeIndex`` and ``.dt`` accessor. (:issue:`11128`)
+- ``pd.to_datetime`` has a new parameter, ``origin``, to define an offset for ``DatetimeIndex`` (:issue:`11276`, :issue:`11745`)
 
   .. ipython:: python
 

pandas/tseries/tests/test_timeseries.py

@@ -752,6 +752,48 @@ def test_to_datetime_unit(self):
             seconds=t) for t in range(20)] + [NaT])
         assert_series_equal(result, expected)
 
+    def test_to_datetime_origin(self):
+        units = ['D', 's', 'ms', 'us', 'ns']
+        # Addresses Issue Number 11276, 11745
+        # for origin as julian
+        julian_dates = pd.date_range(
+            '2014-1-1', periods=10).to_julian_date().values
+        result = Series(pd.to_datetime(
+            julian_dates, unit='D', origin='julian'))
+        expected = Series(pd.to_datetime(
+            julian_dates - pd.Timestamp(0).to_julian_date(), unit='D'))
+        assert_series_equal(result, expected)
+
+        # checking for invalid combination of origin='julian' and unit != D
+        for unit in units:
+            if unit == 'D':
+                continue
+            with self.assertRaises(ValueError):
+                pd.to_datetime(julian_dates, unit=unit, origin='julian')
+
+        # for origin as 1960-01-01
+        epoch_1960 = pd.Timestamp('1960-01-01')
+        epoch_timestamp_convertible = [epoch_1960, epoch_1960.to_datetime(
+        ), epoch_1960.to_datetime64(), str(epoch_1960)]
+        units = ['D', 's', 'ms', 'us', 'ns']
+        invalid_origins = ['random_string', '13-24-1990']
+        units_from_epoch = range(5)
+
+        for unit in units:
+            for epoch in epoch_timestamp_convertible:
+                expected = Series(
+                    [pd.Timedelta(x, unit=unit) +
+                     epoch_1960 for x in units_from_epoch])
+                result = Series(pd.to_datetime(
+                    units_from_epoch, unit=unit, origin=epoch))
+                assert_series_equal(result, expected)
+
+            # check for invalid origins
+            for origin in invalid_origins:
+                with self.assertRaises(ValueError):
+                    pd.to_datetime(units_from_epoch, unit=unit,
+                                   origin=origin)
+
     def test_series_ctor_datetime64(self):
         rng = date_range('1/1/2000 00:00:00', '1/1/2000 1:59:50', freq='10s')
         dates = np.asarray(rng)

pandas/tseries/tools.py

@@ -170,7 +170,7 @@ def _guess_datetime_format_for_array(arr, **kwargs):
                  mapping={True: 'coerce', False: 'raise'})
 def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
                 utc=None, box=True, format=None, exact=True, coerce=None,
-                unit=None, infer_datetime_format=False):
+                unit=None, infer_datetime_format=False, origin='epoch'):
     """
     Convert argument to datetime.
 
@@ -228,6 +228,17 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
         datetime strings, and if it can be inferred, switch to a faster
         method of parsing them. In some cases this can increase the parsing
         speed by ~5-10x.
+    origin : scalar convertible to Timestamp / string ('julian', 'epoch'),
+        default 'epoch'.
+        Define relative offset for the returned dates.
+
+        - If 'epoch', offset is set to 1-1-1970.
+        - If 'julian', unit must be 'D', and offset is set to beginning of
+          Julian Calendar.
+        - If Timestamp convertible, offset is set to Timestamp identified by
+          origin.
+
+        .. versionadded: 0.18.1
 
     Returns
     -------
@@ -260,6 +271,14 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
     If a date that does not meet timestamp limitations, passing errors='coerce'
     will force to NaT. Furthermore this will force non-dates to NaT as well.
 
+    >>> pd.to_datetime(range(100), unit='D', origin=Timestamp('1960-01-01'))
+    0    1960-01-01
+    1    1960-01-02
+    ...
+    98   1960-04-08
+    99   1960-04-09
+
+
     >>> pd.to_datetime('13000101', format='%Y%m%d')
     datetime.datetime(1300, 1, 1, 0, 0)
     >>> pd.to_datetime('13000101', format='%Y%m%d', errors='coerce')
@@ -285,10 +304,25 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
     1 loop, best of 3: 471 ms per loop
 
     """
-    return _to_datetime(arg, errors=errors, dayfirst=dayfirst,
-                        yearfirst=yearfirst,
-                        utc=utc, box=box, format=format, exact=exact,
-                        unit=unit, infer_datetime_format=infer_datetime_format)
+    # variable to set offset as per origin parameter
+    offset = None
+
+    if origin == 'julian':
+        if unit != 'D':
+            raise ValueError("unit must be 'D' for origin='julian'")
+        arg = arg - tslib.Timestamp(0).to_julian_date()
+    elif origin != 'epoch':
+        offset = tslib.Timestamp(origin) - tslib.Timestamp(0)
+
+    result = _to_datetime(arg, errors=errors, dayfirst=dayfirst,
+                          yearfirst=yearfirst, utc=utc, box=box, format=format,
+                          exact=exact, unit=unit,
+                          infer_datetime_format=infer_datetime_format)
+
+    if offset is not None:
+        result = result + offset
+
+    return result
 
 
 def _to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,