BUG: pandas.read_excel creates a DataFrame with incorrect multi-level columns

[LastsForever]

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of pandas.

• (optional) I have confirmed this bug exists on the master branch of pandas.

---

Note: Please read this guide detailing how to provide the necessary information for us to reproduce your bug.

There is a file a.xlsx with only index and multi-level columns:

pd.read_excel('a.xlsx', index_col=0, header=[0, 1]) creates a DataFrame with incorrect multi-level columns:

However, if the file b.xlsx with the same structure (shown below) is not empty, the result appears to be correct:

Problem description

The parameter header=[0, 1] indicates that the first two rows of the excel file should be used as multi-level columns, but the result got first three rows as the multi-level columns.

Expected Output

pd.read_excel('a.xlsx', index_col=0, header=[0, 1]) should get the DataFrame:

Output of pd.show_versions()

INSTALLED VERSIONS

commit : None
python : 3.8.2.final.0
python-bits : 64
OS : Darwin
OS-release : 19.4.0
machine : x86_64
processor : i386
byteorder : little
LC_ALL : None
LANG : None
LOCALE : None.UTF-8

pandas : 1.0.3
numpy : 1.18.1
pytz : 2020.1
dateutil : 2.8.1
pip : 20.0.2
setuptools : 46.2.0.post20200511
Cython : None
pytest : None
hypothesis : None
sphinx : None
blosc : None
feather : None
xlsxwriter : None
lxml.etree : None
html5lib : None
pymysql : None
psycopg2 : None
jinja2 : 2.11.2
IPython : 7.13.0
pandas_datareader: None
bs4 : None
bottleneck : None
fastparquet : None
gcsfs : None
lxml.etree : None
matplotlib : 3.1.3
numexpr : None
odfpy : None
openpyxl : 3.0.3
pandas_gbq : None
pyarrow : None
pytables : None
pytest : None
pyxlsb : None
s3fs : None
scipy : None
sqlalchemy : None
tables : None
tabulate : None
xarray : None
xlrd : 1.2.0
xlwt : 1.3.0
xlsxwriter : None
numba : None

[rhshadrach]

Thanks for the report! It seems writing might have a related issue. Doing:

df = pd.DataFrame({'a': 3 * [None]}, index=[1, 2, 3])
df.columns = pd.MultiIndex.from_arrays([['A'], ['x']])
df.to_excel('test.xlsx')

produces an empty line below the columns. Reading this in produces the original DataFrame correctly. If I first delete this empty line and then read in the excel file, I get the issue mentioned above.

[ahawryluk]

It looks like this behaviour was intentional. The reader interprets the blank spaces the same way the writer does, and "in the case of column MultiIndex a blank row ALWAYS has to be inserted so the format is unambiguous. I believe this is unavoidable (csv does it too) - but the output looks a little odd if the index doesn't have names." #10967 (comment)

Also, #10967 (comment) points out this exact case as being ambiguous:

There's no way to know if "a" is the index name or if the data row is blank. Pandas assumes that "a" is the index name because that's how it writes named MulitIndex dataframes.

[rhshadrach]

Thanks @ahawryluk. I don't see any options that would improve upon this, but perhaps a note in the documentation of read_excel may be useful.