pandas.MultiIndex.set_levels — pandas 3.0.0.dev0+2100.gf496acffcc documentation (original) (raw)

MultiIndex.set_levels(levels, *, level=None, verify_integrity=True)[source]#

Set new levels on MultiIndex. Defaults to returning new index.

The set_levels method provides a flexible way to change the levels of aMultiIndex. This is particularly useful when you need to update the index structure of your DataFrame without altering the data. The method returns a new MultiIndex unless the operation is performed in-place, ensuring that the original index remains unchanged unless explicitly modified.

The method checks the integrity of the new levels against the existing codes by default, but this can be disabled if you are confident that your levels are consistent with the underlying data. This can be useful when you want to perform optimizations or make specific adjustments to the index levels that do not strictly adhere to the original structure.

Parameters:

levelssequence or list of sequence

New level(s) to apply.

levelint, level name, or sequence of int/level names (default None)

Level(s) to set (None for all levels).

verify_integritybool, default True

If True, checks that levels and codes are compatible.

Returns:

MultiIndex

A new MultiIndex with the updated levels.

Examples

idx = pd.MultiIndex.from_tuples( ... [ ... (1, "one"), ... (1, "two"), ... (2, "one"), ... (2, "two"), ... (3, "one"), ... (3, "two"), ... ], ... names=["foo", "bar"], ... ) idx MultiIndex([(1, 'one'), (1, 'two'), (2, 'one'), (2, 'two'), (3, 'one'), (3, 'two')], names=['foo', 'bar'])

idx.set_levels([["a", "b", "c"], [1, 2]]) MultiIndex([('a', 1), ('a', 2), ('b', 1), ('b', 2), ('c', 1), ('c', 2)], names=['foo', 'bar']) idx.set_levels(["a", "b", "c"], level=0) MultiIndex([('a', 'one'), ('a', 'two'), ('b', 'one'), ('b', 'two'), ('c', 'one'), ('c', 'two')], names=['foo', 'bar']) idx.set_levels(["a", "b"], level="bar") MultiIndex([(1, 'a'), (1, 'b'), (2, 'a'), (2, 'b'), (3, 'a'), (3, 'b')], names=['foo', 'bar'])

If any of the levels passed to set_levels() exceeds the existing length, all of the values from that argument will be stored in the MultiIndex levels, though the values will be truncated in the MultiIndex output.

idx.set_levels([["a", "b", "c"], [1, 2, 3, 4]], level=[0, 1]) MultiIndex([('a', 1), ('a', 2), ('b', 1), ('b', 2), ('c', 1), ('c', 2)], names=['foo', 'bar']) idx.set_levels([["a", "b", "c"], [1, 2, 3, 4]], level=[0, 1]).levels FrozenList([['a', 'b', 'c'], [1, 2, 3, 4]])