ENH: MultiIndex.from_frame

doc/source/advanced.rst

@@ -62,8 +62,9 @@ The :class:`MultiIndex` object is the hierarchical analogue of the standard
 can think of ``MultiIndex`` as an array of tuples where each tuple is unique. A
 ``MultiIndex`` can be created from a list of arrays (using
 :meth:`MultiIndex.from_arrays`), an array of tuples (using
-:meth:`MultiIndex.from_tuples`), or a crossed set of iterables (using
-:meth:`MultiIndex.from_product`).  The ``Index`` constructor will attempt to return
+:meth:`MultiIndex.from_tuples`), a crossed set of iterables (using
+:meth:`MultiIndex.from_product`), or a :class:`DataFrame` (using 
+:meth:`MultiIndex.from_frame`).  The ``Index`` constructor will attempt to return
 a ``MultiIndex`` when it is passed a list of tuples.  The following examples
 demonstrate different ways to initialize MultiIndexes.
 
@@ -89,6 +90,19 @@ to use the :meth:`MultiIndex.from_product` method:
    iterables = [['bar', 'baz', 'foo', 'qux'], ['one', 'two']]
    pd.MultiIndex.from_product(iterables, names=['first', 'second'])
 
+You can also construct a ``MultiIndex`` from a ``DataFrame`` directly, using 
+the method :meth:`MultiIndex.from_frame`. This is a complementary method to
+:meth:`MultiIndex.to_frame`.
+
+.. versionadded:: 0.24.0
+
+.. ipython:: python
+
+   df = pd.DataFrame([['bar', 'one'], ['bar', 'two'],
+                      ['foo', 'one'], ['foo', 'two']],
+                     columns=['first', 'second'])
+   pd.MultiIndex.from_frame(df)
+
 As a convenience, you can pass a list of arrays directly into ``Series`` or
 ``DataFrame`` to construct a ``MultiIndex`` automatically:
 

doc/source/api.rst

@@ -1703,6 +1703,7 @@ MultiIndex Constructors
    MultiIndex.from_arrays
    MultiIndex.from_tuples
    MultiIndex.from_product
+   MultiIndex.from_frame
 
 MultiIndex Attributes
 ~~~~~~~~~~~~~~~~~~~~~

doc/source/whatsnew/v0.24.0.rst

@@ -378,6 +378,7 @@ Backwards incompatible API changes
 - Passing scalar values to :class:`DatetimeIndex` or :class:`TimedeltaIndex` will now raise ``TypeError`` instead of ``ValueError`` (:issue:`23539`)
 - ``max_rows`` and ``max_cols`` parameters removed from :class:`HTMLFormatter` since truncation is handled by :class:`DataFrameFormatter` (:issue:`23818`)
 - :meth:`read_csv` will now raise a ``ValueError`` if a column with missing values is declared as having dtype ``bool`` (:issue:`20591`)
+- The column order of the resultant :class:`DataFrame` from :meth:`MultiIndex.to_frame` is now guaranteed to match the :attr:`MultiIndex.names` order. (:issue:`22420`)
 
 .. _whatsnew_0240.api_breaking.deps:
 
@@ -1431,6 +1432,7 @@ MultiIndex
 
 - Removed compatibility for :class:`MultiIndex` pickles prior to version 0.8.0; compatibility with :class:`MultiIndex` pickles from version 0.13 forward is maintained (:issue:`21654`)
 - :meth:`MultiIndex.get_loc_level` (and as a consequence, ``.loc`` on a ``Series`` or ``DataFrame`` with a :class:`MultiIndex` index) will now raise a ``KeyError``, rather than returning an empty ``slice``, if asked a label which is present in the ``levels`` but is unused (:issue:`22221`)
+- :cls:`MultiIndex` has gained the :meth:`MultiIndex.from_frame`, it allows constructing a :cls:`MultiIndex` object from a :cls:`DataFrame` (:issue:`22420`)
 - Fix ``TypeError`` in Python 3 when creating :class:`MultiIndex` in which some levels have mixed types, e.g. when some labels are tuples (:issue:`15457`)
 
 I/O