to_numeric(arg, errors='raise', downcast=None)

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

Please note that precision loss may occur if really large numbers are passed in. Due to the internal limitations of :None:None:`ndarray`, if numbers smaller than :None:None:`-9223372036854775808` (np.iinfo(np.int64).min) or larger than :None:None:`18446744073709551615` (np.iinfo(np.uint64).max) are passed in, it is very likely they will be converted to float so that they can stored in an :None:None:`ndarray`. These warnings apply similarly to Series since it internally leverages :None:None:`ndarray`.

Parameters

arg : scalar, 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.

downcast : str, default None

Can be 'integer', 'signed', 'unsigned', or 'float'. 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.

Returns

ret

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

Convert argument to a numeric type.

See Also

DataFrame.astype

Cast argument to a specified dtype.

DataFrame.convert_dtypes

Convert dtypes.

numpy.ndarray.astype

Cast a numpy array to a specified type.

to_datetime

Convert argument to datetime.

to_timedelta

Convert argument to timedelta.

Examples

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

This example is valid syntax, but we were not able to check execution

>>> s = pd.Series(['1.0', '2', -3])
... pd.to_numeric(s)
0    1.0
1    2.0
2   -3.0
dtype: float64

This example is valid syntax, but we were not able to check execution

>>> pd.to_numeric(s, downcast='float')
0    1.0
1    2.0
2   -3.0
dtype: float32

This example is valid syntax, but we were not able to check execution

>>> pd.to_numeric(s, downcast='signed')
0    1
1    2
2   -3
dtype: int8

This example is valid syntax, but we were not able to check execution

>>> 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

This example is valid syntax, but we were not able to check execution

>>> pd.to_numeric(s, errors='coerce')
0    NaN
1    1.0
2    2.0
3   -3.0
dtype: float64

Downcasting of nullable integer and floating dtypes is supported:

This example is valid syntax, but we were not able to check execution

>>> s = pd.Series([1, 2, 3], dtype="Int64")
... pd.to_numeric(s, downcast="integer")
0    1
1    2
2    3
dtype: Int8

This example is valid syntax, but we were not able to check execution

>>> s = pd.Series([1.0, 2.1, 3.0], dtype="Float64")
... pd.to_numeric(s, downcast="float")
0    1.0
1    2.1
2    3.0
dtype: Float32

See :

Back References

The following pages refer to to this document either explicitly or contain code examples using this.

pandas.core.generic.NDFrame.astype pandas.core.generic.NDFrame.infer_objects pandas.core.generic.NDFrame.convert_dtypes

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them

---

File: /pandas/core/tools/numeric.py#27
type: <class 'function'>
Commit: