Top-N selection
Ranking records by a numeric metric
Pandas · Module
df.nlargest
Returns the rows with the largest values in specified DataFrame columns, ordered descending. It supports configurable handling of ties through keep.
How it works
Call DataFrame.nlargest to return rows ordered by one or more columns from largest to smallest. It retains all DataFrame columns, uses only the named columns for ordering, and provides explicit tie policies through keep.
Syntax
DataFrame.nlargest(n, columns, keep='first')Parameters
| Name | Type | Description |
|---|---|---|
n | int | Number of rows to return. |
columns | Hashable or a sequence | Column label or sequence of column labels to order by. |
keep | {'first', 'last', 'all'}, default 'first' | Duplicate-value policy: first, last, or all; defaults to first. |
Returns
DataFrame containing the first n rows ordered by the specified columns in descending order.
Key points
- The method selects the leading
nrows after descending ordering. - All original columns remain in the result, while only the named columns determine order.
- It provides a specialized, generally faster alternative to sorting descending and taking the head.
- The default
keep="first"favors earlier rows when ordering values tie. keep="last"resolves equal values by favoring later occurrences.
Common mistakes
- Not every dtype is supported for ordering.
- Using object or category columns for the ordering raises TypeError.
- With
keep="all", the result can contain more thannrows.
Example: Select highest-valued rows
import pandas as pd
df = pd.DataFrame({
"name": ["Ada", "Grace", "Linus", "Edsger"],
"score": [91, 98, 87, 98],
})
print(df.nlargest(2, "score"))
print(df.nlargest(2, "score", keep="all"))Select the two highest-scoring rows; the second call retains every row tied at the cutoff.
When to use it
Tie-aware reporting
Including every record tied at the boundary
Multi-column ranking
Ordering by multiple sortable columns
Interview questions
QWhat does DataFrame.nlargest return?
It returns the first n rows ordered by the selected columns in descending order. Unlike selecting only the ordering columns, it returns the other DataFrame columns too.
Follow-up: How would you express the same operation with general sorting? Use df.sort_values(columns, ascending=False).head(n), although the documentation notes that nlargest is more performant.
QWhat are the roles of n and columns?
columns identifies the column label or sequence of labels used for ordering. n specifies how many rows to return.
Follow-up: What happens to non-selected columns? They remain in the returned DataFrame but do not participate in ordering.
QHow does keep affect duplicate values?
keep="first" prioritizes first duplicate occurrences, keep="last" prioritizes last occurrences, and keep="all" preserves ties at the cutoff even when that exceeds n rows.
Follow-up: Which option should be used when every tied row must be included? Use keep="all".
Related
DataFrame.sort_values