Repository: pandas-dev/pandas

Issue:
DOC: Document column order in MultiIndex.to_frame
```
conda create -q -n pandas1 python=3.6 pandas=0.23.4
source activate pandas1
```

```python
>>> import pandas as pd
>>> 
>>> pd.MultiIndex.from_tuples(
...     [("B1", "A1"), ("B2", "A1")], names=["B", "A"]
... ).to_frame()
        B   A
B  A         
B1 A1  B1  A1
B2 A1  B2  A1
```

```
conda create -q -n pandas2 python=3.5 pandas=0.23.4
source activate pandas2
```

```python
import pandas as pd

pd.MultiIndex.from_tuples(
    [("B1", "A1"), ("B2", "A1")], names=["B", "A"]
).to_frame()

        A   B
B  A         
B1 A1  A1  B1
B2 A1  A1  B2
```


#### Problem description
The ordering of columns from `pandas.MultiIndex.to_frame` varies in `python=3.5` vs `python=3.6` and the expected behaviour is not defined in the [docs](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.MultiIndex.to_frame.html).

#### Expected Output

I would expect columns to be in the order of the `MultiIndex` levels. Barring that I would expect the columns to be lexicographical sorted, although I find that to be less intuitive.

#### Output of ``pd.show_versions()``

<details>

```
INSTALLED VERSIONS
------------------
commit: None
python: 3.6.6.final.0
python-bits: 64
OS: Linux
OS-release: 4.15.0-33-generic
machine: x86_64
processor: x86_64
byteorder: little
LC_ALL: None
LANG: en_CA.UTF-8
LOCALE: en_CA.UTF-8

pandas: 0.23.4
pytest: None
pip: 10.0.1
setuptools: 40.2.0
Cython: None
numpy: 1.15.1
scipy: None
pyarrow: None
xarray: None
IPython: None
sphinx: None
patsy: None
dateutil: 2.7.3
pytz: 2018.5
blosc: None
bottleneck: None
tables: None
numexpr: None
feather: None
matplotlib: None
openpyxl: None
xlrd: None
xlwt: None
xlsxwriter: None
lxml: None
bs4: None
html5lib: None
sqlalchemy: None
pymysql: None
psycopg2: None
jinja2: None
s3fs: None
fastparquet: None
pandas_gbq: None
pandas_datareader: None
```
```
INSTALLED VERSIONS
------------------
commit: None
python: 3.5.6.final.0
python-bits: 64
OS: Linux
OS-release: 4.15.0-33-generic
machine: x86_64
processor: x86_64
byteorder: little
LC_ALL: None
LANG: en_CA.UTF-8
LOCALE: en_CA.UTF-8

pandas: 0.23.4
pytest: None
pip: 10.0.1
setuptools: 40.2.0
Cython: None
numpy: 1.15.1
scipy: None
pyarrow: None
xarray: None
IPython: None
sphinx: None
patsy: None
dateutil: 2.7.3
pytz: 2018.5
blosc: None
bottleneck: None
tables: None
numexpr: None
feather: None
matplotlib: None
openpyxl: None
xlrd: None
xlwt: None
xlsxwriter: None
lxml: None
bs4: None
html5lib: None
sqlalchemy: None
pymysql: None
psycopg2: None
jinja2: None
s3fs: None
fastparquet: None
pandas_gbq: None
pandas_datareader: None
```

</details>



Discussion:
That comes from http://pandas.pydata.org/pandas-docs/version/0.23/whatsnew.html#instantiation-from-dicts-preserves-dict-insertion-order-for-python-3-6.

Can you make a PR updating the docstring to indicate that the order follows the same results as the `DataFrame` constructor, and link to those docs?
Can do. @TomAugspurger, just to confirm, when you say link to those docs is the general practice to put that in a `See Also` section? Or actually add a hyperlink? i.e.

```
"""
Create a DataFrame with the levels of the MultiIndex as columns.
Column ordering is determined by the DataFrame constructor with data as a
dict.

.. versionadded:: 0.20.0

Parameters
----------
index : boolean, default True
    Set the index of the returned DataFrame as the original MultiIndex.

Returns
-------
DataFrame : a DataFrame containing the original MultiIndex data.

See also
--------
DataFrame
"""
```

vs

```
"""
Create a DataFrame with the levels of the MultiIndex as columns.
Column ordering is determined by the DataFrame constructor with data as a
dict.

.. versionadded:: 0.20.0

Parameters
----------
index : boolean, default True
    Set the index of the returned DataFrame as the original MultiIndex.

Returns
-------
DataFrame : a DataFrame containing the original MultiIndex data.

Notes
-----
A discussion on the ordering of DataFrames can be found at
https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html
"""
```
A see also is fine I think.

You'll need a blank line between to first and second lines to pass the
docstring validator.

On Tue, Sep 11, 2018 at 11:20 AM Matthew Gilbert <notifications@github.com>
wrote:

> Can do. Just to confirm, when you say link to those docs is the general
> practice to put that in a See Also section? Or actually add a hyperlink?
> i.e.
>
> """
> Create a DataFrame with the levels of the MultiIndex as columns.
> Column ordering is determined by the DataFrame constructor with data as a
> dict.
>
> .. versionadded:: 0.20.0
>
> Parameters
> ----------
> index : boolean, default True
>     Set the index of the returned DataFrame as the original MultiIndex.
>
> Returns
> -------
> DataFrame : a DataFrame containing the original MultiIndex data.
>
> See also
> --------
> DataFrame
> """
>
> vs
>
> """
> Create a DataFrame with the levels of the MultiIndex as columns.
> Column ordering is determined by the DataFrame constructor with data as a
> dict.
>
> .. versionadded:: 0.20.0
>
> Parameters
> ----------
> index : boolean, default True
>     Set the index of the returned DataFrame as the original MultiIndex.
>
> Returns
> -------
> DataFrame : a DataFrame containing the original MultiIndex data.
>
> Notes
> -----
> A discussion on the ordering of DataFrames can be found athttps://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html
> """
>
> —
> You are receiving this because you commented.
> Reply to this email directly, view it on GitHub
> <https://github.com/pandas-dev/pandas/issues/22662#issuecomment-420332428>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ABQHImUPMnNir-qkB_62hbazsUltch8uks5uZ-K0gaJpZM4WjjP5>
> .
>


Resolving patch:
diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py
--- a/pandas/core/indexes/multi.py
+++ b/pandas/core/indexes/multi.py
@@ -1130,6 +1130,9 @@ def to_frame(self, index=True):
         """
         Create a DataFrame with the levels of the MultiIndex as columns.
 
+        Column ordering is determined by the DataFrame constructor with data as
+        a dict.
+
         .. versionadded:: 0.20.0
 
         Parameters
@@ -1140,6 +1143,10 @@ def to_frame(self, index=True):
         Returns
         -------
         DataFrame : a DataFrame containing the original MultiIndex data.
+
+        See also
+        --------
+        DataFrame
         """
 
         from pandas import DataFrame


Test patch: