pandas.to_numeric

pandas.to_numeric(arg, errors='raise', downcast=None)[source]

Convert argument to a numeric type.

The default return dtype is float64 or int64 depending on the data supplied. Use the downcast parameter to obtain other dtypes.

Parameters:
arg : list, tuple, 1-d array, or Series
errors : {‘ignore’, ‘raise’, ‘coerce’}, default ‘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 : {‘integer’, ‘signed’, ‘unsigned’, ‘float’} , default None

If not None, and if the data has been successfully cast to a numerical dtype (or if the data was numeric to begin with), downcast that resulting data to the smallest numerical dtype possible according to the following rules:

  • ‘integer’ or ‘signed’: smallest signed int dtype (min.: np.int8)
  • ‘unsigned’: smallest unsigned int dtype (min.: np.uint8)
  • ‘float’: smallest float dtype (min.: np.float32)

As this behaviour is separate from the core conversion to numeric values, any errors raised during the downcasting will be surfaced regardless of the value of the ‘errors’ input.

In addition, downcasting will only occur if the size of the resulting data’s dtype is strictly larger than the dtype it is to be cast to, so if none of the dtypes checked satisfy that specification, no downcasting will be performed on the data.

New in version 0.19.0.

Returns:
ret : numeric if parsing succeeded.

Return type depends on input. Series if Series, otherwise ndarray

See also

pandas.DataFrame.astype
Cast argument to a specified dtype.
pandas.to_datetime
Convert argument to datetime.
pandas.to_timedelta
Convert argument to timedelta.
numpy.ndarray.astype
Cast a numpy array to a specified type.

Examples

Take separate series and convert to numeric, coercing when told to

>>> s = pd.Series(['1.0', '2', -3])
>>> pd.to_numeric(s)
0    1.0
1    2.0
2   -3.0
dtype: float64
>>> pd.to_numeric(s, downcast='float')
0    1.0
1    2.0
2   -3.0
dtype: float32
>>> pd.to_numeric(s, downcast='signed')
0    1
1    2
2   -3
dtype: int8
>>> s = pd.Series(['apple', '1.0', '2', -3])
>>> pd.to_numeric(s, errors='ignore')
0    apple
1      1.0
2        2
3       -3
dtype: object
>>> pd.to_numeric(s, errors='coerce')
0    NaN
1    1.0
2    2.0
3   -3.0
dtype: float64
Scroll To Top