ENH: .to_latex(longtable=True) latex caption and label support

[jeschwar]

• closes #xxxx
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

When creating a latex table with DataFrame.to_latex(longtable=False) the output is written inside a latex tabular environment and stored in some file like pandas_tabular.tex; the user can conveniently typeset the table in a main report.tex file complete with caption and label as follows:

\begin{table}
\caption{the caption}
\label{the label}
\input{pandas_tabular.tex}
\end{table}

This is good because the pandas_tabular.tex file can be re-created and the main report.tex simply needs to be recompiled to get the updated output.

The problem when creating a latex longtable with DataFrame.to_latex(longtable=True) is the caption and label need to go inside the latex longtable environment which is stored in a some file like pandas_longtable.tex. The latex longtable environment does not go inside a table environment like the tabular environment does; this means that setting the caption and label requires the user to edit the pandas_longtable.tex file after its creation. This does not support an automated workflow like we have with the tabular environment.

This PR adds caption and label support to DataFrame.to_latex(longtable=True) with the arguments lt_caption and lt_label. Example usage is described below.

The following python code creates some data in a DataFrame and writes it to disk in tabular and longtable latex environments:

import numpy as np
import pandas as pd


# create some example data with more rows than would fit on a single page
df = pd.DataFrame(np.random.randn(60,3))

# write the first 5 rows to regular table in a latex tabular environment
df.head().to_latex(
    'pandas_tabular.tex',
)

# write the whole table in the latex longtable environment c/w caption and label
df.to_latex(
    'pandas_longtable.tex',
    longtable=True,
    lt_caption='table in \\texttt{longtable} environment',
    lt_label='tab:longtable',
)

The following latex code is contained in a main report.tex and is used to typset both tables:

\documentclass{article}

\usepackage{longtable}
\usepackage{booktabs}

\begin{document}

% typeset the table in the tabular environment
Table \ref{tab:tabular}	is a \texttt{tabular} and has 5 rows:
\begin{table}[h]	
\centering	
\caption{table in \texttt{tabular} environment}
\label{tab:tabular}
\input{pandas_tabular.tex}	
\end{table}

% typeset the table in the longtable environment
Table \ref{tab:longtable} is a \texttt{longtable} and has 60 rows:
\input{pandas_longtable.tex}
\end{document}

Using DataFrame.to_latex(longtable=True) with the new arguments lt_caption and lt_label means we don't have to edit pandas_longtable.tex after its creation to get the caption and label working. This functionality also works with Series.to_latex(longtable=True).

PDF output is shown below:

[codecov]

Codecov Report

Merging #25339 into master will decrease coverage by <.01%.
The diff coverage is 52.94%.

@@            Coverage Diff             @@
##           master   #25339      +/-   ##
==========================================
- Coverage   91.72%   91.71%   -0.01%     
==========================================
  Files         173      173              
  Lines       52831    52842      +11     
==========================================
+ Hits        48457    48462       +5     
- Misses       4374     4380       +6

Flag	Coverage Δ
#multiple	90.27% <52.94%> (-0.01%)	⬇️
#single	41.71% <0%> (-0.01%)	⬇️

Impacted Files	Coverage Δ
pandas/core/generic.py	94.16% <0%> (ø)	⬆️
pandas/io/formats/format.py	97.99% <100%> (ø)	⬆️
pandas/io/formats/latex.py	95.52% <45.45%> (-4.48%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 83fe6ca...7c105fa. Read the comment docs.

[codecov]

Codecov Report

Merging #25339 into master will decrease coverage by <.01%.
The diff coverage is 52.94%.

@@            Coverage Diff             @@
##           master   #25339      +/-   ##
==========================================
- Coverage   91.72%   91.71%   -0.01%     
==========================================
  Files         173      173              
  Lines       52831    52842      +11     
==========================================
+ Hits        48457    48462       +5     
- Misses       4374     4380       +6

Flag	Coverage Δ
#multiple	90.27% <52.94%> (-0.01%)	⬇️
#single	41.71% <0%> (-0.01%)	⬇️

Impacted Files	Coverage Δ
pandas/core/generic.py	94.16% <0%> (ø)	⬆️
pandas/io/formats/format.py	97.99% <100%> (ø)	⬆️
pandas/io/formats/latex.py	95.52% <45.45%> (-4.48%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 83fe6ca...7c105fa. Read the comment docs.

[jreback]

is label / caption useful to a tabular write?

you would need to add a test for this

[jeschwar]

@jreback that is a good suggestion to allow the label and caption arguments to apply to the latex table environment when longtable=False. This means that DataFrame.to_latex() would have to write the nested latex table/tabular environments in the output; this may be ok for most uses. Here is what I am thinking for possible scenarios and corresponding behavior:

.to_latex(longtable=False, caption=None, label=None)

• only output the latex tabular environment which is the current behavior

.to_latex(longtable=True, caption=None, label=None)

• output the latex longtable environment without any captions or labels which the the current behavior

.to_latex(longtable=False, caption='some caption', label='tab:some label')

• output the latex nested table/tabular environments which include the caption and label from the user
• this code could be added to this PR
• if the user wants to add customized latex code inside the table environment but outside the tabular environment then they should not pass values for the caption and label arguments

.to_latex(longtable=True, caption='some caption', label='tab:some label')

• output the latex longtable environment which includes the caption and label from the user as initially described in this PR

Thoughts anyone?

[WillAyd]

@jeschwar not a LaTeX expert by any means but your proposal makes sense. Can you open as an issue and reference that from this PR? That is typically easiest for change management

[jeschwar]

Thanks @WillAyd I created issue #25436 and will create a new PR because the scope has increased.