pandas.DataFrame.convert_dtypes#

DataFrame.convert_dtypes(infer_objects=<no_default>, convert_string=<no_default>, convert_integer=<no_default>, convert_boolean=<no_default>, convert_floating=<no_default>, dtype_backend='numpy_nullable')[source]#

Convert columns from numpy dtypes to the best dtypes that support pd.NA.

This finds the smallest dtype that can hold all values, or uses extension dtypes (e.g. nullable integer, string, boolean) so that missing values are represented by pd.NA instead of np.nan.

Parameters:

infer_objectsbool, default True

Whether object dtypes should be converted to the best possible types.

Deprecated since version 3.1.0: The infer_objects keyword is deprecated and will be removed in a future version.

convert_stringbool, default True

Whether object dtypes should be converted to StringDtype().

Deprecated since version 3.1.0: The convert_string keyword is deprecated and will be removed in a future version.

convert_integerbool, default True

Whether, if possible, conversion can be done to integer extension types.

Deprecated since version 3.1.0: The convert_integer keyword is deprecated and will be removed in a future version.

convert_booleanbool, defaults True

Whether object dtypes should be converted to BooleanDtypes().

Deprecated since version 3.1.0: The convert_boolean keyword is deprecated and will be removed in a future version.

convert_floatingbool, defaults True

Whether, if possible, conversion can be done to floating extension types. If convert_integer is also True, preference will be give to integer dtypes if the floats can be faithfully casted to integers.

Deprecated since version 3.1.0: The convert_floating keyword is deprecated and will be removed in a future version.

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

Back-end data type applied to the resultant DataFrame or Series (still experimental). Behaviour is as follows:

"numpy_nullable": returns nullable-dtype-backed DataFrame or Series.
"pyarrow": returns pyarrow-backed nullable ArrowDtype DataFrame or Series.

Added in version 2.0.

Returns:

Series or DataFrame: Copy of input object with new dtype.

See also

infer_objects: Infer dtypes of objects.
to_datetime: Convert argument to datetime.
to_timedelta: Convert argument to timedelta.
to_numeric: Convert argument to a numeric type.

Notes

By default, convert_dtypes will attempt to convert a Series (or each Series in a DataFrame) to dtypes that support pd.NA. By using the options convert_string, convert_integer, convert_boolean and convert_floating, it is possible to turn off individual conversions to StringDtype, the integer extension types, BooleanDtype or floating extension types, respectively.

For object-dtyped columns, if infer_objects is True, use the inference rules as during normal Series/DataFrame construction. Then, if possible, convert to StringDtype, BooleanDtype or an appropriate integer or floating extension type, otherwise leave as object.

If the dtype is integer, convert to an appropriate integer extension type.

If the dtype is numeric, and consists of all integers, convert to an appropriate integer extension type. Otherwise, convert to an appropriate floating extension type.

In the future, as new dtypes are added that support pd.NA, the results of this method will change to support those new dtypes.

Examples

>>> df = pd.DataFrame(
...     {
...         "a": pd.Series([1, 2, 3], dtype=np.dtype("int32")),
...         "b": pd.Series(["x", "y", "z"], dtype=np.dtype("O")),
...         "c": pd.Series([True, False, np.nan], dtype=np.dtype("O")),
...         "d": pd.Series(["h", "i", np.nan], dtype=np.dtype("O")),
...         "e": pd.Series([10, np.nan, 20], dtype=np.dtype("float")),
...         "f": pd.Series([np.nan, 100.5, 200], dtype=np.dtype("float")),
...     }
... )

Start with a DataFrame with default dtypes.

>>> df
   a  b      c    d     e      f
0  1  x   True    h  10.0    NaN
1  2  y  False    i   NaN  100.5
2  3  z    NaN  NaN  20.0  200.0

>>> df.dtypes
a      int32
b     object
c     object
d     object
e    float64
f    float64
dtype: object

Convert the DataFrame to use best possible dtypes.

>>> dfn = df.convert_dtypes()
>>> dfn
   a  b      c     d     e      f
0  1  x   True     h    10   <NA>
1  2  y  False     i  <NA>  100.5
2  3  z   <NA>  <NA>    20  200.0

>>> dfn.dtypes
a      Int32
b     string
c    boolean
d     string
e      Int64
f    Float64
dtype: object

Start with a Series of strings and missing data represented by np.nan.

>>> s = pd.Series(["a", "b", np.nan])
>>> s
0      a
1      b
2    NaN
dtype: str

Obtain a Series with dtype StringDtype.

>>> s.convert_dtypes()
0       a
1       b
2    <NA>
dtype: string