ENH: Correct use of `longtable`, `label`, and `caption` with LaTeX

[jdossgollin]

Is your feature request related to a problem?

Currently DataFrame.to_latex() has a longtable argument, which writes the DataFrame to latex using the syntax of the longtable package. When used with the label and caption arguments, it writes a latex table with all of these features.

However, the caption and label are both placed between a \begin{longtable} line and \endhead. As a consequence, the table appears twice in the listoftables and leads to warnings about the reference being multiply defined

Describe the solution you'd like

the .to_latex() method when longtable=True and caption=X and label=Y should print out as follows

\begin{longtable}{...}% alignment characters
\caption{Caption here}\label{label-here}
\endfirsthead
\caption{Caption here}
\endhead

This will prevent a separate label from being defined multiple times in latex (once for each page the caption is printed on). See page 5 of http://www.texdoc.net/texmf-dist/doc/latex/tools/longtable.pdf.

API breaking implications

None

Describe alternatives you've considered

An alternative is to set the caption and label to False, and to add them myself. This works but defeats the purpose of calling the .to_latex() API

[TomAugspurger]

cc @SylvainLan and @jeschwar if either of you have thoughts.

@jdossgollin it'd be helpful if you provide a minimal example constructing a small DataFrame and showing the output http://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-report.

[jdossgollin]

Sure thing.

import pandas as pd
df = pd.DataFrame({"a": range(5), "b": range(5)})
print(df.to_latex(longtable=True, caption="longtable data frame", label="tab:demo"))

gives

\begin{longtable}{lrr}
\caption{longtable data frame}\label{tab:demo}\\
\toprule
{} &  a &  b \\
\midrule
\endhead
\midrule
\multicolumn{3}{r}{{Continued on next page}} \\
\midrule
\endfoot

\bottomrule
\endlastfoot
0 &  0 &  0 \\
1 &  1 &  1 \\
2 &  2 &  2 \\
3 &  3 &  3 \\
4 &  4 &  4 \\
\end{longtable}

I would like instead for the table to show

\begin{longtable}{lrr}
\caption{longtable data frame}\label{tab:demo}\\
\toprule
{} &   a &   b \\
\midrule
\endfirsthead
% now repeat everything from above, but add a [] to the caption and don't print the label
\caption[]{Desired behavior with a very long longtable}\\ % the [] here keeps it from showing up again in \listoftables
\toprule % identical
{} &   a &   b \\ % identical
\midrule % identical
\endhead
...

Here's a live example of how the difference plays out in a document: https://www.overleaf.com/read/wyypsqptyqvb

[jeschwar]

@jdossgollin thanks for identifying this. I didn't give the repeated entries in the List of Tables much thought initially because the table is indeed occupying multiple pages. I can take this and revise such that the List of Tables looks cleaner. Thanks for doing all the hard work!

[jeschwar]

take

[jdossgollin]

thanks for taking this on!