pandas.to_numeric#

pandas.to_numeric(arg,errors='raise',downcast=None,dtype_backend=<no_default>)[source]#

Convert argument to a numeric type.

The default return dtype isfloat64 orint64depending on the data supplied. Use thedowncast parameterto obtain other dtypes.

Please note that precision loss may occur if really large numbersare passed in. Due to the internal limitations ofndarray, ifnumbers smaller than-9223372036854775808 (np.iinfo(np.int64).min)or larger than18446744073709551615 (np.iinfo(np.uint64).max) arepassed in, it is very likely they will be converted to float so thatthey can be stored in anndarray. These warnings apply similarly toSeries since it internally leveragesndarray.

Parameters:

argscalar, list, tuple, 1-d array, or Series

Argument to be converted.

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.

Changed in version 2.2.

“ignore” is deprecated. Catch exceptions explicitly instead.

downcaststr, default None

Can be ‘integer’, ‘signed’, ‘unsigned’, or ‘float’.If not None, and if the data has been successfully cast to anumerical dtype (or if the data was numeric to begin with),downcast that resulting data to the smallest numerical dtypepossible 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 tonumeric values, any errors raised during the downcastingwill be surfaced regardless of the value of the ‘errors’ input.

In addition, downcasting will only occur if the sizeof the resulting data’s dtype is strictly larger thanthe dtype it is to be cast to, so if none of the dtypeschecked satisfy that specification, no downcasting will beperformed on the data.

dtype_backend{‘numpy_nullable’, ‘pyarrow’}, default ‘numpy_nullable’

Back-end data type applied to the resultantDataFrame(still experimental). Behaviour is as follows:

• "numpy_nullable": returns nullable-dtype-backedDataFrame(default).

• "pyarrow": returns pyarrow-backed nullableArrowDtypeDataFrame.

Added in version 2.0.

Returns:

ret

Numeric if parsing succeeded.Return type depends on input. Series if Series, otherwise ndarray.

See also

DataFrame.astype

Cast argument to a specified dtype.

to_datetime

Convert argument to datetime.

to_timedelta

Convert argument to timedelta.

numpy.ndarray.astype

Cast a numpy array to a specified type.

DataFrame.convert_dtypes

Convert dtypes.

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.01    2.02   -3.0dtype: float64>>>pd.to_numeric(s,downcast='float')0    1.01    2.02   -3.0dtype: float32>>>pd.to_numeric(s,downcast='signed')0    11    22   -3dtype: int8>>>s=pd.Series(['apple','1.0','2',-3])>>>pd.to_numeric(s,errors='coerce')0    NaN1    1.02    2.03   -3.0dtype: float64

Downcasting of nullable integer and floating dtypes is supported:

>>>s=pd.Series([1,2,3],dtype="Int64")>>>pd.to_numeric(s,downcast="integer")0    11    22    3dtype: Int8>>>s=pd.Series([1.0,2.1,3.0],dtype="Float64")>>>pd.to_numeric(s,downcast="float")0    1.01    2.12    3.0dtype: Float32