diff --git a/pandas/core/reshape/tile.py b/pandas/core/reshape/tile.py index 980e8aa41669f..fa7a1feccc9c9 100644 --- a/pandas/core/reshape/tile.py +++ b/pandas/core/reshape/tile.py @@ -102,7 +102,7 @@ def cut( precision : int, default 3 The precision at which to store and display the bins labels. include_lowest : bool, default False - Whether the first interval should be left-inclusive or not. + Whether the first interval should be left-inclusive or not. duplicates : {default 'raise', 'drop'}, optional If bin edges are not unique, raise ValueError or drop non-uniques. ordered : bool, default True @@ -111,6 +111,24 @@ def cut( the resulting categorical will be ordered. If False, the resulting categorical will be unordered (labels must be provided). + Notes + ------- + Using include_lowest shifts the lower bound of x by -0.001, + due to the .1% extension on the range x, which makes the + dtype of bin intervals to change from int64 to float64 + + Examples + -------- + In: + >>> pd.cut(np.array([0, 1, 7]), bins=[0, 3, 6, 8], include_lowest=True) + ... # doctest: +ELLIPSIS + Out: + [(-0.001, 3.0], (-0.001, 3.0], (6.0, 8.0]] + Categories (3, interval[float64]): [(-0.001, 3.0] < (3.0, 6.0] < (6.0, 8.0]] + + The lowermost interval changes from 0 to -0.001 after .1% adjustment + which results in change of dtype from int64 to float64 + Returns ------- out : Categorical, Series, or ndarray