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

- [ ] closes #xxxx
- [ ] tests added / passed
- [x] 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:

```tex
\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](https://ctan.org/pkg/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:


```python
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:

```tex
\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:

![image](https://user-images.githubusercontent.com/36767735/52894669-0cf2a100-316b-11e9-8003-54298d8982cb.png)



Labels:
name: Output-Formatting
description: __repr__ of pandas objects, to_string

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25339?src=pr&el=h1) Report
> Merging [#25339](https://codecov.io/gh/pandas-dev/pandas/pull/25339?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/83fe6ca422ecc35f311897abedadcc492b2a0777?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `52.94%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/25339/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/25339?src=pr&el=tree)

```diff
@@            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%)` | :arrow_down: |
| #single | `41.71% <0%> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/25339?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/25339/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `94.16% <0%> (ø)` | :arrow_up: |
| [pandas/io/formats/format.py](https://codecov.io/gh/pandas-dev/pandas/pull/25339/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvZm9ybWF0LnB5) | `97.99% <100%> (ø)` | :arrow_up: |
| [pandas/io/formats/latex.py](https://codecov.io/gh/pandas-dev/pandas/pull/25339/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvbGF0ZXgucHk=) | `95.52% <45.45%> (-4.48%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25339?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25339?src=pr&el=footer). Last update [83fe6ca...7c105fa](https://codecov.io/gh/pandas-dev/pandas/pull/25339?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25339?src=pr&el=h1) Report
> Merging [#25339](https://codecov.io/gh/pandas-dev/pandas/pull/25339?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/83fe6ca422ecc35f311897abedadcc492b2a0777?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `52.94%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/25339/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/25339?src=pr&el=tree)

```diff
@@            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%)` | :arrow_down: |
| #single | `41.71% <0%> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/25339?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/25339/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `94.16% <0%> (ø)` | :arrow_up: |
| [pandas/io/formats/format.py](https://codecov.io/gh/pandas-dev/pandas/pull/25339/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvZm9ybWF0LnB5) | `97.99% <100%> (ø)` | :arrow_up: |
| [pandas/io/formats/latex.py](https://codecov.io/gh/pandas-dev/pandas/pull/25339/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvbGF0ZXgucHk=) | `95.52% <45.45%> (-4.48%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25339?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25339?src=pr&el=footer). Last update [83fe6ca...7c105fa](https://codecov.io/gh/pandas-dev/pandas/pull/25339?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

@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?
@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
Thanks @WillAyd I created issue [#25436](https://github.com/pandas-dev/pandas/issues/25436) and will create a new PR because the scope has increased.