pandas.io.formats.style.Styler.format — pandas 3.0.0.dev0+2097.gcdc5b7418e documentation (original) (raw)
Styler.format(formatter=None, subset=None, na_rep=None, precision=None, decimal='.', thousands=None, escape=None, hyperlinks=None)[source]#
Format the text display value of cells.
Parameters:
formatterstr, callable, dict or None
Object to define how values are displayed. See notes.
subsetlabel, array-like, IndexSlice, optional
A valid 2d input to DataFrame.loc[], or, in the case of a 1d input or single key, to DataFrame.loc[:, ] where the columns are prioritised, to limit data to before applying the function.
na_repstr, optional
Representation for missing values. If na_rep is None, no special formatting is applied.
precisionint, optional
Floating point precision to use for display purposes, if not determined by the specified formatter.
Added in version 1.3.0.
decimalstr, default “.”
Character used as decimal separator for floats, complex and integers.
Added in version 1.3.0.
thousandsstr, optional, default None
Character used as thousands separator for floats, complex and integers.
Added in version 1.3.0.
escapestr, optional
Use ‘html’ to replace the characters &, <, >, ', and "in cell display string with HTML-safe sequences. Use ‘latex’ to replace the characters &, %, $, #, _,{, }, ~, ^, and \ in the cell display string with LaTeX-safe sequences. Use ‘latex-math’ to replace the characters the same way as in ‘latex’ mode, except for math substrings, which either are surrounded by two characters $ or start with the character \( and end with \). Escaping is done before formatter.
Added in version 1.3.0.
hyperlinks{“html”, “latex”}, optional
Convert string patterns containing https://, http://, ftp:// or www. to HTML tags as clickable URL hyperlinks if “html”, or LaTeX href commands if “latex”.
Added in version 1.4.0.
Returns:
Styler
Returns itself for chaining.
Notes
This method assigns a formatting function, formatter, to each cell in the DataFrame. If formatter is None, then the default formatter is used. If a callable then that function should take a data value as input and return a displayable representation, such as a string. If formatter is given as a string this is assumed to be a valid Python format specification and is wrapped to a callable as string.format(x). If a dict is given, keys should correspond to column names, and values should be string or callable, as above.
The default formatter currently expresses floats and complex numbers with the pandas display precision unless using the precision argument here. The default formatter does not adjust the representation of missing values unless the na_rep argument is used.
The subset argument defines which region to apply the formatting function to. If the formatter argument is given in dict form but does not include all columns within the subset then these columns will have the default formatter applied. Any columns in the formatter dict excluded from the subset will be ignored.
When using a formatter string the dtypes must be compatible, otherwise aValueError will be raised.
When instantiating a Styler, default formatting can be applied by setting thepandas.options:
styler.format.formatter: default None.styler.format.na_rep: default None.styler.format.precision: default 6.styler.format.decimal: default “.”.styler.format.thousands: default None.styler.format.escape: default None.
Warning
Styler.format is ignored when using the output format Styler.to_excel, since Excel and Python have inherently different formatting structures. However, it is possible to use the number-format pseudo CSS attribute to force Excel permissible formatting. See examples.
Examples
Using na_rep and precision with the default formatter
df = pd.DataFrame([[np.nan, 1.0, 'A'], [2.0, np.nan, 3.0]]) df.style.format(na_rep='MISS', precision=3)
0 1 2 0 MISS 1.000 A 1 2.000 MISS 3.000
Using a formatter specification on consistent column dtypes
df.style.format('{:.2f}', na_rep='MISS', subset=[0, 1])
0 1 2 0 MISS 1.00 A 1 2.00 MISS 3.000000
Using the default formatter for unspecified columns
df.style.format({0: '{:.2f}', 1: '£ {:.1f}'}, ... na_rep='MISS', precision=1)
0 1 2 0 MISS £ 1.0 A 1 2.00 MISS 3.0
Multiple na_rep or precision specifications under the defaultformatter.
(df.style.format(na_rep='MISS', precision=1, subset=[0]).format( ... na_rep='PASS', precision=2, subset=[1, 2]))
0 1 2 0 MISS 1.00 A 1 2.0 PASS 3.00
Using a callable formatter function.
func = lambda s: 'STRING' if isinstance(s, str) else 'FLOAT' df.style.format({0: '{:.1f}', 2: func}, ... precision=4, na_rep='MISS')
0 1 2 0 MISS 1.0000 STRING 1 2.0 MISS FLOAT
Using a formatter with HTML escape and na_rep.
df = pd.DataFrame([['
', '"A&B"', None]]) s = df.style.format( ... '{0}', escape="html", na_rep="NA") s.to_html()
...
Using a formatter with escape in ‘latex’ mode.
df = pd.DataFrame([["123"], ["~ ^"], ["$%#"]]) df.style.format("\textbf{{{}}}", ... escape="latex").to_latex()
\begin{tabular}{ll} & 0 \ 0 & \textbf{123} \ 1 & \textbf{\textasciitilde \space \textasciicircum } \ 2 & \textbf{$%#} \ \end{tabular}
Applying escape in ‘latex-math’ mode. In the example below we enter math mode using the character $.
df = pd.DataFrame([ ... [r"$\sum_{i=1}^{10} a_i$ a~b α=βζ2\alpha = \frac{\beta}{\zeta^2}α=ζ2β"], ... [r"%#^ $ $x^2 $"]]) df.style.format(escape="latex-math").to_latex()
\begin{tabular}{ll} & 0 \ 0 & ∑i=110ai\sum_{i=1}^{10} a_i∑i=110ai a\textasciitilde b α=βζ2\alpha = \frac{\beta}{\zeta^2}α=ζ2β \ 1 & %#\textasciicircum \space $ $x^2 $ \ \end{tabular}
We can use the character \( to enter math mode and the character \)to close math mode.
df = pd.DataFrame([ ... [r"(\sum_{i=1}^{10} a_i) a~b (\alpha = \frac{\beta}{\zeta^2})"], ... [r"%#^ ( $x^2 )"]]) df.style.format(escape="latex-math").to_latex()
\begin{tabular}{ll} & 0 \ 0 & (\sum_{i=1}^{10} a_i) a\textasciitilde b (\alpha = \frac{\beta}{\zeta^2}) \ 1 & %#\textasciicircum \space ( $x^2 ) \ \end{tabular}
If we have in one DataFrame cell a combination of both shorthands for math formulas, the shorthand with the sign $ will be applied.
df = pd.DataFrame([ ... [r"( x^2 ) x2x^2x2"], ... [r"$\frac{\beta}{\zeta}$ (\frac{\beta}{\zeta})"]]) df.style.format(escape="latex-math").to_latex()
\begin{tabular}{ll} & 0 \ 0 & \textbackslash ( x\textasciicircum 2 \textbackslash ) x2x^2x2 \ 1 & βζ\frac{\beta}{\zeta}ζβ \textbackslash (\textbackslash frac{\textbackslash beta}{\textbackslash zeta}\textbackslash ) \ \end{tabular}
Pandas defines a number-format pseudo CSS attribute instead of the .formatmethod to create to_excel permissible formatting. Note that semi-colons are CSS protected characters but used as separators in Excel’s format string. Replace semi-colons with the section separator character (ASCII-245) when defining the formatting here.
df = pd.DataFrame({"A": [1, 0, -1]}) pseudo_css = "number-format: 0§Red§-§@;" filename = "formatted_file.xlsx" df.style.map(lambda v: pseudo_css).to_excel(filename)
