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, or pandas.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.

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 bool, optional

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.

retbins : bool, default False

Whether to return the bins or not. Useful when bins is provided
as a scalar.

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.

New in version 0.23.0.

Returns:

out : pandas.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.

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

sequence of scalars : returns a Series for Series x or a
pandas.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 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.

Passing an IntervalIndex for bins results in those categories exactly.
Notice that values not covered by the IntervalIndex are set to NaN. 0
is to the left of the first bin (which is closed on the right), and 1.5
falls between two bins.