cudf.cut#

cudf.cut(x, bins, right: bool = True, labels=None, retbins: bool = False, precision: int = 3, include_lowest: bool = False, duplicates: str = 'raise', ordered: bool = True)#

Bin values into discrete intervals.

Use cut when you need to segment and sort data values into bins. This function is also useful for going from a continuous variable to a categorical variable.

Parameters:

xarray-like

The input array to be binned. Must be 1-dimensional.

binsint, sequence of scalars, or IntervalIndex

The criteria to bin by.

int : Defines the number of equal-width bins in the range of x. The range of x is extended by .1% on each side to include the minimum and maximum values of x.
sequence of scalars : Defines the bin edges allowing for non-uniform width. No extension of the range of x is done.
IntervalIndex : Defines the exact bins to be used. Note that IntervalIndex for bins must be non-overlapping.

rightbool, default True

Indicates whether bins includes the rightmost edge or not.

labelsarray or False, default None

Specifies the labels for the returned bins. Must be the same length as the resulting bins. If False, returns only integer indicators of the bins. If True,raises an error. When ordered=False, labels must be provided.

retbinsbool, default False

Whether to return the bins or not.

precisionint, default 3

The precision at which to store and display the bins labels.

include_lowestbool, default False

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.

orderedbool, default True

Whether the labels are ordered or not. Applies to returned types Categorical and Series (with Categorical dtype). If True, the resulting categorical will be ordered. If False, the resulting categorical will be unordered (labels must be provided).

Returns:

outCategoricalIndex: An array-like object representing the respective bin for each value of x. The type depends on the value of labels.
binsnumpy.ndarray or IntervalIndex.: The computed or specified bins. Only returned when retbins=True. For scalar or sequence bins, this is an ndarray with the computed bins. If set duplicates=drop, bins will drop non-unique bin. For an IntervalIndex bins, this is equal to bins.

Examples

Discretize into three equal-sized bins.

>>> cudf.cut(np.array([1, 7, 5, 4, 6, 3]), 3)
CategoricalIndex([(0.994, 3.0], (5.0, 7.0], (3.0, 5.0], (3.0, 5.0],
            (5.0, 7.0], (0.994, 3.0]], categories=[(0.994, 3.0],
            (3.0, 5.0], (5.0, 7.0]], ordered=True, dtype='category')

>>> cudf.cut(np.array([1, 7, 5, 4, 6, 3]), 3, retbins=True)
(CategoricalIndex([(0.994, 3.0], (5.0, 7.0], (3.0, 5.0], (3.0, 5.0],
            (5.0, 7.0], (0.994, 3.0]], categories=[(0.994, 3.0],
            (3.0, 5.0], (5.0, 7.0]], ordered=True, dtype='category'),
 array([0.994, 3.   , 5.   , 7.   ]))

>>> cudf.cut(np.array([1, 7, 5, 4, 6, 3]),
...          3, labels=["bad", "medium", "good"])
CategoricalIndex(['bad', 'good', 'medium', 'medium', 'good', 'bad'],
                 categories=['bad', 'medium', 'good'],ordered=True,
                 dtype='category')

>>> cudf.cut(np.array([1, 7, 5, 4, 6, 3]), 3,
...          labels=["B", "A", "B"], ordered=False)
CategoricalIndex(['B', 'B', 'A', 'A', 'B', 'B'], categories=['A', 'B'],
           ordered=False, dtype='category')

>>> cudf.cut([0, 1, 1, 2], bins=4, labels=False)
array([0, 1, 1, 3], dtype=int32)

Passing a Series as an input returns a Series with categorical dtype:

>>> s = cudf.Series(np.array([2, 4, 6, 8, 10]),
...        index=['a', 'b', 'c', 'd', 'e'])
>>> cudf.cut(s, 3)