Rank-based segmentation
Convert a numeric score into quartile or decile groups for reporting.
Pandas · Function
pd.qcut
Divides one-dimensional data into quantile-based buckets, typically producing groups with similar numbers of observations. Use q to choose a number of quantiles or provide explicit quantile probabilities.
How it works
qcut ranks one-dimensional values and divides them into bins whose boundaries are sample quantiles. Pass an integer for an equal number of quantiles or an ordered sequence of quantile boundaries; the result is categorical for ordinary output, or integer bin codes when labels=False.
Syntax
pandas.qcut(x, q, labels=None, retbins=False, precision=3, duplicates='raise')Parameters
| Name | Type | Description |
|---|---|---|
x | 1d ndarray or Series | One-dimensional NumPy array or pandas Series to discretize. |
q | int or list-like of float | Number of quantiles, or an ordered list-like sequence of quantile probabilities. |
labels | array or False, default None | Labels for the resulting bins; use False for integer indicators. Default is None. |
retbins | bool, optional | Whether to return bin edges together with the result. Default is False. |
precision | int, optional | Precision used to store and display bin labels. Default is 3. |
duplicates | 'raise' or 'drop', optional | How to handle non-unique edges: raise an error or drop them. Default is 'raise'. |
Returns
Categorical, Series, or integer array when labels=False; a Series input yields a categorical Series, otherwise the result is Categorical. If retbins=True, also returns an ndarray of floating-point bin edges.
Key points
- Use qcut to turn continuous one-dimensional data into quantile-based categories.
- Its buckets are based on rank or sample quantiles, aiming for similar observation counts rather than equal numeric widths.
- An integer q directly expresses familiar groupings such as deciles or quartiles.
- Use an ordered quantile array when the desired probability cut points are explicit.
- labels=False produces numeric bin indicators instead of categorical labels.
- retbins=True additionally exposes the calculated edges alongside the categorized result.
Common mistakes
- When supplying labels, provide exactly one label for each resulting bin.
- Repeated values can produce duplicate quantile edges; choose duplicates="drop" to remove them or retain the default error.
- Do not use labels=True; the documented behavior is to raise an error.
Example: Create labeled quartiles
import pandas as pd
scores = pd.Series([10, 20, 30, 40, 50, 60, 70, 80])
bands, edges = pd.qcut(
scores,
q=4,
labels=["Q1", "Q2", "Q3", "Q4"],
retbins=True,
)
print(bands)
print(edges)This assigns eight scores to four equal-frequency quartiles and returns the computed bin edges.
When to use it
Feature engineering
Create categorical features with comparable sample counts for analysis or modeling.
Expose quantile edges
Inspect the numeric thresholds used for categorization.
Interview questions
QWhat distinguishes qcut from value-based binning?
qcut performs quantile-based discretization, so it creates intervals from sample quantiles rather than fixed-width value ranges. With q=4, it targets quartiles.
Follow-up: How would you obtain the boundaries as well as the categories? Set retbins=True; the result includes the categorical output and a floating-point array of bin edges.
QHow can q specify the quantile divisions?
An integer q specifies the number of quantiles, while a list-like q supplies explicit quantile probabilities such as [0, 0.25, 0.5, 0.75, 1].
Follow-up: What happens if explicit boundaries create duplicate edges? The default raises ValueError; duplicates="drop" removes non-unique edges.
QWhat does qcut return?
For a Series input, the output is a categorical Series; for other one-dimensional input, it is a Categorical object. Setting labels=False returns integer bin indicators instead.
Follow-up: How can callers control displayed bin-label precision? Use precision, whose default is 3.
Related
pandas.cutpandas.Categoricalpandas.Series