Method set_levels

pandas/core/indexes/multi.py:930–1047

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

(
        self, levels, *, level=None, verify_integrity: bool = True
    )

        self._reset_cache()

    def set_levels(
        self, levels, *, level=None, verify_integrity: bool = True
    ) -> MultiIndex:
        """
        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
        ----------
        levels : sequence or list of sequence
            New level(s) to apply.
        level : int, level name, or sequence of int/level names (default None)
            Level(s) to set (None for all levels).
        verify_integrity : bool, 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'),