Skip to main content
`Ctrl`+`K`

# pandas.cut

pandas.cut(x, bins, right=True, labels=None, retbins=False, precision=3, include_lowest=False, duplicates='raise', ordered=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. 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 1d ndarray or Series

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

    bins int, 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.

    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.

    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{‘raise’, ‘drop’}, default ‘raise’

      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 a 1d ndarray or Series 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.

  See also

  `qcut`

    Discretize variable into equal-sized buckets based on rank or based on sample quantiles.

  `Categorical`

    Array type for storing data that come from a fixed set of values.

  `Series`

    One-dimensional array with axis labels (including time series).

  `IntervalIndex`

    Immutable Index implementing an ordered, sliceable set.

  `numpy.histogram_bin_edges`

    Function to calculate only the edges of the bins used by the histogram function.

  Notes

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

  `numpy.histogram_bin_edges` can be used along with cut to calculate bins according to some predefined methods.

  Reference the user guide for more examples.

  Examples

  Discretize into three equal-sized bins.

      >>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3)
      ...
      [(0.994, 3.0], (5.0, 7.0], (3.0, 5.0], (3.0, 5.0], (5.0, 7.0], ...
      Categories (3, interval[float64, right]): [(0.994, 3.0] < (3.0, 5.0] ...

      >>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3, retbins=True)
      ...
      ([(0.994, 3.0], (5.0, 7.0], (3.0, 5.0], (3.0, 5.0], (5.0, 7.0], ...
      Categories (3, interval[float64, right]): [(0.994, 3.0] < (3.0, 5.0] ...
      array([0.994, 3.   , 5.   , 7.   ]))

  Discovers the same bins, but assign them specific labels. Notice that the returned Categorical’s categories are labels and is ordered.

      >>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3, labels=["bad", "medium", "good"])
      ['bad', 'good', 'medium', 'medium', 'good', 'bad']
      Categories (3, str): ['bad' < 'medium' < 'good']

  `ordered=False` will result in unordered categories when labels are passed. This parameter can be used to allow non-unique labels:

      >>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3, labels=["B", "A", "B"], ordered=False)
      ['B', 'B', 'A', 'A', 'B', 'B']
      Categories (2, str): ['A', 'B']

  `labels=False` implies you just want the bins back.

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

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

      >>> s = pd.Series(np.array([2, 4, 6, 8, 10]), index=["a", "b", "c", "d", "e"])
      >>> pd.cut(s, 3)
      ...
      a    (1.992, 4.667]
      b    (1.992, 4.667]
      c    (4.667, 7.333]
      d     (7.333, 10.0]
      e     (7.333, 10.0]
      dtype: category
      Categories (3, interval[float64, right]): [(1.992, 4.667] < (4.667, ...

  Passing a Series as an input returns a Series with mapping value. It is used to map numerically to intervals based on bins.

      >>> s = pd.Series(np.array([2, 4, 6, 8, 10]), index=["a", "b", "c", "d", "e"])
      >>> pd.cut(s, [0, 2, 4, 6, 8, 10], labels=False, retbins=True, right=False)
      ...
      (a    1.0
       b    2.0
       c    3.0
       d    4.0
       e    NaN
       dtype: float64,
       array([ 0,  2,  4,  6,  8, 10]))

  Use drop optional when bins is not unique

      >>> pd.cut(
      ...     s,
      ...     [0, 2, 4, 6, 10, 10],
      ...     labels=False,
      ...     retbins=True,
      ...     right=False,
      ...     duplicates="drop",
      ... )
      ...
      (a    1.0
       b    2.0
       c    3.0
       d    3.0
       e    NaN
       dtype: float64,
       array([ 0,  2,  4,  6, 10]))

  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.

      >>> bins = pd.IntervalIndex.from_tuples([(0, 1), (2, 3), (4, 5)])
      >>> pd.cut([0, 0.5, 1.5, 2.5, 4.5], bins)
      [NaN, (0.0, 1.0], NaN, (2.0, 3.0], (4.0, 5.0]]
      Categories (3, interval[int64, right]): [(0, 1] < (2, 3] < (4, 5]]

  Using np.histogram_bin_edges with cut

      >>> pd.cut(
      ...     np.array([1, 7, 5, 4]),
      ...     bins=np.histogram_bin_edges(np.array([1, 7, 5, 4]), bins="auto"),
      ... )
      ...
      [NaN, (5.0, 7.0], (3.0, 5.0], (3.0, 5.0]]
      Categories (3, interval[float64, right]): [(1.0, 3.0] < (3.0, 5.0] < (5.0, 7.0]]