# pandas.qcut

`pandas.``qcut`(x, q, labels=None, retbins=False, precision=3, duplicates='raise')

  Quantile-based discretization function. Discretize variable into equal-sized buckets based on rank or based on sample quantiles. For example 1000 values for 10 quantiles would produce a Categorical object indicating quantile membership for each data point.

  Parameters:

  x : 1d ndarray or Series

  q : integer or array of quantiles

  > Number of quantiles. 10 for deciles, 4 for quartiles, etc. Alternately array of quantiles, e.g. [0, .25, .5, .75, 1.] for quartiles

  labels : array or boolean, default None

  > Used as labels for the resulting bins. Must be of the same length as the resulting bins. If False, return only integer indicators of the bins.

  retbins : bool, optional

  > Whether to return the (bins, labels) or not. Can be useful if bins is given as a scalar.

  precision : int, optional

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

  duplicates : {default ‘raise’, ‘drop’}, optional

  > If bin edges are not unique, raise ValueError or drop non-uniques.

  > New in version 0.20.0.

  Returns:

  out : Categorical or Series or array of integers if labels is False

  > The return type (Categorical or Series) depends on the input: a Series of type category if input is a Series else Categorical. Bins are represented as categories when categorical data is returned.

  bins : ndarray of floats

  > Returned only if retbins is True.

  Notes

  Out of bounds values will be NA in the resulting Categorical object

  Examples

      >>> pd.qcut(range(5), 4)
      ...
      [(-0.001, 1.0], (-0.001, 1.0], (1.0, 2.0], (2.0, 3.0], (3.0, 4.0]]
      Categories (4, interval[float64]): [(-0.001, 1.0] < (1.0, 2.0] ...

      >>> pd.qcut(range(5), 3, labels=["good", "medium", "bad"])
      ...
      [good, good, medium, bad, bad]
      Categories (3, object): [good < medium < bad]

      >>> pd.qcut(range(5), 4, labels=False)
      array([0, 0, 1, 2, 3])

Scroll To Top