modin.pandas.cut

modin.pandas.cut(x: AnyArrayLike, bins: int | Sequence[Scalar] | IntervalIndex, right: bool = True, labels=None, retbins: bool = False, precision: int = 3, include_lowest: bool = False, duplicates: str = 'raise', ordered: bool = True)[source]

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. For example, cut could convert ages to groups of age ranges. Supports binning into an equal number of bins, or a pre-specified array of bins.

Parameters:

  • x (array-like) – The input array to be binned. Must be 1-dimensional.

  • bins (int, sequence of scalars) –

    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.

  • right (bool, default True) – Indicates whether bins includes the rightmost edge or not. If right == True (the default), then the bins [1, 2, 3, 4] indicate (1,2], (2,3], (3,4]. This argument is ignored when bins is an IntervalIndex.

  • labels (array 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. This affects the type of the output container (see below). This argument is ignored when bins is an IntervalIndex. If True, raises an error. When ordered=False, labels must be provided.

    Snowpark pandas API does not support labels=None. Labels must be of a Snowpark pandas API supported dtype.

  • retbins (bool, default False) – Snowpark pandas API does not support this parameter yet.

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

  • duplicates ({default 'raise', 'drop'}, optional) – If bin edges are not unique, raise ValueError or drop non-uniques.

  • ordered (bool, 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:

  • out (Categorical, Series, or ndarray) – An array-like object representing the respective bin for each value of x. The type depends on the value of labels.

    • None (default) : returns a Series for Series x or a Categorical for all other inputs. The values stored within are Interval dtype.

    • sequence of scalars : returns a Series for Series x or a Categorical for all other inputs. The values stored within are whatever the type in the sequence is.

    • False : returns an ndarray of integers.

  • bins (numpy.ndarray) – 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.

Notes

Any NA values will be NA in the result. Out of bounds values will be NA in the resulting Series or Categorical object.

Snowpark pandas API does not natively support Categorical and categorical types. When calling cut with a Snowpark pandas Series and using labels=False, a Snowpark pandas Series object is returned. However, for labels != False an error is raised.

Examples

Discretize into three equal-sized bins.

>>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3, labels=False)
... 
array([0, 2, 1, 1, 2, 0])
Copy

labels=False implies you just want the bins back.

>>> pd.cut([0, 1, 1, 2], bins=4, labels=False)
array([0, 1, 1, 3])
Copy

Passing a Series as an input returns a Series with labels=False:

>>> s = pd.Series(np.array([2, 4, 6, 8, 10]),
...               index=['a', 'b', 'c', 'd', 'e'])
>>> pd.cut(s, 3, labels=False)
... 
a    0
b    0
c    1
d    2
e    2
dtype: int64
Copy
Language: English