ENH: add top-level to_timedelta to convert string/integer based to timedeltas

Author: jreback

doc/source/io.rst

@@ -2017,6 +2017,10 @@ Beginning in 0.13.0, you can store and query using the ``timedelta64[ns]`` type.
 specified in the format: ``<float>(<unit>)``, where float may be signed (and fractional), and unit can be
 ``D,s,ms,us,ns`` for the timedelta. Here's an example:
 
+.. warning::
+
+   This requires ``numpy >= 1.7``
+
 .. ipython:: python
 
    from datetime import timedelta

doc/source/release.rst

@@ -191,7 +191,8 @@ API Changes
   - provide automatic dtype conversions on _reduce operations (:issue:`3371`)
   - exclude non-numerics if mixed types with datelike in _reduce operations (:issue:`3371`)
   - default for ``tupleize_cols`` is now ``False`` for both ``to_csv`` and ``read_csv``. Fair warning in 0.12 (:issue:`3604`)
-  - moved timedeltas support to pandas.tseries.timedeltas.py; add timedeltas string parsing
+  - moved timedeltas support to pandas.tseries.timedeltas.py; add timedeltas string parsing,
+    add top-level ``to_timedelta`` function
 
 Internal Refactoring
 ~~~~~~~~~~~~~~~~~~~~

doc/source/timeseries.rst

@@ -1211,6 +1211,26 @@ Time Deltas & Conversions
 
 .. versionadded:: 0.13
 
+**string/integer conversion**
+
+Using the top-level ``to_timedelta``, you can convert a scalar or array from the standard
+timedelta format (produced by ``to_csv``) into a timedelta type (``np.timedelta64`` in ``nanoseconds``).
+It can also construct Series.
+
+.. warning::
+
+   This requires ``numpy >= 1.7``
+
+.. ipython:: python
+
+   to_timedelta('1 days 06:05:01.00003')
+   to_timedelta('15.5us')
+   to_timedelta(['1 days 06:05:01.00003','15.5us','nan'])
+   to_timedelta(np.arange(5),unit='s')
+   to_timedelta(np.arange(5),unit='d')
+
+**frequency conversion**
+
 Timedeltas can be converted to other 'frequencies' by dividing by another timedelta.
 These operations yield ``float64`` dtyped Series.
 

doc/source/v0.13.0.txt

@@ -208,6 +208,21 @@ Enhancements
 
   - ``timedelta64[ns]`` operations
 
+    - Using the new top-level ``to_timedelta``, you can convert a scalar or array from the standard
+      timedelta format (produced by ``to_csv``) into a timedelta type (``np.timedelta64`` in ``nanoseconds``).
+
+      .. warning::
+
+         This requires ``numpy >= 1.7``
+
+      .. ipython:: python
+
+         to_timedelta('1 days 06:05:01.00003')
+         to_timedelta('15.5us')
+         to_timedelta(['1 days 06:05:01.00003','15.5us','nan'])
+         to_timedelta(np.arange(5),unit='s')
+         to_timedelta(np.arange(5),unit='d')
+
     - A Series of dtype ``timedelta64[ns]`` can now be divided by another
       ``timedelta64[ns]`` object to yield a ``float64`` dtyped Series. This
       is frequency conversion. See :ref:`here<timeseries.timedeltas_convert>` for the docs.

pandas/tseries/api.py

@@ -7,5 +7,6 @@
 from pandas.tseries.frequencies import infer_freq
 from pandas.tseries.period import Period, PeriodIndex, period_range, pnow
 from pandas.tseries.resample import TimeGrouper
+from pandas.tseries.timedeltas import to_timedelta
 from pandas.lib import NaT
 import pandas.tseries.offsets as offsets

pandas/tseries/tests/test_timedeltas.py

@@ -11,7 +11,7 @@
                     bdate_range, date_range, _np_version_under1p7)
 import pandas.core.common as com
 from pandas.compat import StringIO, lrange, range, zip, u, OrderedDict, long
-from pandas import compat
+from pandas import compat, to_timedelta, tslib
 from pandas.tseries.timedeltas import _coerce_scalar_to_timedelta_type as ct
 from pandas.util.testing import (assert_series_equal,
                                  assert_frame_equal,
@@ -33,10 +33,9 @@ def setUp(self):
     def test_numeric_conversions(self):
         _skip_if_numpy_not_friendly()
 
-        # ns not converted properly
         self.assert_(ct(0) == np.timedelta64(0,'ns'))
-        self.assert_(ct(10) == np.timedelta64(0,'ns'))
-        self.assert_(ct(10,unit='ns') == np.timedelta64(0,'ns').astype('m8[ns]'))
+        self.assert_(ct(10) == np.timedelta64(10,'ns'))
+        self.assert_(ct(10,unit='ns') == np.timedelta64(10,'ns').astype('m8[ns]'))
 
         self.assert_(ct(10,unit='us') == np.timedelta64(10,'us').astype('m8[ns]'))
         self.assert_(ct(10,unit='ms') == np.timedelta64(10,'ms').astype('m8[ns]'))
@@ -56,11 +55,10 @@ def test_short_format_converters(self):
         def conv(v):
             return v.astype('m8[ns]')
 
-        # ns not converted properly
-        self.assert_(ct('10') == np.timedelta64(0,'ns'))
-        self.assert_(ct('10ns') == np.timedelta64(0,'ns'))
-        self.assert_(ct('100') == np.timedelta64(0,'ns'))
-        self.assert_(ct('100ns') == np.timedelta64(0,'ns'))
+        self.assert_(ct('10') == np.timedelta64(10,'ns'))
+        self.assert_(ct('10ns') == np.timedelta64(10,'ns'))
+        self.assert_(ct('100') == np.timedelta64(100,'ns'))
+        self.assert_(ct('100ns') == np.timedelta64(100,'ns'))
 
         self.assert_(ct('1000') == np.timedelta64(1000,'ns'))
         self.assert_(ct('1000ns') == np.timedelta64(1000,'ns'))
@@ -122,6 +120,48 @@ def conv(v):
         # invalid
         self.assertRaises(ValueError, ct, '- 1days, 00')
 
+    def test_nat_converters(self):
+        _skip_if_numpy_not_friendly()
+
+        self.assert_(to_timedelta('nat') == tslib.iNaT)
+        self.assert_(to_timedelta('nan') == tslib.iNaT)
+
+    def test_to_timedelta(self):
+        _skip_if_numpy_not_friendly()
+
+        def conv(v):
+            return v.astype('m8[ns]')
+        d1 = np.timedelta64(1,'D')
+
+        self.assert_(to_timedelta('1 days 06:05:01.00003') == conv(d1+np.timedelta64(6*3600+5*60+1,'s')+np.timedelta64(30,'us')))
+        self.assert_(to_timedelta('15.5us') == conv(np.timedelta64(15500,'ns')))
+
+        # empty string
+        result = to_timedelta('')
+        self.assert_(result == tslib.iNaT)
+
+        result = to_timedelta(['', ''])
+        self.assert_(isnull(result).all())
+
+        # pass thru
+        result = to_timedelta(np.array([np.timedelta64(1,'s')]))
+        expected = np.array([np.timedelta64(1,'s')])
+        tm.assert_almost_equal(result,expected)
+
+        # ints
+        result = np.timedelta64(0,'ns')
+        expected = to_timedelta(0)
+        self.assert_(result == expected)
+
+        # Series
+        expected = Series([timedelta(days=1), timedelta(days=1, seconds=1)])
+        result = to_timedelta(Series(['1d','1days 00:00:01']))
+        tm.assert_series_equal(result, expected)
+
+        # with units
+        result = Series([ np.timedelta64(0,'ns'), np.timedelta64(10,'s').astype('m8[ns]') ],dtype='m8[ns]')
+        expected = to_timedelta([0,10],unit='s')
+        tm.assert_series_equal(result, expected)
 
 if __name__ == '__main__':
     nose.runmodule(argv=[__file__, '-vvs', '-x', '--pdb', '--pdb-failure'],

pandas/tseries/timedeltas.py

@@ -8,29 +8,86 @@
 import numpy as np
 import pandas.tslib as tslib
 from pandas import compat, _np_version_under1p7
-from pandas.core.common import (ABCSeries, is_integer,
+from pandas.core.common import (ABCSeries, is_integer, is_timedelta64_dtype,
                                 _values_from_object, is_list_like)
 
 repr_timedelta = tslib.repr_timedelta64
 repr_timedelta64 = tslib.repr_timedelta64
 
+def to_timedelta(arg, box=True, unit='ns'):
+    """
+    Convert argument to timedelta
+
+    Parameters
+    ----------
+    arg : string, timedelta, array of strings (with possible NAs)
+    box : boolean, default True
+        If True returns a Series of the results, if False returns ndarray of values
+    unit : unit of the arg (D,s,ms,us,ns) denote the unit, which is an integer/float number
+
+    Returns
+    -------
+    ret : timedelta64/arrays of timedelta64 if parsing succeeded
+    """
+    if _np_version_under1p7:
+        raise ValueError("to_timedelta is not support for numpy < 1.7")
+
+    def _convert_listlike(arg, box):
+
+        if isinstance(arg, (list,tuple)):
+            arg = np.array(arg, dtype='O')
+
+        if is_timedelta64_dtype(arg):
+            if box:
+                from pandas import Series
+                return Series(arg,dtype='m8[ns]')
+            return arg
+
+        value = np.array([ _coerce_scalar_to_timedelta_type(r, unit=unit) for r in arg ])
+        if box:
+            from pandas import Series
+            value = Series(value,dtype='m8[ns]')
+        return value
+
+    if arg is None:
+        return arg
+    elif isinstance(arg, ABCSeries):
+        from pandas import Series
+        values = _convert_listlike(arg.values, box=False)
+        return Series(values, index=arg.index, name=arg.name, dtype='m8[ns]')
+    elif is_list_like(arg):
+        return _convert_listlike(arg, box=box)
+
+    return _convert_listlike([ arg ], box=False)[0]
+
 _short_search = re.compile(
     "^\s*(?P<neg>-?)\s*(?P<value>\d*\.?\d*)\s*(?P<unit>d|s|ms|us|ns)?\s*$",re.IGNORECASE)
 _full_search = re.compile(
     "^\s*(?P<neg>-?)\s*(?P<days>\d+)?\s*(days|d)?,?\s*(?P<time>\d{2}:\d{2}:\d{2})?(?P<frac>\.\d+)?\s*$",re.IGNORECASE)
+_nat_search = re.compile(
+    "^\s*(nat|nan)\s*$",re.IGNORECASE)
+_whitespace = re.compile('^\s*$')
 
 def _coerce_scalar_to_timedelta_type(r, unit='ns'):
     # kludgy here until we have a timedelta scalar
     # handle the numpy < 1.7 case
 
+    def conv(v):
+        if _np_version_under1p7:
+            return timedelta(microseconds=v/1000.0)
+        return np.timedelta64(v)
+
     if isinstance(r, compat.string_types):
         converter = _get_string_converter(r, unit=unit)
         r = converter()
-        r = timedelta(microseconds=r/1000.0)
-
-    if is_integer(r):
+        r = conv(r)
+    elif r == tslib.iNaT:
+        return r
+    elif isinstance(r, np.timedelta64):
+        r = r.astype("m8[{0}]".format(unit.lower()))
+    elif is_integer(r):
         r = tslib.cast_from_unit(r, unit)
-        r = timedelta(microseconds=r/1000.0)
+        r = conv(r)
 
     if _np_version_under1p7:
         if not isinstance(r, timedelta):
@@ -50,6 +107,12 @@ def _coerce_scalar_to_timedelta_type(r, unit='ns'):
 def _get_string_converter(r, unit='ns'):
     """ return a string converter for r to process the timedelta format """
 
+    # treat as a nan
+    if _whitespace.search(r):
+        def convert(r=None, unit=None):
+            return tslib.iNaT
+        return convert
+
     m = _short_search.search(r)
     if m:
         def convert(r=None, unit=unit, m=m):
@@ -92,6 +155,12 @@ def convert(r=None, unit=None, m=m):
             return tslib.cast_from_unit(value, 's')
         return convert
 
+    m = _nat_search.search(r)
+    if m:
+        def convert(r=None, unit=None, m=m):
+            return tslib.iNaT
+        return convert
+
     # no converter
     raise ValueError("cannot create timedelta string converter")
 

pandas/tslib.pyx

@@ -1303,7 +1303,9 @@ cpdef inline int64_t cast_from_unit(object ts, object unit) except -1:
     # to avoid precision issues from float -> int
     base = <int64_t> ts
     frac = ts-base
-    return <int64_t> (base*m) + <int64_t> (round(frac,p)*m)
+    if p:
+       frac = round(frac,p)
+    return <int64_t> (base*m) + <int64_t> (frac*m)
 
 def cast_to_nanoseconds(ndarray arr):
     cdef: