ZetCode

Pandas Binning and Ranking

last modified November 17, 2026 Python 3.15

Binning is the process of grouping many numeric values into a smaller number of ranges, called bins, and replacing each value with the bin it falls into. It turns a continuous quantity such as an exact age into a coarse category such as a ten-year band. Closely related to binning is ranking, which assigns each value its position in an ordered list.

Pandas provides cut for bins of our choosing and qcut for bins that hold equal numbers of values. It also offers rank for positions, nlargest and nsmallest for extreme values, and between for range tests. All examples were run with pandas 3.1.1.

Binning with cut

The cut method divides the range of a Series into intervals. When we pass an integer as bins, Pandas computes that many equal-width intervals between the smallest and largest value and widens the ends slightly so nothing falls outside. The result is a categorical Series: each entry is the interval containing the original number.

binning_cut.py
import pandas as pd

s = pd.Series([1, 7, 5, 12, 3, 20])
print(pd.cut(s, bins=4))

The values range from 1 to 20, so four equal-width bins were created. The notation (0.981, 5.75] means numbers greater than 0.981 and up to and including 5.75. The square bracket on the right shows that the upper end belongs to the bin; the parenthesis on the left shows that the lower end does not.

$ python binning_cut.py
0    (0.981, 5.75]
1     (5.75, 10.5]
2    (0.981, 5.75]
3    (10.5, 15.25]
4    (0.981, 5.75]
5    (15.25, 20.0]
dtype: category
Categories (4, interval[float64, right]): [(0.981, 5.75] < (5.75, 10.5] <
                                           (10.5, 15.25] < (15.25, 20.0]]

Named bins

Instead of letting Pandas choose the boundaries, we can supply the edge values as a list through bins=. The labels= parameter then replaces the interval notation with readable names. There is one label per bin, so four edges produce three bins and we supply three labels here.

binning_labels.py
import pandas as pd

s = pd.Series([1, 7, 5, 12, 3, 20])
print(pd.cut(s, bins=[0, 5, 10, 20], labels=['low', 'mid', 'high']))

The edges 0, 5, 10 and 20 define the ranges from 0 to 5, from 5 to 10 and from 10 to 20. Values 1, 5 and 3 fall into low, the value 7 into mid, and 12 and 20 into high. The categories are ordered, so low < mid < high.

$ python binning_labels.py
0     low
1     mid
2     low
3    high
4     low
5    high
dtype: category
Categories (3, str): ['low' < 'mid' < 'high']

include_lowest

By default a bin opens on the left, so a value exactly equal to the first edge is not counted in the first bin. Setting include_lowest=True makes that first boundary inclusive. The option matters when the data actually contains the lowest edge, as the value 1 does in this Series.

binning_lowest.py
import pandas as pd

s = pd.Series([1, 7, 5, 12, 3, 20])
print(pd.cut(s, bins=[1, 5, 10, 20]))
print()
print(pd.cut(s, bins=[1, 5, 10, 20], include_lowest=True))

In the first result the value 1 becomes NaN because it is not greater than the lower edge of 1. With include_lowest=True that same value lands in the first bin, which is drawn as (0.999, 5.0] to show that the edge has been pulled slightly below 1.

$ python binning_lowest.py
0             NaN
1     (5.0, 10.0]
2      (1.0, 5.0]
3    (10.0, 20.0]
4      (1.0, 5.0]
5    (10.0, 20.0]
dtype: category
Categories (3, interval[int64, right]): [(1, 5] < (5, 10] < (10, 20]]

0    (0.999, 5.0]
1     (5.0, 10.0]
2    (0.999, 5.0]
3    (10.0, 20.0]
4    (0.999, 5.0]
5    (10.0, 20.0]
dtype: category
Categories (3, interval[float64, right]): [(0.999, 5.0] < (5.0, 10.0] <
                                           (10.0, 20.0]]

qcut for equal-sized groups

Where cut makes equal-width intervals, qcut makes intervals of equal size in terms of how many values they contain. The cut points are quantiles, values that split sorted data into equal portions. Asking for four groups of eight numbers places two values in each bin.

binning_qcut.py
import pandas as pd

s = pd.Series([1, 2, 3, 4, 5, 6, 7, 8])
print(pd.qcut(s, 4))

The eight values are split into four bins with two members apiece: 1 and 2, 3 and 4, 5 and 6, and finally 7 and 8. Notice that the intervals are not all the same width in this example, because equal counts rather than equal spans are the goal.

$ python binning_qcut.py
0    (0.999, 2.75]
1    (0.999, 2.75]
2      (2.75, 4.5]
3      (2.75, 4.5]
4      (4.5, 6.25]
5      (4.5, 6.25]
6      (6.25, 8.0]
7      (6.25, 8.0]
dtype: category
Categories (4, interval[float64, right]): [(0.999, 2.75] < (2.75, 4.5] <
                                           (4.5, 6.25] < (6.25, 8.0]]

Ranking values

The rank method gives each value its position starting at 1. The default method='average' splits the positions among tied values, so two entries equal at 20 both receive 2.5, the average of ranks 2 and 3. The method='min' alternative gives every member of a tie the smallest position it could occupy, which is 2 here.

binning_rank.py
import pandas as pd

s = pd.Series([10, 20, 20, 40])
print(s.rank())
print()
print(s.rank(method='min'))

In both results 10 is first and 40 is fourth. Only the tied pair changes: the average method reports 2.5 for each, while the minimum method reports 2 for each. The ranks are floating-point numbers so that fractional positions can be represented.

$ python binning_rank.py
0    1.0
1    2.5
2    2.5
3    4.0
dtype: float64

0    1.0
1    2.0
2    2.0
3    4.0
dtype: float64

nlargest and nsmallest

Sometimes we do not need ranks for every value but only the few extreme ones. The nlargest and nsmallest methods return the top and bottom n values in sorted order, keeping their original index labels so we can see where each came from.

binning_extremes.py
import pandas as pd

s = pd.Series([10, 30, 20, 50, 40])
print(s.nlargest(3))
print()
print(s.nsmallest(2))

The three largest values are 50, 40 and 30 at indices 3, 4 and 1. The two smallest are 10 and 20 at indices 0 and 2. Unlike sorting the whole Series, these methods return only the requested number of entries.

$ python binning_extremes.py
3    50
4    40
1    30
dtype: int64

0    10
2    20
dtype: int64

Testing ranges with between

The between method answers a yes-or-no question for each value: does it lie inside the given range? Both ends are included by default. The method returns a boolean Series, which can be used directly to filter the original data.

binning_between.py
import pandas as pd

s = pd.Series([1, 5, 10, 15, 20])
print(s.between(5, 15))
print()
print(s[s.between(5, 15)])

The bounds 5 and 15 are included, so three values pass the test and the first result contains three True entries. Using that boolean Series as a mask returns just 5, 10 and 15. This style of filtering is explained further in the Pandas boolean indexing tutorial.

$ python binning_between.py
0    False
1     True
2     True
3     True
4    False
dtype: bool

1     5
2    10
3    15
dtype: int64

Source

Pandas cut Documentation, Pandas qcut Documentation, and Pandas Series.rank Documentation

In this article we have binned numbers with cut and qcut, named the resulting intervals, handled the lowest edge with include_lowest, ranked tied values, picked out the extremes with nlargest and nsmallest, and tested ranges with between. The output of cut is a categorical Series; see the Pandas categorical data tutorial for more on that dtype, the Pandas data types tutorial for dtypes in general, and the sorting values tutorial for ordering data.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Pandas tutorials.