downcast_numeric_columns¶

pyhelpers.ops.downcast_numeric_columns(*data, return_copy=True)[source]¶

Downcast numeric types in pandas or polars DataFrames and Series to their optimal sizes.

This function processes multiple objects in one pass, converting integer columns to the smallest signed integer dtype (e.g. int8, int16) and floating-point columns to the smallest floating dtype (e.g. float16, float32) that can safely represent their values without data loss.

Parameters:

data (pandas.DataFrame | pandas.Series | polars.DataFrame | polars.Series) – One or more pandas or polars DataFrames/Series to optimize.
return_copy (bool) – Whether to return a copy or modify the input in-place (where possible). Defaults to True.

Returns:

New DataFrame(s) or Series with downcasted numeric columns.

Return type:

Note

Non-numeric and timedelta columns are automatically skipped.
For polars, operations are inherently out-of-place, so return_copy=False primarily avoids an explicit early clone, but structural changes still yield new objects.

Examples:

>>> from pyhelpers.ops import downcast_numeric_columns
>>> from pyhelpers._cache import example_dataframe
>>> import polars as pl

>>> df1 = example_dataframe().copy()
>>> df1.dtypes
Longitude    float64
Latitude     float64
dtype: object

>>> df2 = example_dataframe().T.copy()
>>> df2.dtypes
City
London        float64
Birmingham    float64
Manchester    float64
Leeds         float64
dtype: object

>>> df11, df21 = downcast_numeric_columns(df1, df2)

>>> df11.dtypes
Longitude    float32
Latitude     float32
dtype: object

>>> df21.dtypes
City
London        float32
Birmingham    float32
Manchester    float32
Leeds         float32
dtype: object

>>> df1, df2 = map(pl.from_pandas, (df1, df2))

>>> df1.dtypes
[Float64, Float64]
>>> df2.dtypes
[Float64, Float64, Float64, Float64]

>>> df21, df22 = downcast_numeric_columns(df1, df2)
>>> df21.dtypes
[Float32, Float32]
>>> df22.dtypes
[Float32, Float32, Float32, Float32]