edit set_levels docstring with additional examples

Author: hweecat

doc/source/user_guide/advanced.rst

@@ -177,37 +177,6 @@ completely analogous way to selecting a column in a regular DataFrame:
 See :ref:`Cross-section with hierarchical index <advanced.xs>` for how to select
 on a deeper level.
 
-.. _advanced.set_levels:
-
-Set values in levels
-~~~~~~~~~~~~~~~~~~~~~
-
-The method :meth:`~MultiIndex.set_levels` changes the ``levels`` attribute by
-passing a new value for each index in the level. It is assumed that a new value
-is provided for each code describing values in the level.
-For example:
-
-.. ipython:: python
-
-   df.columns   # original MultiIndex columns
-
-   df.columns.levels   # original MultiIndex column levels
-
-   df.columns.set_levels([1, 3, 5, 7], level=0)
-
-   df.columns.set_levels([1, 3, 5, 7], level=0).levels
-
-If you pass more values than the number of index values in the level,
-``set_levels`` will still pass the values to the level. The passed values
-are stored in the MultiIndex ``FrozenList`` even though the index values
-may be truncated in the MultiIndex output from ``set_levels``.
-
-.. ipython:: python
-
-    df.columns.set_levels([1, 3, 5, 7], level=1)
-
-    df.columns.set_levels([1, 3, 5, 7], level=1).levels
-
 .. _advanced.shown_levels:
 
 Defined levels

pandas/core/indexes/multi.py

@@ -719,8 +719,15 @@ def _set_levels(
 
     def set_levels(self, levels, level=None, inplace=False, verify_integrity=True):
         """
-        Set new levels on MultiIndex. Defaults to returning
-        new index.
+        Sets/changes levels on MultiIndex by passing a new value for each
+        index in the level. It is assumed that a new value is provided for
+        each code describing values in the level. Defaults to returning new
+        index.
+
+        If the number of values passed is more than number of index values in
+        the level, ``set_levels`` will still pass the values to the level. The
+        passed values are stored in the MultiIndex FrozenList even though the
+        index values may be truncated in the MultiIndex output from set_levels.
 
         Parameters
         ----------
@@ -740,32 +747,51 @@ def set_levels(self, levels, level=None, inplace=False, verify_integrity=True):
         Examples
         --------
         >>> idx = pd.MultiIndex.from_tuples([(1, 'one'), (1, 'two'),
-                                            (2, 'one'), (2, 'two')],
+                                            (2, 'one'), (2, 'two'),
+                                            (3, 'one'), (3, 'two')],
                                             names=['foo', 'bar'])
-        >>> idx.set_levels([['a', 'b'], [1, 2]])
+        >>> idx.set_levels([['a', 'b', 'c'], [1, 2]])
         MultiIndex([('a', 1),
                     ('a', 2),
                     ('b', 1),
-                    ('b', 2)],
+                    ('b', 2),
+                    ('c', 1),
+                    ('c', 2)],
                    names=['foo', 'bar'])
-        >>> idx.set_levels(['a', 'b'], level=0)
+        >>> idx.set_levels(['a', 'b', 'c'], level=0)
         MultiIndex([('a', 'one'),
                     ('a', 'two'),
                     ('b', 'one'),
-                    ('b', 'two')],
+                    ('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')],
+                    (2, 'b'),
+                    (3, 'a'),
+                    (3, 'b')],
+                   names=['foo', 'bar'])
+        >>> idx.set_levels([['a', 'b', 'c'], [1, 2]], level=[0, 1])
+        MultiIndex([('a', 1),
+                    ('a', 2),
+                    ('b', 1),
+                    ('b', 2),
+                    ('c', 1),
+                    ('c', 2)],
                    names=['foo', 'bar'])
-        >>> idx.set_levels([['a', 'b'], [1, 2]], level=[0, 1])
+        >>> idx.set_levels([['a', 'b', 'c'], [1, 2]], level=[0, 1]).levels
+        FrozenList([['a', 'b', 'c'], [1, 2]])
+        >>> idx.set_levels([['a', 'b', 'c'], [1, 2, 3, 4]], level=[0, 1])
         MultiIndex([('a', 1),
                     ('a', 2),
                     ('b', 1),
                     ('b', 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]])
         """
         if is_list_like(levels) and not isinstance(levels, Index):
             levels = list(levels)