pandas.MultiIndex.set_levels#

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 a MultiIndex. 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.

See also

MultiIndex.set_codes: Set new codes on the existing MultiIndex.
MultiIndex.remove_unused_levels: Create new MultiIndex from current that removes unused levels.
Index.set_names: Set Index or MultiIndex name.

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]])