ENH: Added multicolumn/multirow support for latex

- [X] closes pandas-dev#13508
- [X] tests added / passed
- [X] passes `git diff upstream/master | flake8 --diff`
- [X] whatsnew entry

Print names of MultiIndex columns.
Added "multicolumn" and "multirow" flags to to_latex
which trigger the corresponding feature.
"multicolumn_format" is used to select alignment.
Multirow adds clines to visually separate sections.

Author: sgsaenger

doc/source/whatsnew/v0.20.0.txt

@@ -141,6 +141,7 @@ Other enhancements
 - ``Timedelta.isoformat`` method added for formatting Timedeltas as an `ISO 8601 duration`_. See the :ref:`Timedelta docs <timedeltas.isoformat>` (:issue:`15136`)
 - ``pandas.io.json.json_normalize()`` gained the option ``errors='ignore'|'raise'``; the default is ``errors='raise'`` which is backward compatible. (:issue:`14583`)
 - ``.select_dtypes()`` now allows the string 'datetimetz' to generically select datetimes with tz (:issue:`14910`)
+- The ``.to_latex()`` method will now accept ``multicolumn`` and ``multirow`` arguments to use the accompanying LaTeX enhancements
 - ``pd.merge_asof()`` gained the option ``direction='backward'|'forward'|'nearest'`` (:issue:`14887`)
 - ``Series/DataFrame.asfreq()`` have gained a ``fill_value`` parameter, to fill missing values (:issue:`3715`).
 - ``Series/DataFrame.resample.asfreq`` have gained a ``fill_value`` parameter, to fill missing values during resampling (:issue:`3715`).

pandas/core/config_init.py

@@ -249,6 +249,27 @@
     method. Valid values: False,True
 """
 
+pc_latex_multicolumn = """
+: bool
+    This specifies if the to_latex method of a Dataframe uses multicolumns
+    to pretty-print MultiIndex columns.
+    method. Valid values: False,True
+"""
+
+pc_latex_multicolumn_format = """
+: string
+    This specifies the format for multicolumn headers.
+    Can be surrounded with '|'.
+    Valid values: 'l', 'c', 'r', 'p{<width>}'
+"""
+
+pc_latex_multirow = """
+: bool
+    This specifies if the to_latex method of a Dataframe uses multirows
+    to pretty-print MultiIndex rows.
+    method. Valid values: False,True
+"""
+
 style_backup = dict()
 
 
@@ -338,6 +359,12 @@ def mpl_style_cb(key):
                        validator=is_bool)
     cf.register_option('latex.longtable', False, pc_latex_longtable,
                        validator=is_bool)
+    cf.register_option('latex.multicolumn', True, pc_latex_multicolumn,
+                       validator=is_bool)
+    cf.register_option('latex.multicolumn_format', 'l', pc_latex_multicolumn,
+                       validator=is_text)
+    cf.register_option('latex.multirow', False, pc_latex_multirow,
+                       validator=is_bool)
 
 cf.deprecate_option('display.line_width',
                     msg=pc_line_width_deprecation_warning,

pandas/core/frame.py

@@ -1577,10 +1577,11 @@ def to_latex(self, buf=None, columns=None, col_space=None, header=True,
                  index=True, na_rep='NaN', formatters=None, float_format=None,
                  sparsify=None, index_names=True, bold_rows=True,
                  column_format=None, longtable=None, escape=None,
-                 encoding=None, decimal='.'):
-        """
+                 encoding=None, decimal='.', multicolumn=None,
+                 multicolumn_format=None, multirow=None):
+        r"""
         Render a DataFrame to a tabular environment table. You can splice
-        this into a LaTeX document. Requires \\usepackage{booktabs}.
+        this into a LaTeX document. Requires \usepackage{booktabs}.
 
         `to_latex`-specific options:
 
@@ -1593,7 +1594,7 @@ def to_latex(self, buf=None, columns=None, col_space=None, header=True,
         longtable : boolean, default will be read from the pandas config module
             default: False
             Use a longtable environment instead of tabular. Requires adding
-            a \\usepackage{longtable} to your LaTeX preamble.
+            a \usepackage{longtable} to your LaTeX preamble.
         escape : boolean, default will be read from the pandas config module
             default: True
             When set to False prevents from escaping latex special
@@ -1606,12 +1607,37 @@ def to_latex(self, buf=None, columns=None, col_space=None, header=True,
 
             .. versionadded:: 0.18.0
 
+        multicolumn : boolean, default True
+            default will be read from the config module
+            Use \multicolumn to enhance MultiIndex columns.
+
+            .. versionadded:: 0.20.0
+
+        multicolumn_format : str, default 'l'
+            default will be read from the config module
+            The alignment for multicolumns, similar to column_format
+
+            .. versionadded:: 0.20.0
+
+        multirow : boolean, default False
+            default will be read from the pandas config module
+            Use \multirow to enhance MultiIndex rows. Requires adding a
+            \usepackage{multirow} to your LaTeX preamble.
+
+            .. versionadded:: 0.20.0
+
         """
         # Get defaults from the pandas config
         if longtable is None:
             longtable = get_option("display.latex.longtable")
         if escape is None:
             escape = get_option("display.latex.escape")
+        if multicolumn is None:
+            multicolumn = get_option("display.latex.multicolumn")
+        if multicolumn_format is None:
+            multicolumn_format = get_option("display.latex.multicolumn_format")
+        if multirow is None:
+            multirow = get_option("display.latex.multirow")
 
         formatter = fmt.DataFrameFormatter(self, buf=buf, columns=columns,
                                            col_space=col_space, na_rep=na_rep,
@@ -1623,7 +1649,9 @@ def to_latex(self, buf=None, columns=None, col_space=None, header=True,
                                            index_names=index_names,
                                            escape=escape, decimal=decimal)
         formatter.to_latex(column_format=column_format, longtable=longtable,
-                           encoding=encoding)
+                           encoding=encoding, multicolumn=multicolumn,
+                           multicolumn_format=multicolumn_format,
+                           multirow=multirow)
 
         if buf is None:
             return formatter.buf.getvalue()

pandas/formats/format.py

@@ -646,13 +646,17 @@ def _join_multiline(self, *strcols):
             st = ed
         return '\n\n'.join(str_lst)
 
-    def to_latex(self, column_format=None, longtable=False, encoding=None):
+    def to_latex(self, column_format=None, longtable=False, encoding=None,
+                 multicolumn=False, multicolumn_format=None, multirow=False):
         """
         Render a DataFrame to a LaTeX tabular/longtable environment output.
         """
 
         latex_renderer = LatexFormatter(self, column_format=column_format,
-                                        longtable=longtable)
+                                        longtable=longtable,
+                                        multicolumn=multicolumn,
+                                        multicolumn_format=multicolumn_format,
+                                        multirow=multirow)
 
         if encoding is None:
             encoding = 'ascii' if compat.PY2 else 'utf-8'
@@ -820,11 +824,15 @@ class LatexFormatter(TableFormatter):
     HTMLFormatter
     """
 
-    def __init__(self, formatter, column_format=None, longtable=False):
+    def __init__(self, formatter, column_format=None, longtable=False,
+                 multicolumn=False, multicolumn_format=None, multirow=False):
         self.fmt = formatter
         self.frame = self.fmt.frame
         self.column_format = column_format
         self.longtable = longtable
+        self.multicolumn = multicolumn
+        self.multicolumn_format = multicolumn_format
+        self.multirow = multirow
 
     def write_result(self, buf):
         """
@@ -846,14 +854,21 @@ def get_col_type(dtype):
             else:
                 return 'l'
 
+        # reestablish the MultiIndex that has been joined by _to_str_column
         if self.fmt.index and isinstance(self.frame.index, MultiIndex):
             clevels = self.frame.columns.nlevels
             strcols.pop(0)
             name = any(self.frame.index.names)
+            cname = any(self.frame.columns.names)
+            lastcol = self.frame.index.nlevels - 1
             for i, lev in enumerate(self.frame.index.levels):
                 lev2 = lev.format()
                 blank = ' ' * len(lev2[0])
-                lev3 = [blank] * clevels
+                # display column names in last index-column
+                if cname and i == lastcol:
+                    lev3 = [x if x else '{}' for x in self.frame.columns.names]
+                else:
+                    lev3 = [blank] * clevels
                 if name:
                     lev3.append(lev.name)
                 for level_idx, group in itertools.groupby(
@@ -873,6 +888,7 @@ def get_col_type(dtype):
                             compat.string_types):  # pragma: no cover
             raise AssertionError('column_format must be str or unicode, not %s'
                                  % type(column_format))
+        multicolumn_format = self.multicolumn_format
 
         if not self.longtable:
             buf.write('\\begin{tabular}{%s}\n' % column_format)
@@ -881,10 +897,15 @@ def get_col_type(dtype):
             buf.write('\\begin{longtable}{%s}\n' % column_format)
             buf.write('\\toprule\n')
 
-        nlevels = self.frame.columns.nlevels
+        ilevels = self.frame.index.nlevels
+        clevels = self.frame.columns.nlevels
+        nlevels = clevels
         if any(self.frame.index.names):
             nlevels += 1
-        for i, row in enumerate(zip(*strcols)):
+        strrows = list(zip(*strcols))
+        clinebuf = []
+
+        for i, row in enumerate(strrows):
             if i == nlevels and self.fmt.header:
                 buf.write('\\midrule\n')  # End of header
                 if self.longtable:
@@ -906,8 +927,59 @@ def get_col_type(dtype):
                          if x else '{}') for x in row]
             else:
                 crow = [x if x else '{}' for x in row]
+            if i < clevels and self.fmt.header and self.multicolumn:
+                # sum up columns to multicolumns
+                row2 = list(crow[:ilevels])
+                ncol = 1
+                coltext = ''
+
+                def append_col():
+                    # write multicolumn if needed
+                    if ncol > 1:
+                        row2.append('\\multicolumn{{{0:d}}}{{{1:s}}}{{{2:s}}}'
+                                    .format(ncol, multicolumn_format,
+                                            coltext.strip()))
+                    # don't modify where not needed
+                    else:
+                        row2.append(coltext)
+                for c in crow[ilevels:]:
+                    if c.strip():  # if next col has text, write the previous
+                        if coltext:
+                            append_col()
+                        coltext = c
+                        ncol = 1
+                    else:  # if not, add it to the previous multicolumn
+                        ncol += 1
+                if coltext:  # write last column name
+                    append_col()
+                crow = row2
+            if i >= nlevels and self.fmt.index and self.multirow:
+                # perform look-ahead to determine which rows can be joined
+                for j in range(ilevels):
+                    if crow[j].strip():
+                        nrow = 1
+                        for r in strrows[i + 1:]:
+                            if not r[j].strip():
+                                nrow += 1
+                            else:
+                                break
+                        if nrow > 1:
+                            # overwrite non-multirow entry
+                            crow[j] = '\\multirow{{{0:d}}}{{*}}{{{1:s}}}'\
+                                      .format(nrow, crow[j].strip())
+                            # save when to end the current block with \cline
+                            clinebuf.append([nrow, j + 1])
             buf.write(' & '.join(crow))
             buf.write(' \\\\\n')
+            if self.multirow and i < len(strrows) - 1:
+                # during main block, check if sub-block transition takes place
+                # print \cline to distinguish \multirow-areas
+                for cl in clinebuf:
+                    cl[0] -= 1
+                    if cl[0] == 0:
+                        buf.write('\cline{{{0:d}-{1:d}}}\n'.format(cl[1],
+                                  len(strcols)))
+                clinebuf = [x for x in clinebuf if x[0]]
 
         if not self.longtable:
             buf.write('\\bottomrule\n')

pandas/tests/formats/test_format.py

@@ -3571,6 +3571,67 @@ def test_to_latex_multiindex(self):
 
         self.assertEqual(result, expected)
 
+    def test_to_latex_multicolumnrow(self):
+        df = pd.DataFrame({
+                    ('c1',0):dict((x,x) for x in range(5)),
+                    ('c1',1):dict((x,x+5) for x in range(5)),
+                    ('c2',0):dict((x,x) for x in range(5)),
+                    ('c2',1):dict((x,x+5) for x in range(5)),
+                    ('c3',0):dict((x,x) for x in range(5))
+                    })
+        result = df.to_latex(multicolumn=True)
+        expected = r"""\begin{tabular}{lrrrrr}
+\toprule
+{} & \multicolumn{2}{l}{c1} & \multicolumn{2}{l}{c2} & c3 \\
+{} &  0 &  1 &  0 &  1 &  0 \\
+\midrule
+0 &  0 &  5 &  0 &  5 &  0 \\
+1 &  1 &  6 &  1 &  6 &  1 \\
+2 &  2 &  7 &  2 &  7 &  2 \\
+3 &  3 &  8 &  3 &  8 &  3 \\
+4 &  4 &  9 &  4 &  9 &  4 \\
+\bottomrule
+\end{tabular}
+"""
+        self.assertEqual(result, expected)
+
+        result = df.T.to_latex(multirow=True)
+        expected = r"""\begin{tabular}{llrrrrr}
+\toprule
+   &   &  0 &  1 &  2 &  3 &  4 \\
+\midrule
+\multirow{2}{*}{c1} & 0 &  0 &  1 &  2 &  3 &  4 \\
+   & 1 &  5 &  6 &  7 &  8 &  9 \\
+\cline{1-7}
+\multirow{2}{*}{c2} & 0 &  0 &  1 &  2 &  3 &  4 \\
+   & 1 &  5 &  6 &  7 &  8 &  9 \\
+\cline{1-7}
+c3 & 0 &  0 &  1 &  2 &  3 &  4 \\
+\bottomrule
+\end{tabular}
+"""
+        self.assertEqual(result, expected)
+
+        df.index = df.T.index
+        result = df.T.to_latex(multirow=True, multicolumn=True,
+                               multicolumn_format='c')
+        expected = r"""\begin{tabular}{llrrrrr}
+\toprule
+   &   & \multicolumn{2}{c}{c1} & \multicolumn{2}{c}{c2} & c3 \\
+   &   &  0 &  1 &  0 &  1 &  0 \\
+\midrule
+\multirow{2}{*}{c1} & 0 &  0 &  1 &  2 &  3 &  4 \\
+   & 1 &  5 &  6 &  7 &  8 &  9 \\
+\cline{1-7}
+\multirow{2}{*}{c2} & 0 &  0 &  1 &  2 &  3 &  4 \\
+   & 1 &  5 &  6 &  7 &  8 &  9 \\
+\cline{1-7}
+c3 & 0 &  0 &  1 &  2 &  3 &  4 \\
+\bottomrule
+\end{tabular}
+"""
+        self.assertEqual(result, expected)
+
     def test_to_latex_escape(self):
         a = 'a'
         b = 'b'