Represent hierarchical categories
A DataFrame needs labels such as region and team on its rows.
Pandas · Class
MultiIndex
pandas.MultiIndex is a hierarchical index that uses multiple levels of labels on one Series or DataFrame axis. It supports indexing by combinations of keys while keeping the underlying object at its usual dimensionality.
How it works
MultiIndex is pandas' hierarchical index for labeling one axis with multiple levels. Each row label is represented by a unique combination of level labels, allowing DataFrames and Series to be indexed along several dimensions without adding dimensions to the object.
Syntax
class pandas.MultiIndex(*levels=None*, *codes=None*, *sortorder=None*, *names=None*, *copy=False*, *name=None*, *verify_integrity=True*)[source]Parameters
| Name | Type | Description |
|---|---|---|
levels | sequence of arrays | The unique labels for each level. |
codes | sequence of arrays | Integers for each level designating which label occurs at each position. |
sortorder | optional int | Level of sortedness; it must be lexicographically sorted by that level. |
names | optional sequence of objects | Names for the index levels; name is accepted for compatibility. |
copy | bool, default False | Whether to copy metadata. |
name | optional hashable | Compatibility alias for names. |
verify_integrity | bool, default True | Whether to check that levels and codes are consistent and valid. |
Returns
A pandas.MultiIndex object.
Key points
- Use MultiIndex when one Series or DataFrame axis needs hierarchical labels with more than one level.
- Multiple keys let you address nested categories on one axis while retaining a two-dimensional DataFrame or one-dimensional Series.
- Conceptually, every position is identified by a unique tuple containing one label from each level.
- The levels parameter stores the distinct label values independently for each hierarchy level.
- The codes parameter maps each position to a label in its corresponding level.
- Use names to give the hierarchy levels descriptive identifiers for display and level-based operations.
Common mistakes
- A supplied sortorder is valid only when the index is lexicographically sorted through the specified level.
- Turning off integrity verification can allow inconsistent or invalid level/code combinations; keep the default unless validation is handled elsewhere.
- Labels that compare equal cannot coexist within the same level, even when their Python types differ.
Example: Create and select a hierarchical index
import pandas as pd
index = pd.MultiIndex.from_product(
[["east", "west"], ["sales", "support"]],
names=["region", "team"],
)
df = pd.DataFrame({"headcount": [3, 2, 4, 5]}, index=index)
print(df.loc["east"])
Creates a two-level index from every region-team combination, then selects one outer-level label.
When to use it
Build Cartesian-product indexes
A complete set of combinations must be materialized as index labels.
Perform multi-key indexing
Data must be selected using nested keys on one axis.
Interview questions
QWhat is a MultiIndex?
A MultiIndex is a hierarchical index whose labels have multiple levels. It can be viewed as an array of unique tuples, so a single axis can represent combinations such as region and team.
Follow-up: How can you construct one without manually supplying levels and codes? Use class methods such as from_arrays, from_tuples, from_product, or from_frame.
QWhat do levels and codes represent?
The levels argument contains the unique labels for each level. The codes argument contains integer arrays that identify which label from each level is used at every position.
Follow-up: Why are codes integers rather than labels? They provide positional references into the unique label arrays stored in levels.
QWhen would you use MultiIndex.from_product?
from_product creates a MultiIndex containing all combinations from the supplied iterables. It is useful when the index should cover a complete Cartesian product of level values.
Follow-up: What constraint applies to each iterable? Each iterable must contain unique labels for its level.
Related
MultiIndex.from_arraysMultiIndex.from_tuplesMultiIndex.from_productMultiIndex.from_frameIndexSeriesDataFrame