rename epoch -> unix

Author: jreback

doc/source/timeseries.rst

@@ -252,7 +252,8 @@ Epoch Timestamps
 
 It's also possible to convert integer or float epoch times. The default unit
 for these is nanoseconds (since these are how ``Timestamp`` s are stored). However,
-often epochs are stored in another ``unit`` which can be specified:
+often epochs are stored in another ``unit`` which can be specified. These are computed
+from the starting point specified by the :ref:`Origin Parameter <timeseries.origin>`.
 
 Typical epoch stored units
 
@@ -276,6 +277,8 @@ These *work*, but the results may be unexpected.
 
    Epoch times will be rounded to the nearest nanosecond.
 
+.. _timeseries.origin:
+
 Using the Origin Parameter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -284,11 +287,14 @@ Using the Origin Parameter
 Using the ``origin`` parameter, one can specify an alternative starting point for creation
 of a ``DatetimeIndex``.
 
+Start with 1960-01-01 as the starting date
+
 .. ipython:: python
 
    pd.to_datetime([1, 2, 3], unit='D', origin=pd.Timestamp('1960-01-01'))
 
-The default is set at ``origin='epoch'``, which defaults to ``1970-01-01 00:00:00``.
+The default is set at ``origin='unix'``, which defaults to ``1970-01-01 00:00:00``.
+Commonly called 'unix epoch' or POSIX time.
 
 .. ipython:: python
 

doc/source/whatsnew/v0.20.0.txt

@@ -62,11 +62,14 @@ to_datetime has gained an origin parameter
 ``pd.to_datetime`` has gained a new parameter, ``origin``, to define an offset
 from where to compute the resulting ``DatetimeIndex``. (:issue:`11276`, :issue:`11745`)
 
+Start with 1960-01-01 as the starting date
+
 .. ipython:: python
 
    pd.to_datetime([1, 2, 3], unit='D', origin=pd.Timestamp('1960-01-01'))
 
-The default is set at ``origin='epoch'``, which defaults to ``1970-01-01 00:00:00``.
+The default is set at ``origin='unix'``, which defaults to ``1970-01-01 00:00:00``.
+Commonly called 'unix epoch' or POSIX time.
 
 .. ipython:: python
 

pandas/tests/indexes/datetimes/test_tools.py

@@ -1557,6 +1557,21 @@ def test_to_basic(self, julian_dates):
             julian_dates - pd.Timestamp(0).to_julian_date(), unit='D'))
         assert_series_equal(result, expected)
 
+        result = Series(pd.to_datetime(
+            [0, 1, 2], unit='D', origin='unix'))
+        expected = Series([Timestamp('1970-01-01'),
+                           Timestamp('1970-01-02'),
+                           Timestamp('1970-01-03')])
+        assert_series_equal(result, expected)
+
+        # default
+        result = Series(pd.to_datetime(
+            [0, 1, 2], unit='D'))
+        expected = Series([Timestamp('1970-01-01'),
+                           Timestamp('1970-01-02'),
+                           Timestamp('1970-01-03')])
+        assert_series_equal(result, expected)
+
     def test_invalid_unit(self, units, julian_dates):
 
         # checking for invalid combination of origin='julian' and unit != D
@@ -1575,8 +1590,9 @@ def test_epoch(self, units, epochs, epoch_1960, units_from_epochs):
 
     @pytest.mark.parametrize("origin, exc",
                              [('random_string', 'cannot be converted'),
+                              ('epoch', 'cannot be converted'),
                               ('13-24-1990', 'cannot be converted'),
-                              ('0001-01-01', 'Out of Bounds')])
+                              (datetime(1, 1, 1), 'Out of Bounds')])
     def test_invalid_origins(self, origin, exc, units, units_from_epochs):
 
         with tm.assertRaisesRegexp(ValueError, exc):

pandas/tseries/tools.py

@@ -177,7 +177,7 @@ def _guess_datetime_format_for_array(arr, **kwargs):
 
 def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
                 utc=None, box=True, format=None, exact=True,
-                unit=None, infer_datetime_format=False, origin='epoch'):
+                unit=None, infer_datetime_format=False, origin='unix'):
     """
     Convert argument to datetime.
 
@@ -229,19 +229,21 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
         - If False, allow the format to match anywhere in the target string.
 
     unit : string, default 'ns'
-        unit of the arg (D,s,ms,us,ns) denote the unit in epoch
-        (e.g. a unix timestamp), which is an integer/float number.
+        unit of the arg (D,s,ms,us,ns) denote the unit, which is an
+        integer or float number. This will be based off the origin.
+        Example, with unit='ms' and origin='unix' (the default), this
+        would calculate the number of milliseconds to the unix epoch start.
     infer_datetime_format : boolean, default False
         If True and no `format` is given, attempt to infer the format of the
         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'.
+    origin : scalar convertible to Timestamp / string ('julian', 'unix'),
+        default 'unix'.
         Define reference date. The numeric values would be parsed as number
         of units (defined by `unit`) since this reference date.
 
-        - If 'epoch', origin is set to 1970-01-01.
+        - If 'unix' (or POSIX) time; origin is set to 1970-01-01.
         - If 'julian', unit must be 'D', and origin is set to beginning of
           Julian Calendar. Julian day number 0 is assigned to the day starting
           at noon on January 1, 4713 BC.
@@ -454,7 +456,7 @@ def _convert_listlike(arg, box, format, name=None, tz=tz):
         result = _convert_listlike(np.array([arg]), box, format)[0]
 
     # handle origin
-    if origin not in ['epoch', 'julian']:
+    if origin not in ['unix', 'julian']:
         try:
             offset = tslib.Timestamp(origin) - tslib.Timestamp(0)
         except tslib.OutOfBoundsDatetime: