From fadf5e7cfcf2a0a8a9c762e802efb3f5d03f9f07 Mon Sep 17 00:00:00 2001 From: Thierry Moisan Date: Sun, 26 Aug 2018 15:27:46 -0400 Subject: [PATCH 1/4] DOC: Fix to_latex docstring. --- pandas/core/generic.py | 107 +++++++++++++++++++++++++++-------------- 1 file changed, 70 insertions(+), 37 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 85bd6065314f4..3edb1f7b9c58a 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -2521,69 +2521,102 @@ def to_xarray(self): coords=coords, ) - _shared_docs['to_latex'] = r""" + 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=False, + column_format=None, longtable=None, escape=None, + encoding=None, decimal='.', multicolumn=None, + multicolumn_format=None, multirow=None): + r""" Render an object to a tabular environment table. You can splice - this into a LaTeX document. Requires \\usepackage{booktabs}. + this into a LaTeX document. Requires \usepackage{booktabs}. .. versionchanged:: 0.20.2 Added to Series - `to_latex`-specific options: - + Parameters + ---------- + buf : StringIO-like, optional + Buffer to write to. + columns : sequence, optional, default None + The subset of columns to write. Writes all columns by default. + col_space : int, optional + The minimum width of each column. + header : bool or list of str, default True + Write out the column names. If a list of strings is given, + it is assumed to be aliases for the column names. + index : bool, default True + Write row names (index). + na_rep : str, default 'NaN' + Missing data representation. + formatters : list or dict of one-param. functions, optional + Formatter functions to apply to columns' elements by position or + name. The result of each function must be a unicode string. + List must be of length equal to the number of columns. + float_format : str, default None + Format string for floating point numbers. + sparsify : bool, optional, default None + Set to False for a DataFrame with a hierarchical index to print + every multiindex key at each row. + index_names : bool, optional, default True + Prints the names of the indexes. bold_rows : boolean, default False - Make the row labels bold in the output + Make the row labels bold in the output. column_format : str, default None The columns format as specified in `LaTeX table format - `__ e.g 'rcl' for 3 - columns - 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. - escape : boolean, default will be read from the pandas config module + `__ e.g. 'rcl' for 3 + columns. + longtable : bool, default None + When set to None, the value will default from the pandas config + module. Use a longtable environment instead of tabular. Requires + adding a \usepackage{longtable} to your LaTeX preamble. + escape : bool, default will be read from the pandas config module Default: True. When set to False prevents from escaping latex special characters in column names. encoding : str, default None A string representing the encoding to use in the output file, defaults to 'ascii' on Python 2 and 'utf-8' on Python 3. - decimal : string, default '.' + decimal : str, default '.' Character recognized as decimal separator, e.g. ',' in Europe. - .. versionadded:: 0.18.0 - - multicolumn : boolean, default True + multicolumn : bool, default True Use \multicolumn to enhance MultiIndex columns. The default will be read from the config module. - .. versionadded:: 0.20.0 - multicolumn_format : str, default 'l' The alignment for multicolumns, similar to `column_format` The default will be read from the config module. - + .. versionadded:: 0.20.0 + multirow : bool, default False + Use \multirow to enhance MultiIndex rows. Requires adding a + \usepackage{multirow} to your LaTeX preamble. Will print + centered labels (instead of top-aligned) across the contained + rows, separating groups via clines. The default will be read + from the pandas config module. .. versionadded:: 0.20.0 - multirow : boolean, default False - Use \multirow to enhance MultiIndex rows. - Requires adding a \\usepackage{multirow} to your LaTeX preamble. - Will print centered labels (instead of top-aligned) - across the contained rows, separating groups via clines. - The default will be read from the pandas config module. + Returns + ------- + str or None + If buf is None, returns the resulting LateX format as a + string. Otherwise returns None. - .. versionadded:: 0.20.0 - """ + See Also + -------- + DataFrame.to_csv : Write a DataFrame to CSV format. + DataFrame.to_excel : Write a DataFrame to an Excel file. - @Substitution(header='Write out the column names. If a list of strings ' - 'is given, it is assumed to be aliases for the ' - 'column names.') - @Appender(_shared_docs['to_latex'] % _shared_doc_kwargs) - 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=False, - column_format=None, longtable=None, escape=None, - encoding=None, decimal='.', multicolumn=None, - multicolumn_format=None, multirow=None): + Examples + -------- + >>> df = pd.DataFrame({'name': ['Raphael', 'Donatello'], + ... 'mask': ['red', 'purple'], + ... 'weapon': ['sai', 'bo staff']}) + >>> df.to_latex(index=False) # doctest: +NORMALIZE_WHITESPACE + '\\begin{tabular}{lll}\n\\toprule\n name & mask & weapon + \\\\\n\\midrule\n Raphael & red & sai \\\\\n Donatello & + purple & bo staff \\\\\n\\bottomrule\n\\end{tabular}\n' + """ # Get defaults from the pandas config if self.ndim == 1: self = self.to_frame() From 8d59ef47538c5f8ac4db6050da15ff9b0f2f732a Mon Sep 17 00:00:00 2001 From: Thierry Moisan Date: Mon, 27 Aug 2018 22:00:55 -0400 Subject: [PATCH 2/4] Improve to_latex docstring after PR comments --- pandas/core/generic.py | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 3edb1f7b9c58a..43bb0ac7af990 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -2536,9 +2536,9 @@ def to_latex(self, buf=None, columns=None, col_space=None, header=True, Parameters ---------- - buf : StringIO-like, optional - Buffer to write to. - columns : sequence, optional, default None + buf : file descriptor or None + Buffer to write to. If None, the output is returned as a string. + columns : list of label, optional The subset of columns to write. Writes all columns by default. col_space : int, optional The minimum width of each column. @@ -2549,18 +2549,19 @@ def to_latex(self, buf=None, columns=None, col_space=None, header=True, Write row names (index). na_rep : str, default 'NaN' Missing data representation. - formatters : list or dict of one-param. functions, optional + formatters : list of functions or dict of {str: function}, optional Formatter functions to apply to columns' elements by position or name. The result of each function must be a unicode string. List must be of length equal to the number of columns. - float_format : str, default None + float_format : str, optional Format string for floating point numbers. sparsify : bool, optional, default None Set to False for a DataFrame with a hierarchical index to print - every multiindex key at each row. - index_names : bool, optional, default True + every multiindex key at each row. If None, the default will be + read from the config module. + index_names : bool, default True Prints the names of the indexes. - bold_rows : boolean, default False + bold_rows : bool, default False Make the row labels bold in the output. column_format : str, default None The columns format as specified in `LaTeX table format @@ -2570,8 +2571,8 @@ def to_latex(self, buf=None, columns=None, col_space=None, header=True, When set to None, the value will default from the pandas config module. Use a longtable environment instead of tabular. Requires adding a \usepackage{longtable} to your LaTeX preamble. - escape : bool, default will be read from the pandas config module - Default: True. + escape : bool, default None + If None, default will be read from the pandas config module. When set to False prevents from escaping latex special characters in column names. encoding : str, default None @@ -2604,8 +2605,9 @@ def to_latex(self, buf=None, columns=None, col_space=None, header=True, See Also -------- - DataFrame.to_csv : Write a DataFrame to CSV format. - DataFrame.to_excel : Write a DataFrame to an Excel file. + DataFrame.to_string : Render a DataFrame to a console-friendly + tabular output. + DataFrame.to_html : Render a DataFrame as an HTML table. Examples -------- From 052a32f3bca07c47a17d845c62178efb2ad16c69 Mon Sep 17 00:00:00 2001 From: Thierry Moisan Date: Tue, 4 Sep 2018 13:36:09 -0400 Subject: [PATCH 3/4] Use optional instead of 'default None' when None is just a flag. Also add doc for column_format defaults --- pandas/core/generic.py | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 43bb0ac7af990..cf62dd6cbc54b 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -2555,27 +2555,28 @@ def to_latex(self, buf=None, columns=None, col_space=None, header=True, List must be of length equal to the number of columns. float_format : str, optional Format string for floating point numbers. - sparsify : bool, optional, default None + sparsify : bool, optional Set to False for a DataFrame with a hierarchical index to print - every multiindex key at each row. If None, the default will be + every multiindex key at each row. By default, the value will be read from the config module. index_names : bool, default True Prints the names of the indexes. bold_rows : bool, default False Make the row labels bold in the output. - column_format : str, default None + column_format : str, optional The columns format as specified in `LaTeX table format `__ e.g. 'rcl' for 3 - columns. - longtable : bool, default None - When set to None, the value will default from the pandas config + columns. By default, 'l' will be used for all columns except + columns of numbers, which default to 'r'. + longtable : bool, optional + By default, the value will be read from the pandas config module. Use a longtable environment instead of tabular. Requires adding a \usepackage{longtable} to your LaTeX preamble. - escape : bool, default None - If None, default will be read from the pandas config module. - When set to False prevents from escaping latex special + escape : bool, optional + By default, the value will be read from the pandas config + module. When set to False prevents from escaping latex special characters in column names. - encoding : str, default None + encoding : str, optional A string representing the encoding to use in the output file, defaults to 'ascii' on Python 2 and 'utf-8' on Python 3. decimal : str, default '.' From c64fb5d22b09dd631cd493ce7e957d8e3809678d Mon Sep 17 00:00:00 2001 From: Thierry Moisan Date: Wed, 5 Sep 2018 14:24:12 -0400 Subject: [PATCH 4/4] Add a short summary to DataFrame.to_latex docstring --- pandas/core/generic.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index cf62dd6cbc54b..1e2c0e17dad53 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -2528,6 +2528,8 @@ def to_latex(self, buf=None, columns=None, col_space=None, header=True, encoding=None, decimal='.', multicolumn=None, multicolumn_format=None, multirow=None): r""" + Render an object to a LaTeX tabular environment table. + Render an object to a tabular environment table. You can splice this into a LaTeX document. Requires \usepackage{booktabs}.