From b2d23687e5001329f8ae953ce2b44ec0e687140c Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sat, 16 Nov 2019 19:34:13 -0600 Subject: [PATCH] DOC: Update MultiIndex.names whatsnew (#29572) --- doc/source/user_guide/advanced.rst | 25 +++++++++++++++++ doc/source/whatsnew/v1.0.0.rst | 45 +++++++++++++++++------------- 2 files changed, 50 insertions(+), 20 deletions(-) diff --git a/doc/source/user_guide/advanced.rst b/doc/source/user_guide/advanced.rst index c6eadd2adadce4..31bb71064d7356 100644 --- a/doc/source/user_guide/advanced.rst +++ b/doc/source/user_guide/advanced.rst @@ -554,6 +554,31 @@ index. Both ``rename`` and ``rename_axis`` support specifying a dictionary, ``Series`` or a mapping function to map labels/names to new values. +When working with an ``Index`` object directly, rather than via a ``DataFrame``, +:meth:`Index.set_names` can be used to change the names. + +.. ipython:: python + + mi = pd.MultiIndex.from_product([[1, 2], ['a', 'b']], names=['x', 'y']) + mi.names + + mi2 = mi.rename("new name", level=0) + mi2 + +.. warning:: + + Prior to pandas 1.0.0, you could also set the names of a ``MultiIndex`` + by updating the name of a level. + + .. code-block:: none + + >>> mi.levels[0].name = 'name via level' + >>> mi.names[0] # only works for older panads + 'name via level' + + As of pandas 1.0, this will *silently* fail to update the names + of the MultiIndex. Use :meth:`Index.set_names` instead. + Sorting a ``MultiIndex`` ------------------------ diff --git a/doc/source/whatsnew/v1.0.0.rst b/doc/source/whatsnew/v1.0.0.rst index a5b459f3372e64..c91ced1014dd13 100644 --- a/doc/source/whatsnew/v1.0.0.rst +++ b/doc/source/whatsnew/v1.0.0.rst @@ -130,34 +130,39 @@ Backwards incompatible API changes .. _whatsnew_1000.api_breaking.MultiIndex._names: -``MultiIndex.levels`` do not hold level names any longer -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Avoid using names from ``MultiIndex.levels`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- A :class:`MultiIndex` previously stored the level names as attributes of each of its - :attr:`MultiIndex.levels`. From Pandas 1.0, the names are only accessed through - :attr:`MultiIndex.names` (which was also possible previously). This is done in order to - make :attr:`MultiIndex.levels` more similar to :attr:`CategoricalIndex.categories` (:issue:`27242`:). +As part of a larger refactor to :class:`MultiIndex` the level names are now +stored separately from the levels (:issue:`27242`). We recommend using +:attr:`MultiIndex.names` to access the names, and :meth:`Index.set_names` +to update the names. -*pandas 0.25.x* +For backwards compatibility, you can still *access* the names via the levels. -.. code-block:: ipython +.. ipython:: python - In [1]: mi = pd.MultiIndex.from_product([[1, 2], ['a', 'b']], names=['x', 'y']) - Out[2]: mi - MultiIndex([(1, 'a'), - (1, 'b'), - (2, 'a'), - (2, 'b')], - names=['x', 'y']) - Out[3]: mi.levels[0].name - 'x' + mi = pd.MultiIndex.from_product([[1, 2], ['a', 'b']], names=['x', 'y']) + mi.levels[0].name -*pandas 1.0.0* +However, it is no longer possible to *update* the names of the ``MultiIndex`` +via the name of the level. The following will **silently** fail to update the +name of the ``MultiIndex`` .. ipython:: python - mi = pd.MultiIndex.from_product([[1, 2], ['a', 'b']], names=['x', 'y']) - mi.levels[0].name + mi.levels[0].name = "new name" + mi.names + +To update, use ``MultiIndex.set_names``, which returns a new ``MultiIndex``. + +.. ipython:: python + + mi2 = mi.set_names("new name", level=0) + mi2.names + +New repr for :class:`pandas.core.arrays.IntervalArray` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - :class:`pandas.core.arrays.IntervalArray` adopts a new ``__repr__`` in accordance with other array classes (:issue:`25022`)