ENH: add 'downcast' to pd.to_numeric

Closes pandas-devgh-13352.

Author: gfyoung

asv_bench/benchmarks/inference.py

@@ -135,4 +135,25 @@ def setup(self):
         self.df_timedelta64 = DataFrame(dict(A=(self.df_datetime64['A'] - self.df_datetime64['B']), B=self.df_datetime64['B']))
 
     def time_dtype_infer_uint32(self):
-        (self.df_uint32['A'] + self.df_uint32['B'])
+        (self.df_uint32['A'] + self.df_uint32['B'])
+
+
+class to_numeric(object):
+    N = 500000
+
+    param_names = ['data', 'dtype']
+    params = [
+        [(['1'] * N / 2) + ([2] * N / 2),
+         (['-1'] * N / 2) + ([2] * N / 2),
+         np.repeat(np.array('1970-01-01', '1970-01-02',
+                            dtype='datetime64[D]'), N),
+         (['1.1'] * N / 2) + ([2] * N / 2),
+         ([1] * N / 2) + ([2] * N / 2),
+         np.repeat(np.int32(1), N)],
+        ['int64', 'uint64', 'int32', 'uint32',
+         'int16', 'uint16', 'int8', 'uint8',
+         'float64', 'float32', float, int],
+    ]
+
+    def time_to_numeric(self, data, dtype):
+        pd.to_numeric(data, downcast=dtype)

doc/source/whatsnew/v0.18.2.txt

@@ -186,6 +186,12 @@ Other enhancements
 ^^^^^^^^^^^^^^^^^^
 
 - The ``.tz_localize()`` method of ``DatetimeIndex`` and ``Timestamp`` has gained the ``errors`` keyword, so you can potentially coerce nonexistent timestamps to ``NaT``. The default behaviour remains to raising a ``NonExistentTimeError`` (:issue:`13057`)
+- ``pd.to_numeric()`` now accepts a ``downcast`` parameter (:issue:`13352`)
+
+  .. ipython:: python
+
+     s = ['1', 2, 3]
+     pd.to_numeric(s, downcast=np.int8)
 
 - ``Index`` now supports ``.str.extractall()`` which returns a ``DataFrame``, see :ref:`documentation here <text.extractall>` (:issue:`10008`, :issue:`13156`)
 - ``.to_hdf/read_hdf()`` now accept path objects (e.g. ``pathlib.Path``, ``py.path.local``) for the file path (:issue:`11773`)

pandas/tools/tests/test_util.py

@@ -291,6 +291,59 @@ def test_non_hashable(self):
         with self.assertRaisesRegexp(TypeError, "Invalid object type"):
             pd.to_numeric(s)
 
+    def test_downcast(self):
+        mixed_data = ['1', 2, 3]
+        int_data = [1, 2, 3]
+        date_data = np.array(['1970-01-02', '1970-01-03',
+                              '1970-01-04'], dtype='datetime64[D]')
+
+        smaller_dtypes = [np.int8, np.uint8, np.int16, np.uint16,
+                          np.int32, np.uint32, np.float32]
+
+        larger_dtypes = [np.int64, np.uint64, np.float64]
+
+        msg = "'downcast' must be a numerical dtype"
+        bad_dtype = 'datetime64[D]'
+
+        for data in [mixed_data, int_data, date_data]:
+            tm.assertRaisesRegexp(ValueError, msg, pd.to_numeric,
+                                  data, downcast=bad_dtype)
+
+            for smaller_dtype in smaller_dtypes:
+                res = pd.to_numeric(data, downcast=smaller_dtype)
+                expected = np.array([1, 2, 3], dtype=smaller_dtype)
+                tm.assert_numpy_array_equal(res, expected)
+
+            expected = np.array([1, 2, 3], dtype=np.int64)
+
+            # default
+            res = pd.to_numeric(data)
+            tm.assert_numpy_array_equal(res, expected)
+
+            # explicit
+            res = pd.to_numeric(data, downcast=None)
+            tm.assert_numpy_array_equal(res, expected)
+
+            for larger_dtype in larger_dtypes:
+                res = pd.to_numeric(data, downcast=larger_dtype)
+                tm.assert_numpy_array_equal(res, expected)
+
+        # cannot downcast because it is the wrong type
+        data = ['-1', 2, 3]
+        res = pd.to_numeric(data, downcast=np.uint8)
+        expected = np.array([-1, 2, 3], dtype=np.int64)
+        tm.assert_numpy_array_equal(res, expected)
+
+        # ensure behaviour is respected when values are of
+        # different integer dtypes (i.e. not 'np.int')
+        data = np.array([1, 2, 3], dtype=np.int16)
+
+        res = pd.to_numeric(data, downcast=np.int16)
+        tm.assert_numpy_array_equal(res, data)
+
+        expected = np.array([1, 2, 3], dtype=np.uint8)
+        res = pd.to_numeric(data, downcast=np.uint8)
+        tm.assert_numpy_array_equal(res, expected)
 
 if __name__ == '__main__':
     nose.runmodule(argv=[__file__, '-vvs', '-x', '--pdb', '--pdb-failure'],

pandas/tools/util.py

@@ -50,7 +50,7 @@ def compose(*funcs):
     return reduce(_compose2, funcs)
 
 
-def to_numeric(arg, errors='raise'):
+def to_numeric(arg, errors='raise', downcast=None):
     """
     Convert argument to a numeric type.
 
@@ -61,6 +61,13 @@ def to_numeric(arg, errors='raise'):
         - If 'raise', then invalid parsing will raise an exception
         - If 'coerce', then invalid parsing will be set as NaN
         - If 'ignore', then invalid parsing will return the input
+    downcast : numpy.dtype or Python dtype, default None
+        If possible, downcast the resulting numerical data to the
+        specified **numerical** dtype in 'downcast'. If the size of
+        the data's dtype is smaller or equal to that of 'downcast',
+        then this parameter will be ignored.
+
+        .. versionadded:: 0.18.2
 
     Returns
     -------
@@ -74,6 +81,7 @@ def to_numeric(arg, errors='raise'):
     >>> import pandas as pd
     >>> s = pd.Series(['1.0', '2', -3])
     >>> pd.to_numeric(s)
+    >>> pd.to_numeric(s, downcast=np.int8)
     >>> s = pd.Series(['apple', '1.0', '2', -3])
     >>> pd.to_numeric(s, errors='ignore')
     >>> pd.to_numeric(s, errors='coerce')
@@ -102,20 +110,29 @@ def to_numeric(arg, errors='raise'):
     else:
         values = arg
 
-    if com.is_numeric_dtype(values):
-        pass
-    elif com.is_datetime_or_timedelta_dtype(values):
-        values = values.astype(np.int64)
-    else:
-        values = com._ensure_object(values)
-        coerce_numeric = False if errors in ('ignore', 'raise') else True
+    try:
+        if com.is_numeric_dtype(values):
+            pass
+        elif com.is_datetime_or_timedelta_dtype(values):
+            values = values.astype(np.int64)
+        else:
+            values = com._ensure_object(values)
+            coerce_numeric = False if errors in ('ignore', 'raise') else True
 
-        try:
             values = lib.maybe_convert_numeric(values, set(),
                                                coerce_numeric=coerce_numeric)
-        except:
-            if errors == 'raise':
-                raise
+
+        if downcast is not None:
+            dtype = np.dtype(downcast)
+            if not com.is_numeric_dtype(dtype):
+                raise ValueError("'downcast' must be a numerical dtype")
+
+            if values.dtype.itemsize > dtype.itemsize:
+                values = com._possibly_downcast_to_dtype(values, dtype)
+
+    except Exception:
+        if errors == 'raise':
+            raise
 
     if is_series:
         return pd.Series(values, index=arg.index, name=arg.name)